Container image
torus ships as a prebuilt multi-arch image (linux/amd64 + linux/arm64) on GHCR: ghcr.io/tankdonut/torus, built by container CI. Each platform builds exactly once per run (amd64 on the test runner, arm64 on a native ARM runner) and pushes by digest. The multi-arch tags are assembled from those digests only after the container test suite has passed against the amd64 build. The build stage compiles the single-file bun launcher from a source snapshot and bakes the payload tree with its npm dependencies.
| Fact | Value |
|---|---|
| Payload | baked at /opt/torus (TORUS_ROOT) with npm deps and the pinned pi engine; containers boot offline |
| Base image | .tool-versions-pinned node:*-slim, pulled via mirror.gcr.io (avoids Docker Hub rate limits) |
| Runs as | non-root user torus (uid 1000), WORKDIR /workspace |
| Env / entrypoint | TERM=xterm-256color; ENTRYPOINT torus |
| Tags | latest on merges to main; X.Y.Z and X.Y immutable on version tags |
Quickstart
docker run --rm -it -v "$PWD:/workspace" ghcr.io/tankdonut/torusAnything after the image name goes to torus as argv. The payload and its npm dependencies (the pinned pi engine included) are baked into the image at /opt/torus, and TORUS_ROOT points the launcher there. With the baked root in place, containers boot instantly, extract nothing, and need no network access. If TORUS_ROOT arrives unset or empty, the binary’s embedded payload and dependency tree serve as the in-image fallback, extracted offline inside the container. --list-models works with no credentials:
docker run --rm ghcr.io/tankdonut/torus --list-modelsProvider auth
Keyless runs (CI, --list-models) stay clean; real agent use needs provider auth. Mount it read-only:
-v ~/.pi/agent/auth.json:/home/torus/.pi/agent/auth.json:roSandboxing
Not supported inside the container. TORUS_SANDBOX (and TORUS_SANDBOX_DEFAULT) default to off and should stay off there. The container itself is the isolation boundary, and bwrap’s nested user namespaces conflict with container-runtime policy on most hosts (verified: rootless podman, GitHub runners, and Ubuntu 24.04+ hosts with apparmor_restrict_unprivileged_userns=1). torus /doctor reports the live sandbox state. The image still ships bwrap + socat as part of the full-toolkit inventory below; they are not exercised in-container.
Versions & updating
.tool-versions is the single source of truth for the node and bun versions. CI reads it (setup-node node-version-file, setup-bun bun-version-file); ./make.sh image and the CI platform builds pass the bun pin as a build arg (the base image tag is digest-pinned in the Dockerfile and test-synced to the node pin here). Renovate’s asdf updates move the container image versions with no separate bump.
Two pins are renovate blind spots and must be bumped by hand: the Dockerfile ARG AST_GREP_VERSION and the global npm pins for typescript-language-server/typescript.
Local build and test mechanics and the GHCR first-publish note live in docs/internals.md.
What’s inside
Full-toolkit flavor:
| Tool | Version / source |
|---|---|
| node + npm | pinned by .tool-versions (base image node:<pin>-slim) |
| torus payload + pi engine | baked at /opt/torus from the repo payload manifest (engine pin promoted from devDependencies), deps resolved through the baked payload lock; the payload ships no .npmrc |
ast-grep (both the sg shim and ast-grep) | GitHub release pinned by the Dockerfile ARG AST_GREP_VERSION |
| typescript-language-server / typescript | global npm pins in the Dockerfile’s npm i -g layer |
| tmux, bubblewrap, socat, git, ripgrep, notify-send (libnotify) | apt (distro packages) |
| bash, script, which | base image |