rainier

README

Rainier

Self-hostable infrastructure for running your coding agents — Claude Code, Codex, Gemini CLI, and friends — in your own cloud, while they feel like local terminal sessions. Sessions survive laptop sleep and network changes; attach shows the agent's real TUI from any machine; your subscriptions and your GitHub identity stay yours.

Active Development & Hosted Cloud Service Coming Soon: Project Rainier is under active development. Alongside self-hosting, a fully managed hosted cloud service is launching soon. We are actively onboarding pilot users, design partners, and collaborators — reach out to josh@tokencanopy.com for early access.

The Problem Rainier Solves

Autonomous coding agents (Claude Code, Codex, Gemini CLI, and others) are transforming software engineering, but running them on personal machines introduces significant friction:

• Laptops sleep, agent runs break: Long-running agent tasks abort when a developer closes their laptop lid, walks away, or changes Wi-Fi networks.
• Remote shouldn't mean headless: Traditional remote containers or batch jobs strip away the rich interactive terminal UI, making real-time steering and feedback difficult.
• Credential sprawl & security risks: Pasting personal GitHub PATs or cloud keys into .git/config or container environments creates security liabilities; unmonitored container networking risks accidental data exfiltration.
• Local resource exhaustion: Running multiple parallel agent sessions pegs CPU/memory, burns battery, and litters local working copies with half-finished branches and scratch files.

Rainier solves this by providing persistent, secure cloud execution with a local-feeling terminal:

• Continuous Sessions: Agents run on cloud sandboxes that survive laptop sleep, network drops, and machine transitions. Reconnecting instantly restores the interactive TUI.
• Zero Credential Exposure: GitHub tokens and secrets are vaulted in the control plane and minted per-git-operation via an in-sandbox helper — never written to disk or container volumes.
• Locked-Down Egress: Built-in network allowlisting restricts external network calls to approved endpoints and registries. Public package registries, the Go module mirror and GitHub's source and API hosts are reachable by default so ordinary development works out of the box; everything else, including private registries, is named per environment. See docs/default-egress.md.
• Parallel Scale: Offload multiple agent sessions simultaneously without bogging down your workstation.

Architecture & Status

Rainier is currently at v0 (terminal happy path). One controld (Postgres-backed REST + WebSocket API, GitHub identity, least-loaded placement, credential vault) fronts N runnerd VMs that dial it outbound, and the rainier CLI drives the whole fleet. Sessions clone your repositories at boot and push back as you.

• Deployment Guide: docs/deploy-gce.md
• Session Image: docs/session-image.md — the default coding environment every session runs, what is in it, and how it is pinned and smoke tested
• Architecture Specs:
  • Rainier Overview
  • Control Plane (controld)
  • Environments & Snapshots
  • GitHub Connector & Credential Vault

Since the Wave 4 extraction, controld is composed rather than monolithic: the portable session lifecycle, in-pool placement, runner reconciliation, and attach/workspace orchestration live once, in controlapp, behind the frozen public control contract. internal/controld supplies the adapters that contract needs — the store as workspace-keyed repositories, GitHub-login roles as the authorizer, the vault as launch material, the runner websocket as the transport, dial-back pairing as the attach broker — and keeps only what is genuinely host-specific: HTTP/WebSocket handling, GitHub login, secrets, and the sandbox's upward credential request. Rainier Cloud composes the same controlapp with its own adapters. Three more public packages carry what a host needs beyond the services: runnerplane (the runner WebSocket endpoint, generation fencing, dispatch correlation), attachplane (the terminal attach handshake and splice), and v0wire (the /v0/ JSON shapes and the status table), each behind a small host interface that self-hosted controld implements exactly as a hosted cell does.

Quickstart

You need a reachable Rainier server, an account with access, and an administrator who has connected a runner with available capacity. Rainier does not provision these prerequisites through the CLI. Follow the CLI onboarding guide for either installation method and for diagnosing a waiting session.

rainier --help gives a compact command overview; rainier help <command> and <command> --help give details. rainier help all retains the full guide. rainier version (or --version) reports the build version. Source checkouts report dev; make build stamps the actual source worktree's revision and dirty status through scripts/build.sh. Direct, unstamped go build and source archives report plain dev rather than trusting potentially incorrect enclosing-repository metadata. Release builds can supply the actual release tag, for example:

Explicit linker flags (in GOFLAGS or arguments to scripts/build.sh) take precedence over automatic source stamping. Supply main.version to identify a release; otherwise that custom build reports plain dev.

# Replace vX.Y.Z with the release being built; this does not publish anything.
go build -ldflags '-X main.version=vX.Y.Z' -o bin/rainier ./cmd/rainier

make build

# Point the CLI at your controld and log in with your GitHub identity.
# --from-gh borrows the token from the `gh` CLI; --token <t> and
# --client-id <id> (device flow) are the alternatives.
bin/rainier login --from-gh --server https://rainier.example.invalid # replace with your server URL
bin/rainier status                                           # are you ready to code?
bin/rainier env ls                                           # choose an environment available on your server
bin/rainier agent status                                     # inspect coding-agent login status

bin/rainier new --name box1 --env dev                        # replace dev with your environment; creates, then attaches
bin/rainier ls                                               # name, state, age (--verbose for ids and runners)
bin/rainier attach box1                                      # resumes a stopped session; Ctrl-] detaches
bin/rainier stop box1                                        # release its compute; attach brings it back
bin/rainier delete box1                                      # permanent, and it asks first

rainier --help is the whole product surface on one screen; rainier help all is everything else, including the self-hosted and administrative commands used below. The command contract — what each promises and which Cloud APIs it depends on — is docs/cli-v0-contract.md.

Hosted login and contexts

A hosted rainier logs in through the browser instead of a GitHub token:

bin/rainier login --cloud https://edge.example.invalid # replace with your hosted URL; prints and opens sign-in
bin/rainier context list                              # every server this CLI knows (advanced)
bin/rainier workspace use ws_example                  # when the account has several (advanced)
bin/rainier status

On a hosted rainier a bare rainier login is enough after the first time: it signs in again to the server this machine is already using, and it is always safe to rerun. rainier logout removes those credentials and nothing else — your sessions keep running, and your coding-agent logins and GitHub connection are untouched. Signing in successfully is not the same as having a ready workspace, so login ends by printing the authoritative readiness of yours.

login --cloud starts a login attempt, prints the URL you finish signing in at, polls until the browser half is done, and stores the result as a context named after the edge host. A context is one server plus the credentials for it; context use NAME switches, context current says which one is live, and every other command talks to whichever is current. login --server (the GitHub login above) writes the default context unless --context NAME names another, so a self-hosted controld and a hosted edge live side by side in one config.

A hosted context is scoped to one workspace, sent as Rainier-Workspace on every request: a login that finds exactly one workspace adopts it, and workspace use <id> chooses when there are several. Hosted access tokens are short-lived — the CLI refreshes them silently and re-saves the rotated pair, and only says "log in again" when that is genuinely the remaining step. Set RAINIER_NO_BROWSER=1 on a headless box to print the URL without opening it.

Agent login

A coding agent inside a session — Claude Code, Codex — is logged in once and stays logged in: in every later session, in every workspace you are a member of, on any runner.

bin/rainier agent login claude   # a session running the agent's own login; finish it, then exit
bin/rainier agent status         # AGENT  STATUS  SINCE
bin/rainier agent logout claude  # everywhere, at once

agent login is an ordinary session whose only job is the vendor's own login flow, attached to your terminal: Claude Code prints its sign-in URL and asks for the code back, Codex uses a device code. It runs in your workspace's default environment, whose image has the agent installed; --env NAME is the advanced override for a self-hosted server that publishes several. When you exit, the CLI removes that session and reports whether a credential was stored.

agent status says one of three things per agent: not configured, ready, or needs attention. ready means a credential is stored — Rainier does not check it with Anthropic or OpenAI, so it is not a promise that the agent will authenticate.

What makes this work is the agent home: every session a person starts mounts one writable volume per workspace at /rainier/agents, and each agent is pointed at its own subdirectory through the variable it already honors (CLAUDE_CONFIG_DIR, CODEX_HOME). The agent's credential file lives there, and sessiond keeps it equal to a sealed copy the control plane holds: fetched at boot, put whenever the agent rewrites it (a background token refresh included), removed when you log out. The credential is never in the workspace, an environment snapshot, the process environment, a create, or a log. After restoring Claude credentials into a fresh home, Rainier also creates the minimal non-secret onboarding marker so the interactive TUI opens ready to use; it preserves any existing Claude settings. Everything provider-specific is one row in controlapp/agents.go; a third agent is a row plus its probes.

rainier new attaches immediately by default so you watch the agent boot; --detach opts out. rainier attach is state-aware: a suspended session is resumed first, and an established viewer reconnects after transient network or control-plane interruptions from the last terminal sequence it rendered. Names are per-owner, so <id|name> takes either.

An environment is the reusable template a session starts from — a base image, a setup script, an egress allowlist, and the team secrets its sessions get as environment variables. --egress is what a session needs BEYOND the default developer baseline (npm, PyPI, the Go module mirror, GitHub's source and API hosts), which every session already gets:

printf %s "$GH_PAT" | bin/rainier secret set GH_TOKEN   # write-only; stdin keeps it out of your history
bin/rainier env create dev --image node:22 \
  --setup-file ./setup.sh --secret-ref GH_TOKEN \
  --egress npm.internal.example.com                     # extra hosts; the public registries are already on
bin/rainier env ls                                      # name, id, image, cached
bin/rainier env create gpu-dev --image node:22 --capability gpu   # only lands on a runner that announced gpu
bin/rainier new --name box2 --env dev                   # ...starts from it

The first session on an environment runs the setup script live — attach and you watch it — and its image is then snapshot-cached for the next one; editing the image or the script invalidates that cache without touching any running session. --image/--egress on new override the environment for that one session. Setup scripts should install into image-visible paths — $HOME, or /opt/rainier-env on the stock session image, which is already on PATH — because that is what the snapshot carries forward, while /workspace is a per-session volume the snapshot excludes. Details, including the one hardening flag a first build trades away and why /usr/local is not the install prefix, in docs/deploy-gce.md §7.

Give an environment a github connector and its sessions arrive with the code already checked out, on a branch of their own, able to push:

bin/rainier login --from-gh --server http://rainier-1:9090  # asks for `repo`
bin/rainier creds                                           # provider, status, scopes
bin/rainier env create app --image node:22 \
  --connector-json '{"type":"github","repo":"acme/app"}' \
  --init-file ./init.sh                  # runs after the clone, on every boot
bin/rainier new --env app --name app1    # /workspace/app on branch rainier/app1
bin/rainier push ./notes app1:/workspace/notes   # and `pull` the other way

Git inside the session is the source of truth for what changed: attach and run git status, git diff, or git log there. Rainier deliberately has no repository-diff command of its own.

Commits from inside a session are the human's: user.name is your GitHub login and user.email your GitHub noreply address. The token behind them is sealed in controld and minted per git operation through an in-sandbox credential helper — it is never written to .git/config, an environment variable, or the workspace volume. When it goes stale, one failed operation is enough: rainier creds reads needs_refresh and both git and the API say rainier login --refresh github. setup is the cacheable, pre-clone half (toolchains); init is the per-boot, post-clone half (npm ci and friends), and it runs on cache hits too. docs/deploy-gce.md §8 has the whole story.

Locally, make e2e brings the whole stack up on your own machine (Postgres in docker; controld, egressd and a dial-mode runnerd on the host, with runnerd driving real containers) and drives that same CLI flow end to end, secrets and environments included — plus, when gh is authenticated with repo and delete_repo, a real clone/commit/push against a throwaway private repo it creates and deletes. The dress rehearsal for a real deploy.

What runs where

Component	Where	Talks to
rainier	your laptop	controld (HTTPS/WSS)
controld	one VM	Postgres; accepts runner and client connections
runnerd	each runner VM	dials controld outbound; drives docker
egressd	each runner VM	the session allowlist proxy (egress R4)
sessiond	inside each session container	dials its runnerd outbound

Reachability is outbound-only in one direction (spec rule 3): sessiond → runnerd → controld, and clients talk only to controld. Nothing dials into a runner.

runnerctl and rattach are dev tools, not the product surface: they drive one runnerd's local HTTP API directly, bypassing the control plane (no identity, no placement, no durable state). They stay in-tree for debugging a single box — rainier is the CLI to use.

Tests

go test ./...                    # unit + contract suites (no services needed)
go test ./internal/e2e/ -race    # in-process e2e scenes: chaos, environments, git
make e2e                         # full stack on docker, driven by the real CLI
./scripts/egress-check.sh        # egress R4 acceptance (exit 3 = skipped on VM-backed docker)
make session-image               # build the session image (docs/session-image.md)
make session-image-smoke         # functional image smoke: builds, installs, servers, agents

The store contract suite runs against memstore by default and against Postgres when docker is available; the e2e scenes take RAINIER_TEST_PG_DSN=postgres://… to run the same scenarios against pgstore.

Terminal latency benchmark

After make build and rainier login, the developer benchmark drives the real configured fleet with sequential synthetic scratch sessions:

bin/rainier-latency --rainier bin/rainier --samples 10
bin/rainier-latency --rainier bin/rainier --samples 10 --cold

It performs one unreported warm-up by default, emits JSON Lines observations and R-7 percentile summaries, and removes every session it creates. Output contains no session identifiers, terminal contents, user identity, or runner names. The warmed-fleet targets are p95 under 1.5 s for create-to-usable, 200 ms for attach by id, 225 ms by name, and 75 ms for terminal interaction RTT. These exclude image pulls, environment setup, agent CLI boot, burst load, and geographic network differences; small --samples values make p95 directional.

Hosted Pilot & Partnerships

A managed hosted cloud service of Project Rainier is launching soon. We are actively welcoming pilot users, design partners, and collaborators:

• Engineering teams looking to run persistent, off-laptop agent environments.
• Developers running multi-agent workflows across repositories without local resource drain.
• Organizations needing safe agent sandboxes with vaulted credentials and egress filtering.

To join the pilot program or discuss partnerships, email josh@tokencanopy.com.

Brand assets

Logos live in assets/. The mark is a peak chevron in a rounded square, carried over from the earlier AgentDrive system and recolored to the lockup's palette — deep navy #043D6A, ice blue #B8DEF2.

File	Use
project-rainier-lockup.png	Full lockup with wordmark. README hero, docs, slides.
rainier-icon.svg	Square icon, ice blue on navy. Source of truth for the icon PNGs.
rainier-icon-512.png, rainier-icon-1024.png	Rasterized square icon — app icons, connector listings, avatars.
rainier-mark.svg	Bare mark, navy on transparent. Source of truth for the mark PNGs.
rainier-mark-512.png, rainier-mark-1024.png	Rasterized bare mark, transparent — favicons, watermarks, dark or light grounds.
tokencanopy-emblem.svg	Token Canopy org emblem. Company-level use, not product.

The PNGs are generated from the SVGs; edit the SVG and re-render rather than retouching a PNG.

License

Apache-2.0