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, you typically only need to edit two environment files before deploying.
1

Edit the engine environment

Open /etc/2501/env.engine and set the human-required values, such as your LLM provider API keys and the external DATABASE_URL.
2

Edit the Command Center environment

Open /etc/2501/env.command-center and confirm its values.
3

Deploy

deploy syncs your env files to the current version’s spec, runs database migrations, and brings up the stack.
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.
Back up PostgreSQL first, 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.
Commands worth knowing 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.

​
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.

​
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