Deployment model

Mango currently publishes a reproducible local stack and builds a multi-role application image. It does not yet publish a supported production Docker Compose bundle or Kubernetes chart.

Supported assets

Asset	Status	Intended use
Root Dockerfile	Buildable	Produce the API/worker image on Linux AMD64 or ARM64
deployments/local/compose.yaml	Development	Run PostgreSQL, Temporal, NATS, MinIO, API, and worker from the current checkout
Production Docker Compose	Planned	Supported single-host installation using versioned release images
Helm chart	Planned	Kubernetes API and worker deployments with external stateful dependencies

The local stack is intentionally complete so contributors can exercise the durable path without installing each dependency. It contains development credentials, fixed host ports, and stateful dependencies and must not be treated as a high-availability or hardened production configuration.

Process topology

One immutable image serves two independently scalable roles:

mango serve -addr :8080
mango orchestrate

The API refuses to start without an active Workspace key. Set MANGO_API_KEY to bootstrap or rotate the default Workspace key, or manage additional Workspaces and keys through the operator CLI:

mango workspace create -name acme
mango api-key create -workspace wrkspc_... -label production

The plaintext generated key is printed only by api-key create; PostgreSQL stores its SHA-256 digest. API and worker processes share Workspace ownership through PostgreSQL, but only the API needs request credentials.

The API owns HTTP resources, SSE, event admission, and client Files metadata/object coordination. The worker owns Temporal Workflow/Activity execution, model calls, sandbox tools, File Resource materialization, Session output publication, and the outbox relay. They share a release artifact but not a scaling or rollout policy.

Files add an S3-compatible dependency beside PostgreSQL, Temporal, and NATS. Set MANGO_FILE_S3_BUCKET to enable the five Files routes; leaving it empty keeps the rest of the API available and makes Files requests return 422. Failure to initialize or reconcile the configured object store also disables only Files so the Managed Agents core remains available. The API process uses these settings for uploads and File-message admission. A worker that starts Deployment Runs containing File messages or File outcome rubrics, materializes Session File Resources, or publishes /mnt/session/outputs must use the same bucket, endpoint, region, and credentials (it does not run startup intent reconciliation):

Variable	Meaning
MANGO_FILE_S3_BUCKET	Required bucket name; empty disables Files
MANGO_FILE_S3_REGION	AWS region; defaults to us-east-1
MANGO_FILE_S3_ENDPOINT	Optional S3-compatible endpoint
MANGO_FILE_S3_ACCESS_KEY / MANGO_FILE_S3_SECRET_KEY	Optional static credentials; configure both together
MANGO_FILE_S3_PATH_STYLE	Use path-style addressing for providers such as MinIO
MANGO_FILE_S3_CREATE_BUCKET	Development convenience; create a missing bucket
MANGO_FILE_UPLOAD_TEMP_DIR	Directory for bounded upload spool files

The first Files slice assumes one Files-enabled API process during startup reconciliation. It also needs temporary disk capacity up to 500 MB per concurrent upload, Session Resource copy, or Session output publication. These are explicit limits until distributed intent leasing and direct multipart object-store operations are implemented.

File-backed Session Resources and automatic Session output publication additionally require MANGO_SANDBOX=docker. The worker must run where the selected Docker Engine API is reachable; the provider uses the Moby Go client directly and does not require a docker CLI binary. Configure a non-default daemon with DOCKER_HOST and the standard Docker TLS environment variables. The daemon must be able to bind the worker's provider-owned staging directory. Set MANGO_SANDBOX_RESOURCE_DIR to place that directory on a dedicated host volume; the default is mango-resources beneath the process user's home directory. The API and every worker on the task queue must agree on the sandbox provider and object-store configuration. The local-process provider and current remote adapters reject File Resources because they cannot yet provide the same isolated, absolute, read-only mount contract.

Memory API contents and immutable Versions live entirely in PostgreSQL and do not require S3-compatible storage. Memory-backed Session Resources do require MANGO_SANDBOX=docker: the API snapshots each attachment, and the worker bind-mounts it beneath /mnt/memory, then synchronizes tool changes back to PostgreSQL. API and worker processes must select the same provider. Local, self-hosted, and current remote adapters reject Memory Store attachment while the standalone Memory API remains available.

The Vault API is disabled unless MANGO_VAULT_KEYRING_FILE points to an operator-mounted JSON keyring. A configured but invalid keyring fails API startup rather than falling back to plaintext storage. The file has this shape:

{
  "active_key_id": "2026-08",
  "keys": {
    "2026-08": "<standard-base64 32-byte AES key>",
    "2026-07": "<retained decrypt-only key>"
  }
}

New Credentials and secret/auth updates use the active key. Older keys may remain in the file for reads during rotation; removing one makes Credentials encrypted by that key unavailable. Both the API and worker processes must load the same keyring: the API encrypts and admits Session Vault references, while workers decrypt matching credentials immediately before MCP requests. It must never be mounted into a Session sandbox, copied into Agent context, or stored in PostgreSQL. The bundled local keyring is deterministic development material and must not be reused outside the local Compose stack.

Before production deployment bundles are promoted, database migration will be removed from normal API/worker startup and exposed as an explicit one-shot role. This avoids every replica racing to manage schema during a rollout.

Repository commands

Run core checks:

make verify

Build and smoke-test the container entrypoint:

make image-smoke

Builders behind a restricted network can pass a standard Go module proxy without changing the Dockerfile:

make image-smoke GOPROXY=https://proxy.example.com,direct

Validate and start the local stack:

make local-config
make local-up
make local-health

Stop it while retaining PostgreSQL and MinIO data:

make local-down

Set VOLUMES=1 only when all local state should be removed:

make local-down VOLUMES=1

Production promotion gates

A supported Docker or Kubernetes bundle requires:

1. explicit, versioned schema migration;
2. dependency-aware API and worker readiness;
3. graceful API shutdown and worker draining;
4. repeatable live conformance for remote sandbox adapters;
5. real PostgreSQL, Temporal, NATS, S3-compatible storage, and sandbox integration tests in CI;
6. distributed Files reconciliation and documented temporary-disk sizing;
7. versioned images with upgrade and rollback documentation.

Kubernetes packaging will use separate API and worker Deployments from the same image. Stateful services remain external by default. An Operator is not part of the initial deployment model and will be considered only if Mango introduces Kubernetes-native custom resources that require reconciliation.