Hestia is a terminal-first development container project targeting Apple Silicon macOS and Windows through WSL2. The goal is reproducible toolchains and disposable containers without disposable work.
Status: fixture foundation implemented; Milestone 1 acceptance incomplete. The synthetic Go fixture, checkout identity, canonical linux/arm64 image, scoped Compose generator, durable state, lifecycle/cache helpers and the optional agent layers (omp, PiG) have macOS arm64 evidence in the evidence log. omp settings persistence and the provider-policy overlay are exercised. Every agent image also carries the nono sandbox CLI, and opt-in images add upstream Pi, Pi-Bolt and Claude Code; all of them build on the Mac, but no agent session has run under nono or in the new images. The native LiteLLM fixture proof verifies real assisted edits, recreation and saved-session resume; Bedrock authentication, PiG's authentication and sessions, Argus and Windows/WSL2 acceptance are pending. The three-step start (ADR-006) is implemented: install.sh, the hestia launcher, one shared pi login and the first-run install of a checkout's declared tools. Verified on macOS arm64 with scripted tests and a non-interactive hestia -- --version run; not yet verified: a real interactive pi session and /login, an agent change built and tested in a real repository, and the M1-10 run by someone who has only read this page. Today's runbook is for verifying internals, not for getting started.
Needs Docker running and Git 2.31 or newer, on Apple Silicon macOS (the only exercised platform). Nothing else, no sudo.
-
Install. Clones Hestia to
~/.hestiaand linkshestiainto a directory already on yourPATH(if none is writable it prints one line to add to your shell profile):git clone https://github.com/brianluby/hestia.git ~/.hestia && ~/.hestia/install.sh
-
Run
hestiain a Git repository:cd <your-repo> && hestia. The first run builds the image (43 s measured with no Docker cache and the Debian base already pulled; a first-ever build also pulls the base) and installs the tools yourmise.tomlor.tool-versionsdeclares, then opens pi in a container that sees the same files as your host. Later runs reattach in a second or two.Only launch repositories you trust. Launching trusts the repository's mise configuration, which can run scripts in the workspace before pi opens. Every workspace shares one pi home, so those scripts, and the agent, can read your pi login and change pi settings for every repository.
-
Tell pi what to do. The first time, sign in with
/login; the login carries over to every repository.
Update with git -C ~/.hestia pull. The next hestia builds a new image once if the build inputs changed and recreates the workspace container on it (stop active pi sessions first; source, sessions and installed tools are kept). Old hestia-pi:* images stay until you remove them with docker rmi.
Recreating the container keeps source changes, Git metadata and agent sessions; caches can be rebuilt. Experts (identity, mounts, lifecycle, sandboxing, provider handoffs): workspace helpers. You never need them to get started.
- A minimal base containing OS utilities and mise; project toolchains and agents stay outside the default base.
- One canonical build definition, with verified dependencies and multi-architecture builds as design goals rather than existing support claims.
- Checkout identity derived from its canonical path, explicit Git worktree support, and host source separated from persistent agent/service state and disposable Linux caches.
- Optional agents and project services, not an agent orchestration framework.
- No default host Docker socket mount or broad credential/home-directory mounts.
The first milestone has two evidence stages: a nonproprietary fixture on the available Apple Silicon Mac, followed by the Argus pilot on the employer work laptop. Argus source, credentials, and employer-specific configuration stay there. Fixture success alone does not complete the milestone. omp retains AWS Bedrock as its default; the user-selected LiteLLM opt-in passes fixture acceptance. Work-laptop platform and Argus build/service requirements remain open.
Identity and worktree mount planning are part of the foundation; full concurrent workloads, backup/restore, and the broader platform matrix follow. A future browser IDE variant will share the terminal variant's tools and state. Browser IDE and voice implementation are optional, not prerequisites for terminal use.
- Tester runbook: verification of internals, not the user path. Step-by-step fixture setup, workspace checks, persistence, optional omp acceptance and regression commands.
- Milestone 1: user journey, acceptance checks, pilot boundaries, and open inputs.
- Synthetic fixture: nonproprietary build/test fixture for Milestone 1A evidence.
- Workspace identity: bounded checkout-derived identity helper (M1-04).
- Workspace mounts: scoped Compose generator for host checkouts and worktree metadata (M1-02/M1-05).
- Evidence log: observed platforms, versions, commands and results per requirement.
- nono best practices: configuring the optional nono sandbox CLI inside a workspace.
- Architecture: accepted design defaults, trade-offs, and remaining implementation choices.
- Roadmap: short, acceptance-driven implementation sequence.
- Contributor instructions: scope, evidence, verification, and safety expectations.