{"id":32695,"date":"2026-08-03T11:44:16","date_gmt":"2026-08-03T09:44:16","guid":{"rendered":"https:\/\/contabo.com\/blog\/?p=32695"},"modified":"2026-08-03T11:44:19","modified_gmt":"2026-08-03T09:44:19","slug":"how-to-deploy-agency-orchestrator-on-a-vps-self-hosted-ai-agent-workflows","status":"publish","type":"post","link":"https:\/\/contabo.com\/blog\/how-to-deploy-agency-orchestrator-on-a-vps-self-hosted-ai-agent-workflows\/","title":{"rendered":"How to Deploy agency-orchestrator on a VPS: Self-Hosted AI Agent Workflows"},"content":{"rendered":"\n

In short.<\/strong> 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.<\/p>\n\n\n\n

What Is agency-orchestrator and How Does It Relate to agency-agents?<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

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.<\/p>\n\n\n\n

Requirements<\/h2>\n\n\n\n

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.<\/p>\n\n\n\n

    \n
  • 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<\/li>\n\n\n\n
  • 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<\/li>\n\n\n\n
  • Docker Engine and the Docker Compose plugin<\/li>\n\n\n\n
  • A domain name and Caddy for HTTPS (optional, recommended for the web Studio)<\/li>\n\n\n\n
  • 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<\/li>\n<\/ul>\n\n\n\n

    Step 1: Provision and Secure Your VPS<\/h2>\n\n\n\n

    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.<\/p>\n\n\n\n

      \n
    1. Create a Contabo Cloud VPS 8, pick your region, and select Ubuntu 24.04 LTS.<\/li>\n\n\n\n
    2. SSH in as root: ssh root@<your-ip><\/code><\/li>\n\n\n\n
    3. Create a non-root user: adduser ao && usermod -aG sudo ao<\/code><\/li>\n\n\n\n
    4. Set up SSH key authentication and disable password authentication.<\/li>\n\n\n\n
    5. Configure UFW to allow SSH (22), HTTP (80), HTTPS (443), and the Studio port (8088, restricted to your IP or proxied behind Caddy).<\/li>\n\n\n\n
    6. Enable the firewall.<\/li>\n<\/ol>\n\n\n\n
      ufw enable<\/code><\/pre>\n\n\n\n
      Step 2: Install Docker and Docker Compose<\/h2>\n\n\n\n
      agency-orchestrator ships as a Docker image, so this AI agent deployment starts with Docker Engine and the Compose plugin.<\/p>\n\n\n\n
      apt update && apt install -y ca-certificates curl gnupg\ninstall -m 0755 -d \/etc\/apt\/keyrings\ncurl -fsSL https:\/\/download.docker.com\/linux\/ubuntu\/gpg | gpg --dearmor -o \/etc\/apt\/keyrings\/docker.gpg\necho \"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\napt update && apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin\nsystemctl enable --now docker\nusermod -aG docker ao<\/code><\/pre>\n\n\n\n
      Verify the install:<\/p>\n\n\n\n
      docker run hello-world<\/code><\/pre>\n\n\n\n
      Step 3: Deploy agency-orchestrator with Docker<\/h2>\n\n\n\n
      Two paths get agency-orchestrator, and the agency-agents personas it runs, going on your VPS: a single docker run<\/code> command for a quick test, or Docker Compose for an AI agent deployment you intend to keep.<\/p>\n\n\n\n
      Quickstart:<\/p>\n\n\n\n
      docker run -d \\\n  --name agency-orchestrator \\\n  --restart unless-stopped \\\n  -p 8088:8088 \\\n  -v ao-data:\/data \\\n  ghcr.io\/jnmetacode\/agency-orchestrator:latest<\/code><\/pre>\n\n\n\n
      Docker Compose (recommended for production, since it includes volume mounts for output and persistent config):<\/p>\n\n\n\n
      git clone https:\/\/github.com\/jnMetaCode\/agency-orchestrator.git\ncd agency-orchestrator\ndocker compose up -d<\/code><\/pre>\n\n\n\n
      Verify with curl http:\/\/localhost:8088<\/code>, which should return the web Studio HTML. The image tag, port, and provider environment variables (DEEPSEEK_API_KEY<\/code>, ANTHROPIC_API_KEY<\/code>, AO_DATA_DIR<\/code>) shown above are confirmed against the current live documentation.<\/p>\n\n\n\n
      Step 4: Configure Your LLM Provider and API Keys<\/h2>\n\n\n\n
      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.<\/p>\n\n\n\n
      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.<\/p>\n\n\n\n
      # In docker run or docker-compose.yml\nDEEPSEEK_API_KEY=your_key_here\n# Or for Anthropic\nANTHROPIC_API_KEY=your_key_here<\/code><\/pre>\n\n\n\n
      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.<\/p>\n\n\n\n
      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.<\/p>\n\n\n\n
      Step 5: Expose the Web Studio with Caddy and HTTPS<\/h2>\n\n\n\n
      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.<\/p>\n\n\n\n
      ao.yourdomain.com {\n    reverse_proxy localhost:8088\n    basicauth \/* {\n        # Generate with: caddy hash-password\n        admin $2a$14$...\n    }\n}<\/code><\/pre>\n\n\n\n
        \n
      1. Install Caddy: apt install -y caddy<\/code><\/li>\n\n\n\n
      2. Create the Caddyfile above at \/etc\/caddy\/Caddyfile<\/code>.<\/li>\n\n\n\n
      3. Reload Caddy: systemctl reload caddy<\/code><\/li>\n\n\n\n
      4. Visit https:\/\/ao.yourdomain.com<\/code>. The Studio should load over HTTPS.<\/li>\n<\/ol>\n\n\n\n
        The Studio holds your LLM API keys, so protect it with basic-auth or restrict access to a VPN or a known IP range.<\/p>\n\n\n\n
        Step 6: Run Your First Multi-Agent Workflow<\/h2>\n\n\n\n
        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.<\/p>\n\n\n\n
        Through the web Studio, no code required:<\/p>\n\n\n\n
          \n
        1. Open https:\/\/ao.yourdomain.com<\/code>.<\/li>\n\n\n\n
        2. Type a one-sentence prompt, for example “Analyze the feasibility of a SaaS invoicing tool for freelancers.”<\/li>\n\n\n\n
        3. Click Run. agency-orchestrator selects roles automatically and executes a DAG workflow.<\/li>\n\n\n\n
        4. Check the Outputs tab for results.<\/li>\n<\/ol>\n\n\n\n
          Through the CLI, inside the container:<\/p>\n\n\n\n
          docker exec -it agency-orchestrator npx ao compose \\\n  \"PR code review covering security and performance\" \\\n  --run<\/code><\/pre>\n\n\n\n
          Through MCP, the officially documented pattern connects Claude Code or Cursor to an ao serve<\/code> instance running on the same machine:<\/p>\n\n\n\n
          {\n  \"mcpServers\": {\n    \"agency-orchestrator\": {\n      \"command\": \"npx\",\n      \"args\": [\"agency-orchestrator\", \"serve\"]\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
          Step 7: Persist Outputs and Automate Backups<\/h2>\n\n\n\n
          Your self-hosted AI agent writes every result to ao-output\/<\/code> inside the Docker volume mounted at \/data<\/code>, and a daily backup keeps that data safe off the VPS.<\/p>\n\n\n\n
          docker exec agency-orchestrator tar czf - \/data\/ao-output | \\\n  s3cmd put - s3:\/\/your-bucket\/ao-backup-$(date +%Y%m%d).tar.gz<\/code><\/pre>\n\n\n\n
          Schedule it as a cron job on the VPS host:<\/p>\n\n\n\n
          0 2 * * * \/path\/to\/backup-script.sh<\/code><\/pre>\n\n\n\n
          Troubleshooting Common Deployment Issues<\/h2>\n\n\n\n
          Most agency-orchestrator deployment problems trace back to three causes.<\/p>\n\n\n\n
          The container starts and immediately exits. Check docker logs agency-orchestrator<\/code> 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.<\/p>\n\n\n\n
          The web Studio is unreachable at your domain. Confirm UFW allows ports 80 and 443, that Caddy reloaded without errors (systemctl status caddy<\/code>), and that the Caddyfile’s reverse_proxy<\/code> line points at localhost:8088<\/code>.<\/p>\n\n\n\n
          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.<\/p>\n\n\n\n
          FAQ: agency-orchestrator on a VPS<\/h2>\n\n\n\n
          What is the difference between agency-agents and agency-orchestrator?<\/strong> 
          agency-agents, built by msitarzewski, is a library of 184 specialist AI persona files: markdown prompts you install into Claude Code, Cursor, or another coding tool. There is no server and nothing to deploy. agency-orchestrator, built by jnMetaCode, is the separate AI agent framework that uses those personas as its role library and adds a workflow engine, parallel execution, a web Studio, and a Docker image. This guide deploys agency-orchestrator.<\/p> <\/div> 
          How much RAM do I need to run agency-orchestrator on a VPS?<\/strong> 
          For API-based providers such as DeepSeek, Claude, or OpenAI, this self-hosted AI agent is lightweight, and a Contabo Cloud VPS 4 (4 vCPU, 8 GB RAM) handles most workflows. Choose Cloud VPS 8 (8 vCPU, 24 GB RAM) for complex parallel workflows, or to host other services alongside it. Local Ollama inference with 13B-parameter models or larger calls for a Cloud VDS S (6 dedicated vCores, 24 GB RAM) instead.<\/p> <\/div> 
          Can I run agency-orchestrator without an API key?<\/strong> 
          Yes, for local development. agency-orchestrator supports seven key-free providers, including Claude Code, Gemini CLI, GitHub Copilot, and Codex CLI, which route requests through an existing subscription CLI. On a headless VPS, though, key-free modes need an interactive authentication session that is impractical to maintain. For always-on VPS deployment, an API key provider such as DeepSeek, Anthropic, or OpenAI is the recommended choice.<\/p> <\/div> 
          What LLM providers does agency-orchestrator support?<\/strong> 
          agency-orchestrator supports 10 providers in total: DeepSeek, Claude (API), OpenAI, and seven key-free options, Claude Code (Claude Pro\/Max subscription), Gemini CLI (a free tier of 1,000 requests per day on Gemini 2.5 Pro), GitHub Copilot (Copilot subscription), Codex CLI (ChatGPT Plus\/Pro), OpenClaw, Hermes Agent, and Ollama for local models. Any OpenAI-compatible endpoint also works through a custom base URL.<\/p> <\/div> 
          Is agency-orchestrator free to use?<\/strong> 
          agency-orchestrator is open source under the Apache-2.0 license, free to use, modify, and self-host. What costs money is the LLM traffic behind it, and that depends on your provider choice. DeepSeek is the most cost-efficient API option, while key-free providers such as Claude Code or Gemini CLI cost nothing extra if you already hold the underlying subscription.<\/p> <\/div> <\/div>\n","protected":false},"excerpt":{"rendered":"
          Deploy agency-orchestrator on a Contabo VPS with Docker, configure an LLM provider, secure the web Studio with HTTPS, run multi-agent workflows, and automate backups.<\/p>\n","protected":false},"author":63,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"inline_featured_image":false,"_uag_custom_page_level_css":"","site-sidebar-layout":"default","site-content-layout":"","ast-site-content-layout":"default","site-content-style":"default","site-sidebar-style":"default","ast-global-header-display":"","ast-banner-title-visibility":"","ast-main-header-display":"","ast-hfb-above-header-display":"","ast-hfb-below-header-display":"","ast-hfb-mobile-header-display":"","site-post-title":"","ast-breadcrumbs-content":"","ast-featured-img":"","footer-sml-layout":"","ast-disable-related-posts":"","theme-transparent-header-meta":"","adv-header-id-meta":"","stick-header-meta":"","header-above-stick-meta":"","header-main-stick-meta":"","header-below-stick-meta":"","astra-migrate-meta-layouts":"set","ast-page-background-enabled":"default","ast-page-background-meta":{"desktop":{"background-color":"var(--ast-global-color-4)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"ast-content-background-meta":{"desktop":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"tablet":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""},"mobile":{"background-color":"var(--ast-global-color-5)","background-image":"","background-repeat":"repeat","background-position":"center center","background-size":"auto","background-attachment":"scroll","background-type":"","background-media":"","overlay-type":"","overlay-color":"","overlay-opacity":"","overlay-gradient":""}},"footnotes":"","_members_access_role":[],"_members_access_error":""},"categories":[18],"tags":[3316,3439,1552],"ppma_author":[1492],"class_list":["post-32695","post","type-post","status-publish","format-standard","hentry","category-tutorials","tag-ai-workflow-automation","tag-ai-workloads","tag-application-deployment"],"uagb_featured_image_src":{"full":false,"thumbnail":false,"medium":false,"medium_large":false,"large":false,"1536x1536":false,"2048x2048":false},"uagb_author_info":{"display_name":"Christopher Carter","author_link":"https:\/\/contabo.com\/blog\/author\/christophercarter\/"},"uagb_comment_info":0,"uagb_excerpt":"Deploy agency-orchestrator on a Contabo VPS with Docker, configure an LLM provider, secure the web Studio with HTTPS, run multi-agent workflows, and automate backups.","authors":[{"term_id":1492,"user_id":63,"is_guest":0,"slug":"christophercarter","display_name":"Christopher Carter","avatar_url":"https:\/\/secure.gravatar.com\/avatar\/63db81672a5ce4c1e8ee39753d00251d561b5b3a9967febf1c4f662024cef00f?s=96&d=mm&r=g","author_category":"","user_url":"","last_name":"Carter","first_name":"Christopher","job_title":"","description":""}],"_links":{"self":[{"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/posts\/32695","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/users\/63"}],"replies":[{"embeddable":true,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/comments?post=32695"}],"version-history":[{"count":1,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/posts\/32695\/revisions"}],"predecessor-version":[{"id":32697,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/posts\/32695\/revisions\/32697"}],"wp:attachment":[{"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/media?parent=32695"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/categories?post=32695"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/tags?post=32695"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/contabo.com\/blog\/wp-json\/wp\/v2\/ppma_author?post=32695"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}