Engineering · Self-hosting · Postgres
Self-hosted AI coding agent: what one host really needs
What it takes to run a self-hosted AI coding agent: one Linux host, Postgres with pgvector, one backend per database, a sandbox provider, mail, backups, disk.
On this page
Running a self-hosted AI coding agent means running three things: a control plane, a Postgres database, and somewhere for the agents' sandboxes to live. The first two fit on one Linux host. The third usually shouldn't. This is what the open-source UseAgent stack needs in practice, including the parts that bit us on our own production host.
The code is AGPL-3.0 at github.com/useagenthq/useagent. It is alpha software. APIs and schemas change between releases, so pin a tag. The public repo is at v0.0.3 and gets each release after it has been verified in production.
What a self-hosted AI coding agent runs on
| Piece | What it is | Notes |
|---|---|---|
| Host | Ubuntu 24.04 | 4 vCPU / 8 GB is a comfortable start for the core stack |
| Runtime | bun, pinned to 1.3.14 | bun 1.4 and later reject the repo's file: package dependencies |
| Database | Postgres 16+ with pgvector | The schema runs CREATE EXTENSION vector |
| Proxy | Caddy | Obtains and renews TLS for your domain |
| Models | An OpenRouter key, or provider keys | Keys stay on the server, never in a sandbox |
| Sandboxes | Daytona, CubeSandbox or Box | A plugin per vendor, chosen by env |
| SMTP with implicit TLS | For sign-up verification and invites | |
| Team memory | Optional separate service | Off unless configured |
Our hosted production is a single machine too: 12 cores, 64 GB of RAM, two NVMe drives in RAID1 for 436 GB usable, Postgres on the host. The database is about 2.2 GB. During a 50-run load test the backend used a quarter of one core and 1.4 GB of memory, and host load sat at 1.1. The control plane is small. The agents are not, and they run elsewhere.
Two ways to get a host
The provider-agnostic path is infra/self-host/deploy-app.sh. Provision any Ubuntu 24.04 machine, install the base packages (the list in infra/self-host/hetzner/cloud-init.yaml is plain apt and shell and works as user-data on AWS, Google Cloud or Azure), point a domain at it, open 80 and 443, and run the script from your laptop with your secrets in the environment.
The other path is a reference host on Hetzner through Terraform, about 200 lines: server, firewall, SSH key, cloud-init with Postgres, pgvector, bun, Docker and Caddy. We verified it end to end on 2026-08-20, provision to boot to a live model turn to destroy. One thing that stopped us that day: the default cpx31 type had been retired in Hetzner's EU datacenters and was only orderable in the US ones, so query the API for available server types before you pick a location.
Generate the three application secrets once, at least 32 characters each, and keep them. Every redeploy must reuse them. Regenerating one silently invalidates sessions, operator access or stored org secrets. On the first deploy, a bootstrap admin email and password (12 characters minimum) create the first user through the normal auth hooks, then the credential file is deleted. The self-hosted backend never opens public sign-up on its own.
The three things that blocked our first boot
bun version. bun 1.4 and newer refuse the repo's file:../packages/* dependencies with "unsafe folder path". The cloud-init pins 1.3.14.
Package installs. The shared packages are linked with file: dependencies, not a workspace, so each one needs its own bun install. Skip it and the frontend type-check can't resolve the shared packages. The README's install snippet does every package in order.
pgvector permissions. vector is not a trusted extension, so the restricted app role can't create it. Install postgresql-16-pgvector and create the extension as the Postgres superuser before the first boot. The migration's CREATE EXTENSION IF NOT EXISTS then does nothing, which is what you want.
Exactly one backend per database
This rule cuts against the usual reflex for availability, two replicas behind a load balancer. Don't.
Two things in the backend are process-local. The realtime fan-out that feeds every browser's thread stream lives in one process's memory. So does the barrier that seals a run's events once its provider has stopped writing. Two backends on one database split the stream between them, and one can seal a run the other is still writing. On top of that, boot recovery is global: when a backend starts, it scans every active command in the database and adopts, parks or fails its run. Start a second backend against a live database and it will go after the first one's in-flight runs. We did exactly that in development when several of us shared one dev database, and it failed other people's runs.
So the backend takes a session-level Postgres advisory lock at boot. Production sets REQUIRE_SINGLE_BACKEND, which makes contention fatal:
[boot] SINGLE-BACKEND: another UseAgent backend already holds the singleton lock on this database. ... Refusing to boot. Run exactly one backend per database.Practical consequences. No staging backend pointed at the production database, ever. Test stacks get a throwaway database. And your deploy has to stop the old backend before the new one can take the lock. Availability comes from restarting fast and from runs that survive a restart, which is the subject of deploying long-running AI agents. The control plane post has the longer version of why.
Sandboxes are where the cost is
Each agent gets its own Linux machine with the repo, a terminal, a browser and a desktop. Three plugins are in the repo, and two of them cover most setups.
Daytona is the easy start. It needs an API key and nothing on your host, so the control plane can run on any small VM. Watch the org-wide memory cap if other people share your Daytona org; we hit Total memory limit exceeded. Maximum allowed: 500GiB once and it failed runs that weren't ours.
CubeSandbox runs on your own hardware and speaks the E2B protocol. You get full data locality and no per-sandbox bill, and you pay in disk. A template build needs about 1.5 times the image size free and refuses otherwise ("insufficient disk space: available=6 GiB, estimated_required=39 GiB" was ours, on a host at 99%). Our 3.3 GB agent image became an 11.5 GB filesystem. The whole self-hosted Cube stack took around 145 GB on our host, and when we pointed production at E2B's cloud instead, it sat idle. If you go this way, give it its own machine.
E2B vs Daytona has the startup numbers and the quirks of each.
Check your mail ports before your mail config
Sign-up verification and invites need outbound mail. Our SMTP client does implicit TLS or plaintext; it has no STARTTLS. Hetzner blocks outbound 25 and 465 by default, and a blocked port shows up as nothing more than "SMTP timeout". Resend offers implicit TLS on port 2465, so that combination works. Postmark has no implicit-TLS port, so it can't work with this client at all.
Test the port from the host first:
timeout 6 bash -c 'cat < /dev/null > /dev/tcp/smtp.resend.com/2465' && echo openOne testing trap: Cloudflare Email Routing dropped plus addresses for us, so you+test@yourdomain never arrived. Test with the exact routed address.
A backup timer isn't a backup
The repo ships a backup script: a pg_dump plus the durable state directories, encrypted, checksummed, verified right after it's written, kept 14 days, run daily at 03:17 UTC by a systemd timer. It also has verify and restore commands.
On our own host the timer was installed and had never been enabled. We found that on 2026-09-22 while listing what blocked a public launch. The first archive was 385 MB and took 55 seconds. Run systemctl list-timers after you deploy.
A local archive also dies with the disk. Set the remote sync command so archives leave the host, and set the require-remote flag so a backup fails loudly when that sync isn't working.
Disk fills from releases, not from data
The database stayed small. Docker images did not. Every release pulls new backend, frontend and gateway images, and old ones never leave on their own. One cleanup found 39 old copies of each, plus local copies of 16 to 18 GB agent images; pruning took the disk from 227 GB used to 118 GB. Earlier, a different cleanup took it from 89% to 69%.
Release images pulled by digest carry no tag, so you can't prune them by tag. Prune per repository by image ID and keep the newest few, because a rollback needs the previous release's images. If you run CubeSandbox, its MySQL keeps 1 GB binlogs forever unless you set binlog_expire_logs_seconds. Put the prune on a weekly timer.
For Postgres on a 64 GB host we run shared_buffers 4GB, effective_cache_size 32GB, work_mem 32MB, maintenance_work_mem 1GB, random_page_cost 1.1 and jit off. We restarted Postgres to apply it only when no runs were in flight; the backend reconnected on its own.
If you'd rather not run any of this, hosted UseAgent is the same platform, and the self-host guide is the place to start if you would.
Frequently asked questions
What do I need to self-host UseAgent?
A Linux host (Ubuntu 24.04, 4 vCPU and 8 GB RAM is a comfortable start for the core stack), bun, Postgres 16 or newer with pgvector, Caddy for TLS, a model key, and a sandbox provider such as a Daytona API key if you want agents with a computer.
Can I run UseAgent without a sandbox provider?
The web UI and model-backed chat run without one. Claude Code, Codex and OpenCode runs need a sandbox, because the agent works in its own isolated Linux machine.
Can I run two UseAgent backends for high availability?
No. Exactly one backend per database is supported. Production sets a flag that makes a second backend refuse to boot, and availability comes from fast restarts and runs that survive them instead of replicas.