Skip to main content
Deploy 2501 with the release’s compose.yaml, your .env settings and Docker secrets. Keep site-specific changes in a separate site.yaml so they survive upgrades.

​
Prepare the Swarm

1

Download the build

Get compose.yaml and env.example from installation releases. Verify the files.
2

Prepare Docker

Use Docker 23.0 or newer on every node. Initialize the Swarm if needed and join its nodes.
3

Choose the data node

Run docker node update --label-add 2501-data=true <node> for the node that stores the supplied PostgreSQL database.
4

Copy the release images

Copy every image into your registry under the same paths and digests. Set its prefix as IMAGE_REGISTRY below.
The engine runs on a manager and needs access to its Docker socket. Database volumes are local to the labelled data node. See registry access for image copying; 2501’s registry login expires after 12 hours and Swarm cannot renew it. List the images to copy from the release file:

​
Write your .env

Copy env.example to .env beside compose.yaml. Use Docker secrets for passwords and keys. The first three variables are required. Identity and LLM values initialize a new installation only; change them later in Command Center. Without initial LLM settings, add a model after sign-in. See the configuration reference for other settings.

​
Create the secrets

Run the secret-creation commands at the top of compose.yaml on a manager, after replacing every placeholder. Existing secrets are skipped. Before the first deploy, remove and recreate any secret accidentally made with a placeholder. Create llm-api-key-v1 even without LLM settings; any value is sufficient when those settings are absent because the stack still mounts the secret.
Preserve the credential key, engine API key, authentication secret, log encryption key and database password across upgrades. Replacing them can make existing data inaccessible. Never commit secret values.

​
Deploy

Load the settings and sign in to your registry:
If you use site.yaml, add -c site.yaml to both stack commands. Review the merged configuration before deploying. Pruning removes services dropped by a build and retains data volumes. The bootstrap service migrates the database and initializes missing identity and model settings. It retries while the database starts. Investigate persistent migration errors in its logs instead of treating a running web service as a completed installation. Bootstrap retries stop at the configured limit of 10 attempts. Fix the cause shown in the logs, then remove the failed bootstrap service and redeploy the stack:
Include -c site.yaml again if you use it.

​
Adapt to your site

Keep the published compose.yaml unchanged. Start site.yaml with its version: value and merge the required recipes below. Apply with both files after each change.
Create the CA configuration with docker config create corporate-ca corporate-ca.pem:
Keep only the proxy or CA lines if you need one. Add your internal domains to NO_PROXY.
Issue a certificate for engine. Create Docker secrets engine-tls.tls.crt and engine-tls.tls.key from its certificate and key:
With a corporate CA too, list both paths in CA_BUNDLE_FILES, separated by a space. Renew certificates under new secret names and update the references.
Create pg-connection-v1.DATABASE_URL and pg-connection-v1.DIRECT_URL as Docker secrets containing your connection strings with TLS verification. The direct URL bypasses any pooler.
Keep postgres-password-v1: services still mount it. Check the bootstrap logs after deploying.

​
Check

Swarm’s supplied health check uses /health; it does not wait for database readiness. Check /ready separately before opening access. After its first success, readiness remains successful even during a later database outage. Sign in at https://<your host>. The engine stops before its replacement starts during upgrades; allow running tasks to finish first.

​
gMSA hosts

For Windows targets using gMSA, the engine’s manager must reach domain controllers over LDAPS and Kerberos. Include the build’s kerberos-worker image when copying release images. The worker starts automatically when needed. The worker service is separate from the stack. If the engine did not stop cleanly before docker stack rm, remove the remaining worker with docker service rm kerberos-worker.

​
Hosted MCP servers

Hosted plugins run as containers on the engine’s manager. Supply private-registry access in the registry-auth secret’s Docker config.json, or pre-pull images on each manager. After the hosted network first exists, apply isolation on every eligible manager before assigning production work:
These rules block private destinations and the manager itself. Arrange persistent firewall rules and review them if the Docker network changes. Add narrowly scoped exceptions for required internal services. Reserve manager capacity for plugin containers alongside the engine.

​
Centrals

Local Centrals need a dedicated internal, non-attachable overlay network and a controlled dialback proxy. Configure CENTRAL_LOCAL_SWARM_NETWORK and CENTRAL_LOCAL_SWARM_PROXY in the engine’s site.yaml environment. Set CENTRAL_LOCAL_DIALBACK_URL to the engine’s reachable HTTPS address. The network and proxy settings must contain {org_id} for organization-specific routing. The standard stack does not provision this environment. Use the preparation recipe below, or select a registered cluster that meets these requirements. Run the Central’s dry run before assigning work; it checks execution and cleanup, not task credentials.
Centrals require Docker Engine API 1.47 or newer and registry access at each launch. Prepare a separate network per organization. Use your actual tenant and organization IDs for TENANT_ID and ORG_ID below.
1

Create the dedicated network

Use the command below only after your site has qualified the proxy and network filtering. Do not attach application infrastructure or Host executors.
2

Deploy your controlled proxy

Attach your approved proxy service to the network. Give the service the labels below, using the same tenant and organization IDs.
3

Verify isolation

Permit the installation’s HTTPS callback and required tool destinations through the proxy. Verify denial of private infrastructure, metadata and unwanted incoming traffic before approving this network.
4

Configure and test

Set the engine environment below in site.yaml, redeploy, then run the Central’s Test in Dry run and confirm cleanup.
Proxy service labels belong under deploy.labels in its Compose definition:
Labels record your verification; they do not implement filtering. Swarm permits traffic between tasks on the same overlay. Provide and verify an external filter if you require task-to-task isolation.
Replace the proxy and callback addresses with your reachable services. The callback certificate must be trusted. Use a separate proxy service for each organization, with its corresponding network and labels. Requalify the setup after network or proxy changes before admitting more Central work.