Self-host Agno AgentOS on your own VM
Agno agents as durable services, with PostgreSQL, on a private VM.
Shelley handles the setup. About 15 minutes.
Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/agno-agentos/prompt.txt | ssh exe.dev new --prompt=/dev/stdinAgno is a Python framework for agents, teams, and workflows, and AgentOS is its runtime: a FastAPI server that runs them as durable services, with sessions, memory, knowledge, approvals, schedules, and traces in PostgreSQL. The agentos-docker template packages it as a working platform: Super Agent, which runs your agents and builds new ones; Company, for scheduled routines and tasks; an MCP server; and Claude Code and Codex as agents you can turn on. You manage it from the AgentOS UI at os.agno.com, which talks to your AgentOS straight from your browser.
An exe.dev VM runs the template's Docker Compose stack around the clock, private behind exe.dev login, with PostgreSQL on the VM's disk. Models come from exe.dev's LLM integration, so no OpenAI or Anthropic key is on the VM, and Claude and Codex work in a checkout of the platform itself.
What you get#
- AgentOS and PostgreSQL with pgvector in Docker Compose in ~/agentos, back after a reboot
- Super Agent answering through exe.dev's LLM integration, with no OpenAI or Anthropic key on the VM
- Port 8000 private behind exe.dev login, answering /health
- A generated database password in ~/agentos/.env, mode 600
- A nightly pg_dump of the database in ~/backups
What's running, and where
https://my-agentos.exe.xyz/docs
the AgentOS REST API and its interactive docs, behind exe.dev login
http://localhost:7777
the same API on your computer, through ssh -L; what os.agno.com connects to
ssh my-agentos.exe.xyz
the platform's code, data, and logs
Deploy with Shelley#
Click Deploy and Shelley will set up Agno AgentOS on a new VM, then check that it works. No config-file wrangling required.
Prefer a terminal?
curl -fsSL \
https://exe-staging.dev/deploy/agno-agentos/prompt.txt \
| ssh exe.dev new --prompt=/dev/stdinWhat Shelley is told
Set up Agno AgentOS on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/agno-agentos.md from top to bottom.
The recipe's example VM name is my-agentos. This VM's name is the output of `hostname`: use it wherever the recipe writes my-agentos. Skip the step that creates the VM; you are on it.
You are done when all of these are true. Check each one yourself:
- AgentOS and PostgreSQL with pgvector in Docker Compose in ~/agentos, back after a reboot
- Super Agent answering through exe.dev's LLM integration, with no OpenAI or Anthropic key on the VM
- Port 8000 private behind exe.dev login, answering /health
- A generated database password in ~/agentos/.env, mode 600
- A nightly pg_dump of the database in ~/backups
Run "Set up AgentOS by hand" from "On the VM", skipping VM creation and
SSH, then the backup commands in "Back up and restore". The first build
takes about four minutes. Wait for /health before running the Super Agent
check. Don't enable Claude or Codex Engineer unless the owner asks.
Keep port 8000 private: never run share set-public, and never switch to
compose.prod.yaml without a JWT key from the owner. Finish by giving the
owner the `ssh -N -L 7777:localhost:8000 <vm>.exe.xyz` command and the
steps in "Open the AgentOS UI", using this VM's name.
Finish with the URLs I should open.
Also at /deploy/agno-agentos/prompt.txt. The recipe it follows is /deploy/agno-agentos.md.
Set up AgentOS#
Deploy sets it up on a new VM. To do it yourself:
Set up AgentOS by hand
On your computer:
ssh exe.dev new --name=my-agentos
ssh my-agentos.exe.xyz
On the VM, get the template at the commit this page was tested with, and start Docker at boot:
git clone https://github.com/agno-agi/agentos-docker ~/agentos
cd ~/agentos
git checkout -b exe 0f29d2c9b8635da00fd310ecf9a66f4713594293
sudo systemctl enable --now docker.service
The template pins Agno 3.1.12. Move it to 3.2.0, the version this page was
tested with: change the pin, then re-resolve requirements.txt with the
template's own script, run in Agno's Python image, which has uv.
UV_EXCLUDE_NEWER keeps the other packages to what was out when this page
was tested:
sed -i 's/]==3.1.12"/]==3.2.0"/' pyproject.toml
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/app" -w /app \
-e UV_EXCLUDE_NEWER=2026-11-16T00:00:00Z agnohq/python:3.14 \
./scripts/generate_requirements.sh agno agnoctl
grep -E '^(agno|slack-bolt)==' requirements.txt
Expect agno==3.2.0 and slack-bolt==1.30.0, which Agno's Slack
interface needs from 3.2 on.
Agno 3.2 renamed OS Manager to Super Agent (superagent) and runs
scheduled Routines on its Mini Agent (miniagent) instead of Company
Manager, which it no longer has. Point the template's maintenance Routine
and quick prompts at the new IDs, or AgentOS refuses to start:
sed -i 's/executor_id="company-manager-internal"/executor_id="miniagent"/' app/company.py
sed -i 's/^ os-manager-internal:/ superagent:/' app/config.yaml
git diff --stat
Expect four files changed so far. The template's AGENTS.md and skills
still use the old names; a coding agent working on the platform should
read superagent for os-manager-internal.
Make .env: model calls go to the LLM integration, with placeholder keys,
and PostgreSQL gets a generated password:
cp example.env .env && chmod 600 .env
sed -i 's|^OPENAI_API_KEY=.*|OPENAI_API_KEY=exe-llm-integration|' .env
cat >> .env <<EOF
OPENAI_BASE_URL=https://llm.int.exe.xyz/v1
ANTHROPIC_BASE_URL=https://llm.int.exe.xyz
ANTHROPIC_API_KEY=exe-llm-integration
DB_PASS=$(openssl rand -hex 24)
EOF
The template's models chain turns with previous_response_id, which needs
responses stored at OpenAI. The LLM integration doesn't keep them, so send
the context each time instead:
sed -i 's/OpenAIResponses(id="gpt-6.1-sol")/OpenAIResponses(id="gpt-6.1-sol", store=False)/' app/settings.py
grep -c 'store=False' app/settings.py
Expect 2. Then build and start the stack (about five minutes the first
time):
docker compose up -d --build
This is the template's own Compose file. It runs AgentOS on port 8000 with
no login of its own, since exe.dev's login guards the port, and with
~/agentos mounted into the container, so code changes reload at once.
The database listens only on the VM's loopback. Check it after a few
seconds:
curl -s localhost:8000/health
curl -s -X POST localhost:8000/teams/superagent/runs \
-F 'message=Which agents are on this platform? One sentence.' -F stream=false |
jq '{status, content}'
Expect {"status":"ok",...}, then "status": "COMPLETED" and Super
Agent's answer, which came through the LLM integration.
Note
AgentOS has no login of its own in this setup: anyone who can open the VM's HTTPS address can run every agent. That's only you until you share the VM, so share it only with people you'd trust with the platform.
Open the AgentOS UI#
The UI at os.agno.com calls your AgentOS from your browser, and Agno's free plan connects it to a local AgentOS. So make the VM's port 8000 local to your computer. On your computer, leave this running:
ssh -N -L 7777:localhost:8000 my-agentos.exe.xyz
Then:
- Open os.agno.com and sign up, free, with GitHub, Google, or an email address. Name your organization.
- Under Where do you want to run your OS?, choose Skip.
- Under Connect your AgentOS, keep Local, name it
my-agentos, set the endpoint URL to
localhost:7777(withhttp://), and choose Connect OS. - When your browser asks whether os.agno.com may access other apps and services on your device or local network, allow it: that's the tunnel.
The dot next to my-agentos turns green. Ask Super Agent, in the box at the bottom of Home: "Create and publish an agent that turns pasted meeting notes into decisions, action items and open questions. Use the default model and no tools." It builds the agent in about 20 seconds, and Chat then lists it next to your other agents. Sessions, memory, traces, approvals, schedules, and Company are in the sidebar; they all live in the VM's PostgreSQL, and the UI keeps no copy.
The tunnel is only for the UI. Your agents keep running on the VM when you close it, along with their schedules and queued runs.
Call your agents#
Every agent, team, and workflow is a REST endpoint. Open
https://my-agentos.exe.xyz/docs for the interactive API reference,
behind exe.dev login. From the VM:
curl -s localhost:8000/agents | jq -r '.[].id'
curl -s -X POST localhost:8000/teams/superagent/runs \
-F 'message=Hello' -F stream=true -F session_id=demo -F user_id=me
The second streams events as they happen; a later run with the same
session_id continues the conversation. From your computer, the same
calls work on http://localhost:7777 while the tunnel is open. From
another exe.dev VM, use a
VM-to-VM integration to my-agentos,
which keeps the port private.
To build agents in code, put them in ~/agentos/agents/ and register them
in app/main.py; the server reloads when you save. The template's
AGENTS.md and its .agents/skills/ tell a coding agent how, so Shelley
on the VM can do it: "Follow .agents/skills/create-agent/SKILL.md to build
an agent that...".
Turn on Claude and Codex Engineer#
The template includes Claude Code and Codex as agents, off by default:
ClaudeAgent and CodexAgent run the real CLIs inside the AgentOS
container, in a checkout of the platform (~/agentos, mounted at
/app), so they can read and change its code. Their models come from the
LLM integration too: .env already points Claude there, and Codex needs a
provider of its own. On the VM:
cd ~/agentos
sed -i 's|^# from agents.engineers import|from agents.engineers import|; s|^ # create_claude_engineer(),| create_claude_engineer(),|; s|^ # create_codex_engineer(),| create_codex_engineer(),|' app/main.py
sed -i 's|^ model="gpt-6.1-sol",$|&\n model_provider="exe-llm",\n config={"model_providers": {"exe-llm": {"name": "exe-llm", "base_url": "https://llm.int.exe.xyz/v1"}}},|' agents/engineers.py
sed -i 's|approval_mode="auto_review",|approval_policy="untrusted",|' agents/engineers.py
grep -c '^from agents.engineers\|^ create_' app/main.py; grep -c 'exe-llm\|untrusted' agents/engineers.py
Expect 4 and 3. The last sed has Codex ask you before commands it
doesn't consider safe, instead of letting its own reviewer decide. The
server reloads by itself; after a few seconds:
curl -s localhost:8000/agents | jq -r '.[].id'
Expect claude-engineer and codex-engineer in the list. In the UI, ask
Codex Engineer (under Chat): "Add a line saying hi to README.md."
The run pauses at the first command Codex wants to run, and the chat
shows the command with Confirm and Cancel; each answer goes back
to the same Codex session, which carries on until it needs you again,
including before it edits the file. Paused runs wait 15
minutes for an answer by default (hitl_timeout).
Claude Engineer runs in Claude Code's auto permission mode; change
permission_mode in agents/engineers.py to have it ask as well.
Warning
The engineers run as root inside the AgentOS container, which can reach your database and, through the Docker socket the template mounts, start containers on the VM. Treat them like a shell on the VM. The template's harness guide describes Docker sandboxes, a container per session, for more isolation.
Make it live#
To reach the API from the internet, for your own product, claude.ai and ChatGPT over MCP, or Slack, switch to the template's production Compose file, which turns on AgentOS's JWT authorization, then make port 8000 public. The AgentOS UI connects to a live AgentOS only on Agno's Pro plan, which starts with a 30-day trial.
-
In os.agno.com, choose Connect OS, pick Live, enter
https://my-agentos.exe.xyz, and turn on token-based authorization. Copy the public key it shows. -
On the VM, add it to
~/agentos/.envwith your editor, with the whole key in double quotes:JWT_VERIFICATION_KEY="-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----" -
On the VM, set the public URL and an MCP secret, and restart with the production file:
cd ~/agentos printf 'AGENTOS_URL=https://%s.exe.xyz\nMCP_CONNECT_SECRET=%s\n' "$(hostname)" "$(openssl rand -hex 32)" >> .env docker compose -f compose.yaml -f compose.prod.yaml up -d --build sleep 20; curl -s -o /dev/null -w '%{http_code}\n' localhost:8000/agentsExpect
401: without a token, the API refuses. -
On your computer:
ssh exe.dev share set-public my-agentos
The production file runs the code built into the image, without the
~/agentos mount, so after a code change, run the same up -d --build
again; changes Claude or Codex Engineer make inside the container are lost
when it's rebuilt. /, /health, /info,
/docs, and /openapi.json stay readable without a token; everything else
needs a JWT from os.agno.com or a service-account token
(Agno's security guide).
To go back, run ssh exe.dev share set-private my-agentos.
Back up and restore#
On the VM, dump the database every night at 03:30 UTC and keep two weeks:
mkdir -p ~/backups
(crontab -l 2>/dev/null; echo '30 3 * * * docker exec agentos-db pg_dump -U ai -Fc ai > $HOME/backups/agentos-$(date +\%F).dump && find $HOME/backups -name "agentos-*.dump" -mtime +14 -delete') | crontab -
docker exec agentos-db pg_dump -U ai -Fc ai > ~/backups/agentos-$(date +%F).dump
ls -lh ~/backups
Copy ~/backups and ~/agentos/.env off the VM now and then, for example
with scp, or back up the whole disk with VM backups.
To restore a dump:
cd ~/agentos
docker exec -i agentos-db pg_restore -U ai -d ai --clean --if-exists < ~/backups/agentos-2026-11-15.dump
docker compose restart agentos-api
Update#
To move to a newer Agno, read its release notes first, since minor versions have breaking changes, then repeat the pin step with the new version and a current date, and rebuild. For example, for a 3.2.1:
cd ~/agentos
sed -i 's/]==3.2.0"/]==3.2.1"/' pyproject.toml
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/app" -w /app \
-e UV_EXCLUDE_NEWER=$(date -u +%FT%TZ) agnohq/python:3.14 \
./scripts/generate_requirements.sh agno agnoctl
docker compose up -d --build
To take the template's own changes, commit yours and merge:
cd ~/agentos
git add -A && git -c user.name=me -c user.email=me@localhost commit -qm 'My platform'
git pull --no-rebase --no-edit origin main
Git may ask you to resolve conflicts, most likely in pyproject.toml,
requirements.txt, and app/company.py once the template moves to Agno
3.2 itself. Rebuild afterwards. If you made it live, add
-f compose.yaml -f compose.prod.yaml to each docker compose command.
Troubleshooting#
Previous response cannot be used for this organization due to Zero Data Retention: a model withoutstore=False. Add it to everyOpenAIResponses(...)inapp/settings.pyand your own agents.- Codex Engineer fails with
401 Unauthorized ... api.openai.com: it isn't using theexe-llmprovider; rerun thesedcommands in Turn on Claude and Codex Engineer. - os.agno.com can't connect (a red dot by my-agentos): check that the
ssh -Lcommand is still running, thencurl -s localhost:7777/healthon your computer. If that works, your browser is blocking os.agno.com from local addresses: allow local network access for os.agno.com in its site settings (the icon left of the address bar) and reload. - AgentOS exits at startup with
only Mini Agent runs Routines: theapp/company.pystep for Agno 3.2 is missing. - Nothing answers after a reboot:
sudo systemctl enable --now docker.service, thendocker compose psin~/agentos. docker compose logs -f agentos-apiin~/agentosshows the server's log, including Python errors after a code change.
Frequently asked questions#
Is AgentOS free?
The Agno SDK, the AgentOS runtime, and the agentos-docker template are open source (Apache-2.0). The AgentOS UI at os.agno.com is free for a local AgentOS, which is how this page connects it. Connecting a live (public HTTPS) AgentOS needs Agno's Pro plan, $150 a month as of November 2026 after a 30-day trial; see Agno's pricing. You pay exe.dev for the VM and for model usage through the LLM integration.
Why does the UI go through an SSH tunnel instead of the VM's HTTPS address?
os.agno.com calls your AgentOS from your browser, cross-origin. Port 8000 is private behind exe.dev login, which a cross-origin request can't complete: the browser's CORS preflight is redirected to the login page and fails. A tunnel makes the AgentOS a local one at http://localhost:7777, reachable only from your computer, which is also what Agno's free plan supports. To open the API itself to the internet, see Make it live.
Do I need an OpenAI or Anthropic API key?
No. .env points the OpenAI and Anthropic clients at exe.dev's LLM integration, which bills your exe.dev account; the keys in .env are placeholders. The models are told not to store responses (store=False), since the integration doesn't keep them for previous_response_id.
Where is my data, and how do I back it up?
Sessions, memory, knowledge, traces, schedules, and queued runs are in PostgreSQL, in the agentos_pgdata Docker volume on the VM's disk. The platform's code and .env are in ~/agentos. The nightly pg_dump in Back up and restore covers the database; keep a copy of .env too.
Can I use Slack?
Agno's Slack interface receives Slack's HTTP events at /slack/events and calls Slack with the bot token, so it needs a live AgentOS and the token and signing secret in .env, as the template's README describes. exe.dev's Slack Bot integration, which keeps tokens off the VM, uses Socket Mode, which Agno doesn't speak. We haven't tested Slack on this page.
How is this different from Railway, AWS, or E2B?
It's one always-on machine with Docker, a persistent disk, and sudo: PostgreSQL lives next to the API, Claude and Codex Engineer work in a real checkout of your platform, and nothing is public until you make it so. There's no autoscaling; ssh exe.dev resize gives the VM more CPU, memory, or disk.
Updated Nov 16, 2026 · tested end to end Nov 16, 2026 · Markdown · manifest.json · Something wrong? Tell us