Skip to main content
Deploy and configure 2501 on your infrastructure using the 2501 infra CLI.

​
Install the CLI

Install the 2501 infra CLI on the machine that will run the deployment. Your 2501 account team provides the installer. Installation is a single self-contained step: it places a checksum-verified static binary, sets up a sudo wrapper so 2501 infra deploy runs privileged without you typing sudo, and runs a non-interactive setup so you finish with a ready-to-edit workspace. No Docker, AWS CLI, or registry login is required on the machine to install. Common installer options: --target kubernetes (instead of the default Docker Swarm), --user (install under your home directory with no sudo), and --version <tag> (pin a specific version).

​
Keeping the CLI current

There is no separate update command. The CLI stays in lockstep with the deployed platform version:
  • During deploy. Interactive 2501 infra deploy lists published releases newest-first. When you pick a version, the CLI self-updates its own binary to match (checksum-verified, then re-executed) before deploying.
  • CLI only. To refresh just the binary, re-run the installer. It is idempotent and never touches an existing workspace.

​
Quick start

After install, edit the two environment files before deploying. For a new installation, also review the initial tenant, organizations, and administrator in Users & Organizations.
1

Edit the engine environment

Open /etc/2501/env.engine and confirm the public Command Center URL. If you use your own PostgreSQL instance, set DATABASE_URL and DIRECT_URL (the direct connection used for migrations).
2

Edit the Command Center environment

Open /etc/2501/env.command-center and confirm its values, including the same public URL and external DATABASE_URL.
3

Deploy

deploy syncs your env files to the current version’s spec, runs database migrations, and brings up the stack.
For a new installation, sign in to Command Center and configure the LLM providers, models, and tenant defaults before running agents.
Most settings are defaulted for you. A plain Docker Swarm deployment with an external database needs no configuration file at all, just the two environment files above. See Configuration for when an optional 2501-infra.yml is written.

​
Upgrading

Upgrading is the same deploy command at a newer version. Point your Kubernetes manifests and/or 2501-infra.yml at the new image tag, depending on how you deployed, then apply. The Engine, the Command Center, and the executor images the Engine spawns all move to that tag together. Read the release notes for every version you are crossing before you start. Some releases add environment variables or carry breaking changes, which matters most when you are coming from an old version.
If 2501 manages PostgreSQL for you and you are upgrading from 0.13 or earlier, drop the unused vector extension first:
The database stopped using it in 0.9 and the new PostgreSQL image no longer carries it, so a dump that still declares the extension will not restore - including the backup you are about to take. Nothing 2501 owns depends on the extension, so the command succeeds unless you added vector columns of your own here. If it says something depends on it, keep the old PostgreSQL server or those columns stop reading: on Docker Swarm, pin postgres.image to pgvector/pgvector:pg16 in 2501-infra.yml; on Kubernetes that setting has no effect, so set the postgres container’s image to pgvector/pgvector:pg16 in the generated Deployment before you apply it.Then back up PostgreSQL, schema and data both:
Restoring that dump is what makes a downgrade possible. An Elasticsearch snapshot is optional.Keep automated backups for disaster recovery too, not just one dump before an upgrade. This matters most when 2501 manages PostgreSQL for you, rather than connecting to a database you already run and already back up.
Useful commands around an upgrade: On Kubernetes the CLI generates manifests rather than applying them, so it does not record what reached the cluster. Take your rollback target from the image tag in your manifests or from your GitOps history instead. Once the new version is up, check both health endpoints at the address your containers are exposed on:
The interactive version picker reads the release list from https://2501-public.s3.eu-west-3.amazonaws.com/cli-2501/versions.json. Allow egress to it if you want the picker; otherwise pass --tag <version> explicitly.

​
Plugins from the legacy runtime

Before upgrading, stop the old engine, let its calls and cleanup finish, and verify that its owned plugin containers or pods are gone. A forced stop may require targeted cleanup. Keep shared MCP services and independent executors running. The new runtime never starts the removed built-in MCPs, such as the GitHub and VMware ones: a plugin that used one reports Migration required and gives agents no tools until it is migrated, either by giving it an MCP endpoint (Add an endpoint in its editor, with the plugin turned off) or by adding its server again as a hosted MCP server. Of the containers and pods it runs, it deletes at start only the hosted MCP server ones its own engine left behind. Then give each such plugin its new server: see Give a legacy plugin an endpoint.

​
Rolling back

If the new version misbehaves, go back to the last one that worked and restore the data that went with it:
  • Redeploy the previous image tag.
  • Restore your PostgreSQL backup. If the failed upgrade already part-migrated the database, recreate it empty and restore into that.
  • Verify the stack is healthy before handing it back to users.
  • Contact 2501 with what went wrong and any details you still have, so we can debug it and ship a patch.
A restore rewinds your data to the moment the backup was taken. Some upgrades change the database in a way the previous version cannot read, so always restore the backup when you go back to an earlier version. On Docker Swarm, an engine update that fails is rolled back to the previous image on its own (swarm.rollback_on_failure, on by default), which puts the previous engine on the upgraded database: restore the backup then too.

​
Getting help

The CLI includes built-in documentation for all commands:

​
Deployment workflow

  1. Install the 2501 infra CLI (setup runs automatically)
  2. Edit env.engine and env.command-center with your human-required values
  3. Deploy with 2501 infra deploy
  4. Create entities (the CLI prompts you interactively; skipped with --yes)
  5. Access the Command Center UI

​
What’s Next

Init Command

Initialize your deployment

Configuration

Overview of configuration files

Docker Swarm

Deploy to production

Troubleshooting

Common issues and solutions