torusv0.24.0docs

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.

FactValue
Payloadbaked 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 asnon-root user torus (uid 1000), WORKDIR /workspace
Env / entrypointTERM=xterm-256color; ENTRYPOINT torus
Tagslatest 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/torus

Anything 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-models

Provider 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:ro

Sandboxing

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:

ToolVersion / source
node + npmpinned by .tool-versions (base image node:<pin>-slim)
torus payload + pi enginebaked 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 / typescriptglobal npm pins in the Dockerfile’s npm i -g layer
tmux, bubblewrap, socat, git, ripgrep, notify-send (libnotify)apt (distro packages)
bash, script, whichbase image