How to Deploy agency-orchestrator on a VPS: Self-Hosted AI Agent Workflows

In short. agency-agents is a library of specialist AI personas, and agency-orchestrator is the AI agent framework that runs them as an always-on, self-hosted AI agent server. One sentence, or a YAML workflow, sends multiple AI experts to work in parallel on a single deliverable. This guide is an AI agent deployment walkthrough for putting agency-orchestrator on a Contabo VPS with Docker, reachable from any device. Plan for about 25 minutes on a Cloud VPS 8.

What Is agency-orchestrator and How Does It Relate to agency-agents?

agency-orchestrator is the AI agent framework that turns the agency-agents persona library into an always-on multi-agent server you can run on a VPS. The two projects are often confused, so it is worth separating them before you deploy anything.

agency-agents, built by msitarzewski and MIT licensed, is a library of 184 English specialist AI persona files, with 129,000+ GitHub stars as of this writing. Each persona is a markdown prompt you install into Claude Code, Cursor, GitHub Copilot, or a similar coding tool. There is no server component here and nothing to deploy: agency-agents lives entirely inside your local coding assistant.

agency-orchestrator, built by jnMetaCode and Apache-2.0 licensed, is a separate project that uses those same agency-agents personas as its AI roles, alongside a companion Chinese-language persona library it maintains itself. It adds a YAML-based workflow engine, DAG-based parallel execution, support for 10 LLM providers, and a web Studio interface, then ships the combination as a Docker image. As an open source AI agent, agency-orchestrator is what runs on a VPS, and it is what this guide deploys.

Running it on a VPS instead of a laptop, as an AI agent deployment, changes four things: your workflows stay always-on, they can be triggered by API or MCP calls from a CI/CD pipeline, their outputs persist in one fixed location, and the whole setup is reachable from any device on the network.

Requirements

This AI agent deployment needs a VPS, Docker, and access to one of ten supported LLM providers to run as a self-hosted AI agent.

• Contabo Cloud VPS 8 (8 vCPU Cores, 24 GB RAM, 300 GB SSD) for multi-parallel workflows with API-based providers, or Cloud VPS 4 (4 vCPU Cores, 8 GB RAM) for lighter workflows using key-free providers such as Claude Code or Gemini CLI
• Contabo Cloud VDS S (6 dedicated vCores, AMD EPYC 7282, 24 GB RAM, 180 GB NVMe) if you plan to run local Ollama inference with 13B-parameter models or larger
• Docker Engine and the Docker Compose plugin
• A domain name and Caddy for HTTPS (optional, recommended for the web Studio)
• One LLM access method: an Anthropic, DeepSeek, or OpenAI API key, or an existing Claude Pro/Max, Gemini, or GitHub Copilot subscription for key-free access

Step 1: Provision and Secure Your VPS

This step gets you a hardened Ubuntu server ready to run your self-hosted AI agent under Docker, the foundation this AI agent deployment builds on.

1. Create a Contabo Cloud VPS 8, pick your region, and select Ubuntu 24.04 LTS.
2. SSH in as root: ssh root@<your-ip>
3. Create a non-root user: adduser ao && usermod -aG sudo ao
4. Set up SSH key authentication and disable password authentication.
5. Configure UFW to allow SSH (22), HTTP (80), HTTPS (443), and the Studio port (8088, restricted to your IP or proxied behind Caddy).
6. Enable the firewall.

ufw enable

Step 2: Install Docker and Docker Compose

agency-orchestrator ships as a Docker image, so this AI agent deployment starts with Docker Engine and the Compose plugin.

apt update && apt install -y ca-certificates curl gnupg
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null
apt update && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
systemctl enable --now docker
usermod -aG docker ao

Verify the install:

docker run hello-world

Step 3: Deploy agency-orchestrator with Docker

Two paths get agency-orchestrator, and the agency-agents personas it runs, going on your VPS: a single docker run command for a quick test, or Docker Compose for an AI agent deployment you intend to keep.

Quickstart:

docker run -d \
  --name agency-orchestrator \
  --restart unless-stopped \
  -p 8088:8088 \
  -v ao-data:/data \
  ghcr.io/jnmetacode/agency-orchestrator:latest

Docker Compose (recommended for production, since it includes volume mounts for output and persistent config):

git clone https://github.com/jnMetaCode/agency-orchestrator.git
cd agency-orchestrator
docker compose up -d

Verify with curl http://localhost:8088, which should return the web Studio HTML. The image tag, port, and provider environment variables (DEEPSEEK_API_KEY, ANTHROPIC_API_KEY, AO_DATA_DIR) shown above are confirmed against the current live documentation.

Step 4: Configure Your LLM Provider and API Keys

agency-orchestrator reaches its agency-agents personas through one of two provider modes: an API key, or a key-free CLI proxy. Whichever you pick decides how reliably this AI agent deployment keeps your self-hosted AI agent running unattended.

Option A, API key providers, is the practical choice for a headless VPS. DeepSeek is a cost-efficient default; Anthropic and OpenAI both work the same way.

# In docker run or docker-compose.yml
DEEPSEEK_API_KEY=your_key_here
# Or for Anthropic
ANTHROPIC_API_KEY=your_key_here

Option B, key-free providers such as Claude Code or Gemini CLI, route requests through an existing subscription. They need an interactive authentication session, which is straightforward on a local machine but awkward to maintain on a headless VPS. For always-on deployment, an API key provider is the more reliable choice.

Either way, keys are entered once in the web Studio’s Providers page and stored in the mounted volume, so they persist across container restarts.

Step 5: Expose the Web Studio with Caddy and HTTPS

Putting the web Studio behind Caddy gives your self-hosted AI agent a real domain and HTTPS with basic-auth protection in a handful of steps.

ao.yourdomain.com {
    reverse_proxy localhost:8088
    basicauth /* {
        # Generate with: caddy hash-password
        admin $2a$14$...
    }
}

1. Install Caddy: apt install -y caddy
2. Create the Caddyfile above at /etc/caddy/Caddyfile.
3. Reload Caddy: systemctl reload caddy
4. Visit https://ao.yourdomain.com. The Studio should load over HTTPS.

The Studio holds your LLM API keys, so protect it with basic-auth or restrict access to a VPN or a known IP range.

Step 6: Run Your First Multi-Agent Workflow

As an AI agent framework, agency-orchestrator accepts a workflow through the web Studio, the CLI, or an MCP connection to an AI coding agent such as Claude Code or Cursor, and all three trigger the same underlying agency-agents persona dispatch.

Through the web Studio, no code required:

1. Open https://ao.yourdomain.com.
2. Type a one-sentence prompt, for example “Analyze the feasibility of a SaaS invoicing tool for freelancers.”
3. Click Run. agency-orchestrator selects roles automatically and executes a DAG workflow.
4. Check the Outputs tab for results.

Through the CLI, inside the container:

docker exec -it agency-orchestrator npx ao compose \
  "PR code review covering security and performance" \
  --run

Through MCP, the officially documented pattern connects Claude Code or Cursor to an ao serve instance running on the same machine:

{
  "mcpServers": {
    "agency-orchestrator": {
      "command": "npx",
      "args": ["agency-orchestrator", "serve"]
    }
  }
}

Step 7: Persist Outputs and Automate Backups

Your self-hosted AI agent writes every result to ao-output/ inside the Docker volume mounted at /data, and a daily backup keeps that data safe off the VPS.

docker exec agency-orchestrator tar czf - /data/ao-output | \
  s3cmd put - s3://your-bucket/ao-backup-$(date +%Y%m%d).tar.gz

Schedule it as a cron job on the VPS host:

0 2 * * * /path/to/backup-script.sh

Troubleshooting Common Deployment Issues

Most agency-orchestrator deployment problems trace back to three causes.

The container starts and immediately exits. Check docker logs agency-orchestrator first. A missing or malformed API key environment variable is the most common cause, so confirm the variable name matches the ones confirmed in Step 3.

The web Studio is unreachable at your domain. Confirm UFW allows ports 80 and 443, that Caddy reloaded without errors (systemctl status caddy), and that the Caddyfile’s reverse_proxy line points at localhost:8088.

A key-free provider fails with an authentication error. This is expected on a headless VPS. Switch to an API key provider (Step 4) rather than troubleshooting an interactive CLI session with no display.

FAQ: agency-orchestrator on a VPS