Deployment

Most people should use the desktop app or run Minara locally. Use Docker when you want a repeatable server setup with a persistent data volume.

Choose a deployment shape

Docker Compose stack

From a source checkout, start the full stack with:

pnpm docker

On the first run, Minara copies .env.example to .env and exits. Add at least your LLM provider credential and MINARA_API_KEY, then run the command again. The stack builds and starts:

• Web UI: http://localhost:5173
• Gateway: http://localhost:8080

Common operations:

pnpm docker:up        # start without rebuilding
pnpm docker:down      # stop containers and keep data
pnpm docker:logs      # follow combined logs
pnpm docker:rebuild   # rebuild images and start again

Use docker exec -it minara-agent node dist/gateway/cli.js when you need a terminal session against the running agent container.

Persistent data and upgrades

The Docker stack stores Minara state in a named volume. It contains SQLite data, audit records, workspace files, authentication profiles, and logs. Keep that volume when recreating containers.

Before a significant upgrade, back up the data volume or export the SQLite database. Then rebuild or replace the containers and keep the same volume attached. Database migrations run when the agent starts.

SQLite is designed for a single active writer. Run one state-owning agent against a volume. If you add replicas, route writes through that owner instead of mounting the same database into multiple independent writers.

Network and secrets

Keep the gateway on localhost unless you have a reason to expose it. A remote gateway can reach financial and account operations, so protect it with GATEWAY_AUTH_TOKEN and put a TLS-terminating reverse proxy in front of it.

Keep credentials outside the image. Use .env for local Docker Compose, your platform's secret store for hosted deployments, or injected runtime environment variables. Do not commit secrets or bake them into an image.

The gateway exposes GET /healthz for a basic container health check. Run minara doctor for a broader local configuration check.

Agent-only container

When you do not need the Web UI, build and run the agent image directly:

pnpm docker:build
pnpm docker:run

This exposes the gateway on port 8080 and mounts the minara-data volume. Provide credentials through the host environment or your deployment platform, never in the command history.

Before you go live

• Confirm that the data volume persists after a restart.
• Set daily and per-transaction limits appropriate to the account.
• Verify minara doctor and the gateway health check.
• Test the reverse proxy and authentication path before exposing the service.
• Start automation on paper or with a small allocation, then review its audit trail.