---
title: "Self-host Agno AgentOS on your own VM"
description: "Run Agno's AgentOS and PostgreSQL on an exe.dev VM: agents as durable services, models through the LLM integration, and the AgentOS UI over SSH."
url: https://exe-staging.dev/deploy/agno-agentos
category: "AI agents"
updated: 2026-11-16
---

# Self-host Agno AgentOS on your own VM

Agno agents as durable services, with PostgreSQL, on a private VM.

- **Software:** Agno AgentOS (https://www.agno.com)
- **Source:** https://github.com/agno-agi/agno
- **License:** Apache-2.0 (Agno and the agentos-docker template); the AgentOS UI is a hosted service
- **Time:** 15 minutes
- **Example VM name:** `my-agentos` (yours will differ; on the VM, `hostname` prints it)
- **Machine-readable:** https://exe-staging.dev/deploy/agno-agentos/manifest.json

## 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

Running on the VM:

- **AgentOS**: The agentos-docker template, moved to Agno 3.2.0 (Python 3.14), in Docker Compose, with Super Agent, port 8000, data in `~/agentos`
- **PostgreSQL 18 with pgvector**: agnohq/pgvector:18 in Docker Compose; sessions, memory, knowledge, traces, schedules, and the run queue, data in `the agentos_pgdata Docker volume`
- **Models**: GPT (and Claude for Claude Engineer) through exe.dev's LLM integration
- **AgentOS UI**: os.agno.com in your browser, through an SSH tunnel to the VM

How it is reached:

- https://my-agentos.exe.xyz/docs (private): the AgentOS REST API and its interactive docs, behind exe.dev login
- http://localhost:7777 (private): the same API on your computer, through `ssh -L`; what os.agno.com connects to
- ssh my-agentos.exe.xyz (private): the platform's code, data, and logs

## Deploy with Shelley

Open https://exe-staging.dev/new?prompt=Set%20up%20Agno%20AgentOS%20on%20this%20VM%20by%20following%20the%20exe.dev%20recipe%20at%20https%3A%2F%2Fexe-staging.dev%2Fdeploy%2Fagno-agentos.md%20from%20top%20to%20bottom.%0A%0AThe%20recipe%27s%20example%20VM%20name%20is%20my-agentos.%20This%20VM%27s%20name%20is%20the%20output%20of%20%60hostname%60%3A%20use%20it%20wherever%20the%20recipe%20writes%20my-agentos.%20Skip%20the%20step%20that%20creates%20the%20VM%3B%20you%20are%20on%20it.%0A%0AYou%20are%20done%20when%20all%20of%20these%20are%20true.%20Check%20each%20one%20yourself%3A%0A-%20AgentOS%20and%20PostgreSQL%20with%20pgvector%20in%20Docker%20Compose%20in%20~%2Fagentos%2C%20back%20after%20a%20reboot%0A-%20Super%20Agent%20answering%20through%20exe.dev%27s%20LLM%20integration%2C%20with%20no%20OpenAI%20or%20Anthropic%20key%20on%20the%20VM%0A-%20Port%208000%20private%20behind%20exe.dev%20login%2C%20answering%20%2Fhealth%0A-%20A%20generated%20database%20password%20in%20~%2Fagentos%2F.env%2C%20mode%20600%0A-%20A%20nightly%20pg_dump%20of%20the%20database%20in%20~%2Fbackups%0A%0ARun%20%22Set%20up%20AgentOS%20by%20hand%22%20from%20%22On%20the%20VM%22%2C%20skipping%20VM%20creation%20and%0ASSH%2C%20then%20the%20backup%20commands%20in%20%22Back%20up%20and%20restore%22.%20The%20first%20build%0Atakes%20about%20four%20minutes.%20Wait%20for%20%2Fhealth%20before%20running%20the%20Super%20Agent%0Acheck.%20Don%27t%20enable%20Claude%20or%20Codex%20Engineer%20unless%20the%20owner%20asks.%0AKeep%20port%208000%20private%3A%20never%20run%20share%20set-public%2C%20and%20never%20switch%20to%0Acompose.prod.yaml%20without%20a%20JWT%20key%20from%20the%20owner.%20Finish%20by%20giving%20the%0Aowner%20the%20%60ssh%20-N%20-L%207777%3Alocalhost%3A8000%20%3Cvm%3E.exe.xyz%60%20command%20and%20the%0Asteps%20in%20%22Open%20the%20AgentOS%20UI%22%2C%20using%20this%20VM%27s%20name.%0A%0AFinish%20with%20the%20URLs%20I%20should%20open.%0A to create a VM whose agent, Shelley, follows this recipe. From a terminal:

```sh
curl -fsSL https://exe-staging.dev/deploy/agno-agentos/prompt.txt | ssh exe.dev new --prompt=/dev/stdin
```

Or follow the steps below by hand.

[Agno](https://github.com/agno-agi/agno) 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](https://github.com/agno-agi/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](https://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](/docs/integrations-llm), so no OpenAI or
Anthropic key is on the VM, and Claude and Codex work in a checkout of the
platform itself.

## Set up AgentOS

Deploy sets it up on a new VM. To do it yourself:

<details id="create-the-vm" data-manual-setup class="dp-details">
<summary>Set up AgentOS by hand</summary>

On your computer:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
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.

</details>

> [!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](/docs/sharing) 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:

```bash
ssh -N -L 7777:localhost:8000 my-agentos.exe.xyz
```

Then:

1. Open [os.agno.com](https://os.agno.com) and sign up, free, with
   GitHub, Google, or an email address. Name your organization.
2. Under **Where do you want to run your OS?**, choose **Skip**.
3. Under **Connect your AgentOS**, keep **Local**, name it
   **my-agentos**, set the endpoint URL to `localhost:7777` (with
   `http://`), and choose **Connect OS**.
4. 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:

```bash
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](/docs/integrations-vm-to-vm) 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:

```bash
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:

```bash
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](https://github.com/agno-agi/agentos-docker/blob/main/docs/harnesses.md)
> 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.

1. 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.
2. On the VM, add it to `~/agentos/.env` with your editor, with the whole
   key in double quotes:

   ```
   JWT_VERIFICATION_KEY="-----BEGIN PUBLIC KEY-----
   ...
   -----END PUBLIC KEY-----"
   ```

3. On the VM, set the public URL and an MCP secret, and restart with the
   production file:

   ```bash
   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/agents
   ```

   Expect `401`: without a token, the API refuses.
4. On your computer:

   ```bash
   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](https://docs.agno.com/agent-os/security/overview)).
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:

```bash
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](/docs/vm-backups).
To restore a dump:

```bash
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](https://github.com/agno-agi/agno/releases) 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:

```bash
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:

```bash
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 without `store=False`. Add it to every
  `OpenAIResponses(...)` in `app/settings.py` and your own agents.
- Codex Engineer fails with `401 Unauthorized ... api.openai.com`: it
  isn't using the `exe-llm` provider; rerun the `sed` commands in
  [Turn on Claude and Codex Engineer](#turn-on-claude-and-codex-engineer).
- os.agno.com can't connect (a red dot by **my-agentos**): check that the
  `ssh -L` command is still running, then `curl -s localhost:7777/health`
  on 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`: the
  `app/company.py` step for Agno 3.2 is missing.
- Nothing answers after a reboot: `sudo systemctl enable --now
  docker.service`, then `docker compose ps` in `~/agentos`.
- `docker compose logs -f agentos-api` in `~/agentos` shows 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](https://www.agno.com/pricing). You pay exe.dev for the VM and for model usage through the [LLM integration](/docs/integrations-llm).

### 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](#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](/docs/integrations-llm), 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](#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](#make-it-live) AgentOS and the token and signing secret in `.env`, as the template's README describes. exe.dev's [Slack Bot integration](/docs/integrations-slack-bot), 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.


## Related

- [Self-host PostgreSQL](https://exe-staging.dev/deploy/postgres.md): Your own Postgres on a real disk, with backups you've actually restored.
- [Run Mastra agents and workflows on your own VM](https://exe-staging.dev/deploy/mastra.md): The TypeScript agent framework, with Studio, memory, and a VM per thread.
- [Sandboxes for the OpenAI Agents SDK](https://exe-staging.dev/deploy/openai-agents-sdk.md): The SDK runs the agent loop. Each session's commands run on a VM of its own.
- [Run Claude Code on a remote server](https://exe-staging.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
- [Run Codex on a remote server](https://exe-staging.dev/deploy/codex.md): A computer for Codex. An early night for your laptop.
- [Running Agents](https://exe-staging.dev/deploy/agents.md): Use exe.dev VMs as a sandbox
