How Uai works.
A chat, a crew of personas, the backlog they draft, a container, an editor, in-app review, a live preview, browser testing, and your own credentials — the architecture, in the order you'll meet it.
1. The chat loop
A task is a Slack-style channel with a goal. You set a global context for the task; each agent gets its own kickoff prompt; any agent with a non-empty kickoff opens the first turn the moment its container is ready.
Mention @agent-id to address one directly. The
orchestrator routes the message; the agent answers in-channel. No
hidden side conversations.
2. Personas & the crew
You don't configure agents per task — you design
personas and reuse them. A persona is a named,
reusable teammate: a name and @handle, an avatar, a role
and brief (its system prompt), an engine (Claude or Codex, with model
+ effort), attached skills, permissions for what it may do, and
cross-task memory that carries what it learned into the next task.
Group personas into Teams — a saved lineup with a
leader — and drop a whole team onto a task as a unit. The specific
agents on one task are its crew: they answer
in-channel and review each other — an @architect
proposes, a @reviewer pushes back — before anything
reaches you. The host advertises which engines and models it
supports; the picker filters to what's actually available.
3. Agents that plan
Point a planner persona at a goal and it drafts the backlog for you — fully-configured task and subtask drafts that stay inert until you approve them with Start. You green-light the plan; nothing runs on its own.
Subtasks carry the parent's chat as context and kick off when the parent closes.
4. The container
Every task runs in a fresh Docker stack named task-<id>.
For each selected project Uai creates a git worktree
on the task's branch and bind-mounts it into the container.
One standard image per host carries the agent CLIs and a runtime
base; per-folder versions come from each repo's
.tool-versions via asdf. Your main
workspace is never touched.
5. The editor
Every task container runs code-server — the same
VS Code engine you know. The task page shows it in an Editor pane
alongside the chat; both point at the same worktree.
Edit a file mid-conversation. Drop a debugger. Run a command in the integrated terminal. The agents see your edits the moment they read the file again.
6. In-app review
Before anything ships, you review it. A diff drawer inside Uai spans every repo in the task, split or unified, comparing the task branch against your default branch.
Approve what's right; send the rest back with a message — no leaving for "go check GitHub."
7. The preview
Declare a preview port on the project (e.g. web → 3000).
Every task gets a subdomain URL like
<taskId>-web.preview.runuai.com that proxies
straight into the running dev server inside the container.
Hot reload works because it's a real dev server. By default the URL is private, gated by a signed cookie; on Dev and up you can make it public — cookie-free, guarded only by an unguessable task ID — to hand to a teammate or point QA at it.
8. Browser testing
Turn on browser testing for a project and agents get a headless Chromium through the Playwright MCP — so they can drive the running app, click through a flow, and check their own work against a live preview before handing it back.
Opt-in, per project.
9. The credentials
Every task carries the task-creator's own credentials, not the host
operator's. The host generates a per-user SSH keypair — you paste
the public key into GitHub once — and keeps the private key
encrypted under the host master key, never touching your
~/.ssh. Commits are authored with your git identity
(name and email), so a task clones and pushes as you.
GitHub uses the Uai App with user-to-server tokens, so every PR
opened and every comment posted attributes to you, not to a bot.
Tokens live in the container's ~/.config/gh/hosts.yml;
the host refreshes them before each 8-hour expiry.
See the whole loop in your repo.
Design a crew, start a task, and watch the whole loop come together — on a host you control.