Self-host Omnara

Install#

Deploy sets up the stack, the agents' user, and backups on a new VM. To do it yourself:

ssh exe.dev new --name=my-omnara
ssh my-omnara.exe.xyz

sudo systemctl enable --now docker.service
git clone --branch cluster-v0.2.15 --depth 1 \
  https://github.com/omnara-ai/omnara ~/omnara
cd ~/omnara
curl -fsSLO https://exe-staging.dev/deploy/omnara/compose.exe.yaml
curl -fsSLO https://exe-staging.dev/deploy/omnara/exe-mail.py
curl -fsSLO https://exe-staging.dev/deploy/omnara/backup.sh
chmod +x backup.sh

(umask 077; set -o noclobber; cat > ~/omnara/.env <<EOF
COMPOSE_FILE=compose.yaml:compose.exe.yaml
COMPOSE_PROFILES=app
OMNARA_RELEASE=v0.2.15
OMNARA_PUBLIC_URL=https://$(hostname).exe.xyz
OMNARA_ALLOW_INSECURE_DEV_DEFAULTS=1
OMNARA_SECRET_ENCRYPTION_KEYS='{"k1":"$(openssl rand -base64 32)"}'
OMNARA_SECRET_ENCRYPTION_ACTIVE_KEY_ID=k1
OMNARA_SKILL_DOWNLOAD_SIGNING_KEY=$(openssl rand -base64 32)
OMNARA_EMAIL_DRIVER=smtp
OMNARA_EMAIL_FROM=omnara@$(hostname).exe.xyz
OMNARA_SMTP_ADDR=127.0.0.1:2525
OMNARA_SMTP_REQUIRE_TLS=0
EOF
)

sudo tee /etc/systemd/system/omnara.service >/dev/null <<EOF
[Unit]
Description=Omnara (docker compose)
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target

[Service]
Type=oneshot
RemainAfterExit=yes
User=$USER
WorkingDirectory=$HOME/omnara
ExecStart=/usr/bin/docker compose up -d --remove-orphans

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now omnara.service
cd ~/omnara
until curl -fs http://localhost:8000/healthz; do sleep 3; done; echo
docker compose exec -T worker-llm curl -fsS http://127.0.0.1:8090/v1/models | head -c 200; echo
docker compose logs api-mail

sudo useradd -m -s /bin/bash omnara-agent
sudo loginctl enable-linger omnara-agent
sudo systemctl set-property user-$(id -u omnara-agent).slice \
  IPAddressDeny=172.16.0.0/12
docker network inspect omnara-control-plane -f '{{range .IPAM.Config}}{{.Subnet}}{{end}}'

sudo tee /etc/systemd/system/omnara-backup.service >/dev/null <<EOF
[Unit]
Description=Back up Omnara to ~/omnara-backups
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
User=$USER
ExecStart=$HOME/omnara/backup.sh
EOF
sudo tee /etc/systemd/system/omnara-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up Omnara every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now omnara-backup.timer
sudo systemctl start omnara-backup.service
cd ~/omnara
latest=$(ls -1t ~/omnara-backups/omnara-*.tar.gz | head -n 1)
tar -tzf "$latest"
tar -xzOf "$latest" ./omnara.dump |
  docker compose exec -T postgres pg_restore --list | grep -c 'TABLE DATA'

Sign up#

Open https://my-omnara.exe.xyz/, sign in to exe.dev if asked, and click Sign up with the email of your exe.dev account. A verification email comes from exe.dev within a minute. Open its link, choose a password (12 characters or more), and create an organization. It comes with a project called Default.

exe.dev only delivers to addresses it knows (see the FAQ). The bridge writes a refused message to its log, link and all; to find the newest link, on your computer:

ssh my-omnara.exe.xyz 'cd omnara && docker compose logs --no-log-prefix api-mail' |
  grep -o 'https://[^ ]*?token=[0-9a-f]*' | tail -n 1

Add the models#

In Models, click New provider:

1. Choose the OpenAI preset and name it exe-llm.
2. Under API key, make a new secret with any value, say unused. The relay drops it; exe.dev adds the real credentials.
3. Under Advanced, set Base URL to http://127.0.0.1:8090/v1 and keep the API format OpenAI Responses.
4. Click Add provider. Omnara lists the gateway's models: pick a few, say gpt-6.1-sol and gpt-6-luna, share them with the Default project, and add them.

127.0.0.1:8090 is the relay inside Omnara's containers, not a port on the VM, so nothing else can reach it.

Give agents a machine#

In Machines, click Connect machine, name it omnara-vm, share it with the Default project, and copy the machine token (it's shown once). Then on the VM, paste the token when asked:

read -rsp 'Machine token: ' token; echo
sudo -iu omnara-agent env XDG_RUNTIME_DIR=/run/user/$(id -u omnara-agent) \
  DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/$(id -u omnara-agent)/bus \
  OMNARA_API_URL=http://localhost:8000/api/v1 OMNARA_MACHINE_TOKEN="$token" \
  sh -c 'curl -fsSL http://localhost:8000/install/omnarad.sh | sh'
unset token

Expect omnarad restarted, and the machine shows Online in the dashboard. The daemon is a systemd user service of omnara-agent, keeps its token in ~omnara-agent/.omnarad/daemon.json, and updates itself from Omnara's stable releases. Check it with sudo -iu omnara-agent .omnarad/bin/omnarad status.

Make an agent#

In Agents, click New agent, switch to YAML, name it, and paste:

version: v1
instruction: |
  You are an engineering assistant. Use your machine to run commands.
model:
  provider_config: exe-llm
  name: gpt-6.1-sol
machine_sources:
  - machine_name: omnara-vm

Click Create & launch agent, open Chat, and ask it to run uname -a and df -h /. The agent configuration docs cover tools, MCP servers, skills, memory, subagents, and schedules.

Use the API#

With All projects selected, open API Tokens and create an org token. On the VM, the API is at http://localhost:8000/api/v1, and the chat's cURL and TypeScript SDK tabs show ready-made calls:

curl http://localhost:8000/api/v1/orgs -H "Authorization: Bearer $OMNARA_TOKEN"

From elsewhere, https://my-omnara.exe.xyz/api/v1 is behind exe.dev login too. Send an exe.dev VM token as well, which the proxy removes before Omnara sees the request:

ssh exe.dev ssh-key generate-api-key --vm=my-omnara --label=omnara-api
curl https://my-omnara.exe.xyz/api/v1/orgs \
  -H "X-Exedev-Authorization: Bearer $EXE_VM_TOKEN" \
  -H "Authorization: Bearer $OMNARA_TOKEN"

Bring your team#

Share the VM, on your computer:

ssh exe.dev share add my-omnara teammate@example.com

They sign up at https://my-omnara.exe.xyz/ with the email the VM is shared with, as you did. Then invite them in Members (with All projects selected); they get an email and accept when they sign in.

Compared with the hosted platforms#

• Claude Managed Agents: Anthropic runs the agent loop, sessions, and memory, on Claude only. That page gives each session a VM for its tools. Less to run, but your agents live on Anthropic's platform.
• OpenAI Agents SDK: a library. You write the agent in Python and that page gives each sandbox session a VM. More code, full control.
• Omnara: the platform itself, on your VM, with any model. You get its dashboard, API, triggers, and event log, and you keep it running and updated.

Back up and restore#

Backups run nightly; ~/omnara/backup.sh takes one now and prints its path. Each holds the database, the artifact and memory volumes, and .env. Copy them off the VM now and then, on your computer:

scp 'my-omnara.exe.xyz:omnara-backups/*.tar.gz' .

cd ~/omnara
backup=$(ls -1t ~/omnara-backups/omnara-*.tar.gz | head -n 1)
mkdir /tmp/omnara-restore && tar -xzf "$backup" -C /tmp/omnara-restore
cmp -s .env /tmp/omnara-restore/.env || echo "Keys differ: see below"
docker compose stop api-llm worker-llm api-mail api worker maintenance
docker compose exec -T postgres dropdb -U omnara --force omnara
docker compose exec -T postgres createdb -U omnara omnara
docker compose exec -T postgres pg_restore -U omnara -d omnara --no-owner \
  < /tmp/omnara-restore/omnara.dump
docker run --rm -i -v omnara_rustfs-data:/rustfs-data -v omnara_memory-data:/memory-data \
  postgres:18-alpine sh -c 'find /rustfs-data /memory-data -mindepth 1 -delete && tar -C / -xf -' \
  < /tmp/omnara-restore/volumes.tar
docker compose up -d
rm -rf /tmp/omnara-restore

Update#

Omnara moves fast: read the release notes first. Then, with the new release's number in place of 0.2.15:

cd ~/omnara
./backup.sh
v=0.2.15
git fetch --depth 1 origin tag cluster-v$v && git checkout cluster-v$v
sed -i "s/^OMNARA_RELEASE=.*/OMNARA_RELEASE=v$v/" .env
docker compose up -d

The migrate service upgrades the database before the API starts. Newer releases are untested here; if one misbehaves, restore the backup with the old release checked out.

Troubleshooting#

• Logs: cd ~/omnara && docker compose logs -f api worker.
• After stopping the API or worker, use docker compose up -d, not start or restart: the relays share their network, and up brings them back too.
• A model call can't reach 127.0.0.1:8090: the relay is down. Run docker compose up -d, then the relay check from Install by hand.
• A model is refused as not in the integration's model list: your LLM integration doesn't serve it. Pick another, or enable that provider in the integration.
• Links point to the wrong address, or the API refuses requests for your VM's name: OMNARA_PUBLIC_URL in .env must be https://<vm>.exe.xyz. Run docker compose up -d after changing it.
• No email arrives: docker compose logs api-mail shows sent or why exe.dev refused it, followed by the message. Only you, your team, and people the VM is shared with can get Omnara's email.
• The machine stays Offline: sudo journalctl _UID=$(id -u omnara-agent) -n 30 and sudo -iu omnara-agent .omnarad/bin/omnarad status.