A crew of AI agents,
working out of one Safehouse.

Big Smooth runs the crew. The Smooth Operators pull the jobs. They all work out of one hardware-isolated microsandbox microVM — every CLI pre-installed, credentials brokered by a fixer on the host, every move watched by the family rat.

this the single ~10 MB Rust binary that runs it all — no Docker, no Node runtime, no per-project setup ritual. th up boots the Safehouse by default; th up direct runs the same crew on the host when you're already in a trusted environment (CI runner, devbox).

install.sh

$ curl -fsSL https://raw.githubusercontent.com/SmooAI/smooth/main/install.sh | sh
$ th up

View on GitHub Download binary

Two modes, same cast

th up — boots the Safehouse by default.

Smooth has exactly two ways to run. th up boots the entire crew inside the Safehouse — a hardware-isolated microsandbox microVM (libkrun on Linux, HVF on macOS). th up direct runs the same crew as host processes for environments that are already sandboxed — CI runners, dedicated devboxes, nested-virt VMs. Same agents, same tools, same surveillance; just a different blast radius.

Hardware-isolated microVM

The default. Boots a microsandbox microVM with its own kernel, its own network namespace, its own filesystem view. Boots in seconds; tears down cleanly with th down.

Project cache, not persistent disk

The microVM itself is ephemeral. Per-project caches (pnpm, cargo, mise toolchains) live on the host under ~/.smooth/project-cache/ and are remounted on every boot. Pearl history lives in Dolt in your repo, not in the VM.

Workspace bind-mount

Your repo at /workspace. Operators edit in place — no copy-on-write surprises, no diff-from-overlay reconciliation. Big Smooth, Wonk, Narc, Scribe, Goalie are all read-only on it.

Reach out to host Docker

Docker is never the sandbox. But when the agent needs a container — running a test fixture, building a multi-arch image — Colima, OrbStack, Rancher Desktop, Podman, or Docker Desktop on the host are all reachable via the bundled docker CLI, brokered through the host stub.

Host-side credential broker

A tiny stub on the host (smooth-host-stub) mints short-lived creds per request over a UDS exposed into the microVM. gh auth token, aws sts get-session-token, gcloud auth print-access-token — your long-term creds never enter the VM.

Learned context that persists

Operators write short notes to the pearl DB at task end (remember) and recall them on the next run (recall_recent). The Dolt store lives in your repo, so memory survives the microVM tearing down — and travels with you across machines via th pearls push.

The loop

We tried seven phases. One agent plus a governor wins.

Each operator handles its own inner iteration (LLM → tool → LLM …). A thin outer governor feeds last run's test output back in, snapshots the workspace when failing tests drop, and stops on the first convincing signal.

Green

Agent reports all tests passing.

Close-to-green

Previous turn reached ≤3 failing; this turn didn't improve. More iteration likely regresses.

Budget

Next turn would blow the --budget-usd cap.

Iteration cap

Safety ceiling (default 5) — not the primary brake.

Stop conditions are budget + plateau, not a fixed iteration cap.

How the safety story actually works

One Safehouse, gRPC over UDS inside, a fixer on the corner.

The Safehouse is the microsandbox microVM the crew operates out of. Big Smooth, the cast, and every dispatched Operator share one address space; they talk to each other over tonic gRPC on Unix-domain sockets ( narc.sock, wonk.sock, scribe.sock, bigsmooth.sock). The host's long-term credentials never enter the VM — when paper is needed, the crew calls Bootstrap Bill (host-side stub) for short-lived ones. Outbound network is iptables-locked to Goalie inside the VM.

Meet the family

The crew Big Smooth keeps on retainer.

Every job needs a crew. The Safehouse has eight regulars and one fixer on the outside. Each has a name, a vibe, and a real job they do whether you're shipping a typo fix or rewriting a microservice.

Big Smooth

The Boss

"Holds court in the Safehouse. Doesn't touch the workspace, doesn't make tool calls, never pulls a job himself. Reads the take, books the meetings, sends the crew out. READ-ONLY by enforcement — Narc'll whack anyone who tries to write, even him."

Orchestrator. axum on :4400. Schedules work, generates policy, owns the access store. Speaks to the outside world over HTTP+WS, and to the crew over `bigsmooth.sock`.

HTTP+WS :4400 (out) · gRPC bigsmooth.sock (in)

Wonk

The Consigliere

"Reads the book. Knows every line of every policy. Doesn't argue, doesn't moralize. The crew asks Wonk before they touch anything; Goalie asks Wonk before forwarding traffic; Narc asks Wonk before issuing the verdict. No LLM, no opinions — just the rules."

Access control authority. Pure policy → answer. Hot-reloads via notify + ArcSwap. Negotiates expanded access at runtime via Big Smooth.

gRPC wonk.sock

Goalie

The Bouncer

"Stands at the door. Looks at the list. Asks Wonk first, then either lets you through or doesn't. iptables has his back — anything trying to slip past gets dropped at the kernel."

Outbound HTTP/HTTPS proxy. Dumb pipe — forwards or blocks based on Wonk's answer. iptables + FUSE enforced at the kernel level inside the VM.

In-VM HTTP proxy

Narc

The Rat (Ours)

"Every family has one — except Narc works for us. Watches every tool call, every prompt, every write. Two-tier surveillance: fast regex for the obvious stuff, an LLM judge for the gray area. When something's bad enough, Narc kicks it upstairs."

Tool surveillance + prompt-injection guard. Regex fast-path + LLM-as-a-judge (Haiku / Flash / GPT-4o-mini). Files pending access requests when a human needs to weigh in.

gRPC narc.sock

Scribe

The Bookkeeper

"Writes everything down. Every door knock, every door slam, every tool call, every Narc decision. The books are sacred. When the heat comes, the books are how the family explains itself."

Per-actor structured logging. W3C traceparent propagation, in-memory ring, batch-forwards to Archivist over HTTP.

gRPC scribe.sock

Archivist

The Vault

"Takes the books from every Scribe and binds them into one ledger. The only one in the Safehouse with a write pen — but only on log paths. Don't let her near anything else."

Central log + event aggregator. HTTP :4401, SSE /events. The dashboard subscribes here for live updates.

HTTP :4401 · SSE /events

Diver

The Jobs Guy

"Goes underwater for the pearls. Each one's a job; Diver fishes it out, hands it to an Operator, marks it closed when the loot comes back. Phones the outside accountant (Jira) so the legitimate side of the operation stays in sync."

Pearl lifecycle manager + optional Jira sync. dispatch / complete / sub-pearl APIs over an in-process handle.

In-process to Big Smooth

Groove

The Continuity

"Some jobs go sideways. Groove keeps a flask of memory at every step so when an Operator gets pinched mid-pull, the next one walks back in and picks up exactly where the last one left the heat."

LLM checkpointing + session resume. Captures conversation state after every tool call; persistent in the pearl DB.

In-process to the operator-runner

Outside the Safehouse — on the host

Bootstrap Bill

The Fixer

"Doesn't live in the Safehouse — Bill works the streets. When the crew needs paper — gh tokens, AWS STS sessions, GCP access tokens — they shout 'Bill!' through the door. Bill delivers per request, never tells them his contacts, never says which envelope went where."

Host-side credential broker. Listens on /run/smooth/host.sock. Shells out to gh / aws sts / gcloud per request, returns short-lived creds, never persists.

UDS /run/smooth/host.sock (host-side)

Smooth Operators

The Made Men

"The crew. Each pearl gets its own Operator — a single agent that goes out, does the job, and reports back. They write the code. They run the tests. They ship the diff. Watched by Narc, gated by Wonk, recorded by Scribe — but the only ones in the Safehouse with a key to /workspace."

The AI agents themselves. One subprocess per dispatched pearl, agent loop + tools + NarcHook + WonkHook on every call. Streams AgentEvent JSON-lines back through Big Smooth to the WebSocket UI.

Key invariants

Only Operators write to /workspace. Big Smooth, Wonk, Narc, Scribe, Goalie are read-only on the repo — enforced by file ACLs inside the VM.
Host credentials stay on the host. The VM dials /run/smooth/host.sock for short-lived per-request creds; the stub re-validates the requested service URL against its allowlist before shelling out.
All outbound traffic goes through Goalie. iptables inside the VM rejects anything bypassing the proxy.
Operators see only their pearls. Assigned pearl + depth-2 dependency closure, scoped by auth token.
Narc runs two tiers. Regex fast path for secrets, write guards, prompt injection; an LLM-as-a-judge (Haiku / Flash / GPT-4o-mini) for the ambiguous cases.
In-VM RPCs travel over UDS, not the network. No service on the host can dial the cast — the sockets live inside the Safehouse filesystem.

Tools the agent already has

No "install gh first" — the microVM ships with the tools agents reach for.

Every cloud CLI we've seen agents need is pinned in the image. Language toolchains land via mise so you can bring your own pinned versions per project. Per-project install state ( pnpm, cargo, mise) lives on the host under ~/.smooth/project-cache/ and is remounted on every boot, so repeat runs on the same repo skip the cold-install tax.

gh

GitHub CLI — auth via your host gh login

aws

AWS CLI v2 — STS-minted creds per request

gcloud

Google Cloud SDK — OAuth access tokens

az

Azure CLI

kubectl

Kubernetes CLI

docker

Docker CLI — reaches the host daemon (Colima / OrbStack / Rancher / Podman) for nested-virt-free workloads

git

Plus openssh, jq, common build tools

mise

Language toolchain manager — node, python, go, ruby; `mise install` to add more

Every CLI that needs auth goes through the host stub — agents never see your long-term keys. Need something we didn't bundle? Add it via th plugin or pin a mise toolchain in your repo — ~/.smooth/project-cache/ caches the install so the next th up picks it up instantly.

One key, every model

Semantic routing slots, resolved by the gateway.

Every LLM call dispatches through a routing slot. The gateway (typically llm.smoo.ai) resolves each slot to a concrete model. Upgrading backends doesn't churn the code.

Slot	Used by	Shape
`smooth-coding`	The coding loop (workhorse) — `th code` default	Strong tool use + multi-turn
`smooth-reasoning`	`th code` Plan + Think modes, deep reasoning	Extended chain-of-thought
`smooth-reviewing`	`th code` Review mode, code-review flows	Adversarial critique, different lab
`smooth-judge`	Narc's LLM-as-a-judge, bench scoring	Yes/no verdicts, low latency
`smooth-summarize`	Context compression during long runs	Summarization, 1M-context
`smooth-fast`	Session auto-naming, titles, autocomplete	Haiku/Flash-class, sub-second TTFT
`smooth-default`	Alias to smooth-coding when a specific slot isn't configured	Generalist

Bring your own provider

Smooth talks to any OpenAI-compatible endpoint. Pin each slot to a different upstream via th code's model picker or ~/.smooth/providers.json.

Kimi CodeKimiOpenRouterOpenAIAnthropicGoogle (Gemini)Ollama (local)

Full model roster, pricing, and provider notes

Memory across sessions

The agent remembers what it learned.

Two agent tools backed by the pearl DB — remember writes a short note; recall_recent reads the newest N back. Operators are taught to call them at task boundaries. Codebase conventions, gotchas, working commands, the path to that one weird config file — they stick across sessions because the volume sticks.

.smooth/dolt → memories

remember("this repo uses cargo-zigbuild
   for aarch64-musl cross-compile",
  source="th-893801")
# ...next session, fresh dispatch:
recall_recent(limit=10)
# → agent primes its context

Hosted sessions

Coming soon

Share a running session from anywhere.

Review a pearl from your phone. Hand a teammate a live session to steer. Drive your laptop's Smooth from your office machine. Smooth dials a reverse tunnel out to a smooai-operated rendezvous and gives you a stable HTTPS URL at <slug>.th.smoo.ai.

Ephemeral scratch-XXXX.th.smoo.ai slugs for ad-hoc sharing; stable subdomains on paid tiers. TLS terminates at the smooai edge on a valid wildcard — your laptop never opens an inbound port. th adds reachability, not authorization: Big Smooth still enforces the same auth locally and over the tunnel.

The CLI

Every platform surface behind one binary.

Sandbox lifecycle, auth, orchestration, access control, tools, tunnels. No separate installers, no Docker Compose, no per-project runtime juggling.

Core

th up
Boot the platform inside a microsandbox microVM (default). :4400 forwards out for the TUI / web UI.
th up direct
Run the cast on the host with no sandbox in front. Only safe in an already-trusted environment.
th down
Stop the platform — tears the microVM down and cleans up state.
th status
System health — cast, sockets, providers, operators in flight.
th code
Interactive coding assistant (ratatui TUI).

Project cache

th cache list
Per-project operator caches under ~/.smooth/project-cache/ — pnpm/cargo state survives across runs.
th cache prune
Drop caches for repos you no longer touch.
th cache clear
Nuclear reset — wipes every project cache.

Auth

th auth login smooai-gateway
Recommended — every slot resolves via one key
th auth login openai
Or: anthropic, google, kimi, kimi-code, openrouter, ollama
th auth providers
List configured providers
th auth default <provider>
Pick which backs smooth-default

Work

th run <pearl-id>
Dispatch a pearl to a Smooth Operator
th operators
List active operators
th pause / resume / steer / cancel
Control an operator mid-task
th inbox
Messages needing attention

Access

th access pending
List pending access requests from operators
th access approve <pearl> <domain>
Approve domain access for a pearl
th access policy <operator-id>
Show the current policy an operator is running under

Tools & Plugins

th mcp add playwright npx @playwright/mcp@latest
Register a Model Context Protocol server
th mcp list
Global + project scopes
th plugin init jq --command "jq {{filter}} <<< {{json}}"
Expose any CLI as an agent tool

Tunnel (coming soon)

th tunnel start
Expose your local Big Smooth at <slug>.th.smoo.ai
th tunnel list
Active tunnels for your org
th tunnel stop <slug>
Close a tunnel

Full command reference on GitHub

Standing on shoulders

Built on microsandbox, mise, tonic + tokio.

The sandbox is a real microVM, courtesy of microsandbox — open-source hardware-isolated microVMs on libkrun (Linux) and HVF (macOS). mise handles language toolchains inside it. In-VM RPCs ride on tonic over tokio's UnixStream — no extra networking, no extra processes.

SmooAI/smooth on GitHub

Install. Boot the Safehouse. Ship.

One 10 MB binary. macOS, Linux. th up boots the Safehouse — a microsandbox microVM with the whole crew on the payroll and every CLI the operators reach for already pinned.

$ curl -fsSL https://raw.githubusercontent.com/SmooAI/smooth/main/install.sh | sh
$ th auth login smooai-gateway
$ th up
$ th code

Download binary SmooAI/smooth

A crew of AI agents,working out of one Safehouse.