Self-host Uai.
Your machine, your code, your secrets. The cloud at
app.runuai.com orchestrates; the host on your hardware does
the work and holds the credentials.
What you need
- Docker. Tasks run as Compose stacks.
- Node 22 and pnpm 9 for the host binary in v1 (single-file distribution comes later).
- ~16 GB RAM recommended. Each task container is lightweight on its own; parallel tasks add up.
- Any OS — macOS, Linux, Windows, or a headless server. The same installer covers all four.
What it touches
Uai owns its workspace at ~/.uai/. Every task gets a
worktree inside that directory:
~/.uai/tasks/<taskId>/workspace/<project-slug>/.
Your main project directories — ~/Projects/whatever,
your editors, your shells, your other dev containers — are not
modified.
What it doesn't touch
- Your
~/.claude— Uai authenticates Claude via its own host-resident token. - Your
~/.ssh/id_rsa— the host generates a fresh per-user SSH keypair you paste into GitHub. No key reuse. - Your
~/.codex— Codex gets a per-task writable copy of its own state. - Your other dev containers — Compose project names
are namespaced
task-<id>, so they can't collide with whatever else is running.
Install
Three commands. Run them in the directory you want to clone Uai into.
git clone https://github.com/diogoperillo/uai.git
cd uai && pnpm install && pnpm host-agent build
uai-host install
Then open the local UI in any browser:
http://127.0.0.1:5876. Pair the host with the cloud from
Account → Hosts — the cloud
gives you a one-time token, you paste it into
uai-host pair <token>, and you're connected.
Isolation
Every task: own Compose stack, own worktree, own branch. Ports are
bound to 127.0.0.1 and reached through the cloud proxy;
undeclared app ports are not forwarded. Agent CLIs run inside the
task container, not on your host. Credentials are per-user, encrypted
with the host master key.
Full architecture writeup lives in the repo under
docs/isolation.md.
Headless
Same install on a headless box. Skip the browser; everything you'd see
in the local UI is also in uai-host status. Useful for
a dedicated server, a NAS, or a cheap always-on Mac mini in your
closet.