Getting started
torus installs four ways: pi package, single binary, container image, or source checkout. This page covers the install paths, the first five minutes of a session, and the permission modes with the automode rules. Each section links to its reference page for the full surface.
Install
As a pi package: you need pi installed first; its README covers installation. Then one command loads the full extension pack, skills, and agent roster, with no clone and no build:
pi install git:github.com/tankdonut/torus@vX.Y.ZLauncher-only surfaces (torus serve, torus acp-agent) are not part of this mode; see pi-packages.md.
As a single binary: download torus-<os>-<arch> from releases, make it executable, and run it. Node must be on your PATH; npm is not. The first launch boots offline, extracting the embedded payload and dependency tree (pinned engine included) into ~/.torus/runtime:
chmod +x torus-<os>-<arch> && ./torus-<os>-<arch>The boot needs no network. Set TORUS_BOOTSTRAP=network to bootstrap over npm instead; the launcher env rows in configuration.md cover it.
Verify the download before you run it: the release ships sha256sums.txt and attestations alongside the binary. The commands are in the verifying artifacts section of the README.
In a container (full toolchain, no host install):
docker run --rm -it -v "$PWD:/workspace" ghcr.io/tankdonut/torusFrom source (contributor path). Platform support is declared per extension, so on other platforms unsupported extensions skip loading with a notice instead of failing later; see extensions.md. tmux is optional, since delegation panes only appear inside tmux. The Node version floor is declared in package.json:
git clone https://github.com/tankdonut/torus.git && cd torus
./make.sh npmrc # one-time: dev-only .npmrc (agents are blocked; it never ships)
npm install
./runtime/bin/torus.mjsAll paths need provider auth on first run: /login zai signs in to the built-in Z.ai provider (GLM models). In containers, mount credentials read-only instead; see container.md.
First five minutes
Meet the roster, delegate something small, and try a keyword gate:
/roster: the agents, their model chains, and credentialed providers.- Delegate something small:
/explorer where does the roster load from? - Say
teamin a message (ordeepwork,blueprint). Keyword gates switch the session’s execution mode. /goalto pin a standing objective;/reflectto distill the session into memory.
Every delegation opens a tmux pane on the right, tailing what the agent does live. The statusline gains an entry per running child, and alt+t opens the fleet browser over every agent, where s steers one mid-run and x stops it. Handles steer from the input box too: type @handle <message> (tab completes live handles next to file mentions) to steer a running delegation or queue mail for a team member. The agents, their model chains, and the delegation tools are documented in the roster section of extensions.md.
Permission modes
torus starts in default mode: guards, sandboxing, and approval prompts judge tool calls as they run. Automode is an opt-in permission layer for unattended work: a decision model classifies each bash command, approves the safe ones, and asks before anything risky. Turn it on with torus --permission-mode auto or TORUS_PERMISSION_MODE=auto, or default it on with "permissionMode": "auto" in ~/.torus/config.json; 1 and on also select auto mode, while unset, 0, off, and default keep the built-in gate. The config key sets the default, the env var overrides it, and the flag sets the env var for one session. /automode reports the live status (naming where the mode came from) and switches the current session.
Bypass mode turns every permission guard off at once: torus --permission-mode bypass (or TORUS_PERMISSION_MODE=bypass) starts the session with the context guards, cc-safety-net, the sandbox, the approval dialog, and the automode classifier all disabled, and the statusline carries a red bypass chip while it runs. Bypass is startup-only: it cannot be set from config.json (a "bypass" value there is refused with a warning) or switched mid-session, so each bypass session is a deliberate launch.
Your rules run first, from the automode section of the unified config file ~/.torus/config.json (see configuration.md):
{
"automode": {
"deny": ["git push --force *", "npm publish *"],
"ask": ["git push *", "npx *"],
"allow": ["npm test *", "node --test *"],
"environment": [
"Source control: github.com/tankdonut and all repos under it",
"Package registry: the default npm registry is fine"
],
"softDeny": ["leave the staging database untouched"],
"softDenyExceptions": ["pg_dump against staging for a nightly backup"],
"hardDeny": ["never read or send ~/.ssh credentials anywhere"],
"classifyAllShell": false
}
}Entries are prefix patterns evaluated in deny, ask, then allow order; broad allow entries such as * match nothing and draw a warning at load. A fixed critical-operation floor covers sudo and su, recursive forced rm on root or home paths, force pushes, and recursive chmod or chown on root paths, and floored commands never take an allow-rule shortcut; classifyAllShell suspends allow rules while auto mode is on. The environment, softDeny, softDenyExceptions, and hardDeny entries are prose for the judge: a softDeny entry denies unless a matching softDenyExceptions entry or a recent, specific user intent line clears it. Read-only commands pass without a model call, three consecutive decision-model denies switch the session to asking for everything, and when every model path fails the command still runs unjudged with an [automode] notice in its tool result. Automode only adds gates: denials from guards, cc-safety-net, sandbox, and approval still win, and every decision appends one JSON line to automode.log.
/automode denied lists the last denials from the audit log, and /automode setup drafts environment entries from the repo’s git remotes and ask entries from repeated audit denials. The full pipeline order, judge tiers, classifier pinning, and fallback chains are in the automode section of extensions.md.
Where next
The reference pages, by surface:
- configuration.md: every config section, knob, and env var
- extensions.md: every tool, command, and env var
- serve.md: the authenticated HTTP server and the ACP agent
- container.md: container usage and flags
- pi-packages.md: the pi-package install model and what it omits
- skills.md: skill manifests, import, and export