CLI
Every pistis command and flag.
Run commands from the repository root as pnpm pistis <command>. In the pistis/pistis image, run node packages/pistis/src/main.ts <command>.
pistis dev
Runs Pistis on your machine with SQLite and Docker sandboxes. It writes its settings to .pistis/pistis.json.
| Flag | Meaning |
|---|---|
--port | Port for the web app and the API, on 127.0.0.1. Default 7777. |
--model | provider/model-id new sessions start on (or PISTIS_MODEL). Default: the first model whose provider has a key. |
--data | Where Pistis keeps its data. Default .pistis. |
--database | A Postgres URL instead of SQLite (or PISTIS_DATABASE_URL) |
--require-approval | A tool that waits for the session's owner. Repeatable. |
--auto-mode | Let people send a message in Auto mode (Approvals). |
--allow-registry | A host the sandbox may reach: npm, pypi, crates, go, a host or host:port. Repeatable. |
--internet | Let sandboxes reach the whole internet |
--mcp | A file of MCP servers |
--image | The sandbox image. Default pistis/pistisd:dev. |
--browser | Sandboxes from the browser image, pistis/browser:dev (A browser in the sandbox) |
--desktop | Sandboxes with a whole desktop, from pistis/desktop:dev (A whole desktop) |
--plugin | A plugin package to load. Repeatable. |
--pause-after, --stop-after, --delete-after | When idle sandboxes are paused, stopped and deleted. Defaults 2m, 30m, 7d. |
--namespace | Label for this server's sandboxes in Docker. Default dev. |
--network | The Docker network Pistis uses. Default pistis-int. |
| Variable | Meaning |
|---|---|
PISTIS_TOKEN | A fixed API token, 16 characters or more. Otherwise a new one is printed on every start. |
PISTIS_USERS | alice=<token>,bob=<token>: a token per user |
PISTIS_HOOK_SECRET | Turns on webhooks |
pistis serve
pnpm pistis serve --config pistis.jsonRuns Pistis from a config file (Configuration).
pistis admin link
pnpm pistis admin link --config pistis.json --new-admin <name>
pnpm pistis admin link --config pistis.json --user <email>Prints a one-time sign-in link, valid for an hour, for a new admin or an existing person. Use it when nobody can sign in. It is recorded in the audit log.
pistis admin slack
pnpm pistis admin slack key --config pistis.json
pnpm pistis admin slack link --config pistis.json --slack <team id>:<user id> (--user <email> | --new-person <name>)key issues the Slack app's key, shown once. link links a Slack user to a person. See Slack.
pistis attach
pnpm pistis attach <session> [--url http://127.0.0.1:7777] [--token …]Follows a session in the terminal. Each line you type is sent as a message, except these commands: /plan <message> and /auto <message> send it in Plan or Auto mode, /models lists the models you can pick (the session's is marked *), /model <provider/model> [thinking] switches the session to one, from its next step on, /stop stops the agent, /pause and /resume pause it for everyone, /rename <name> names the session, /decisions lists who decided what and /flow asks the agent to draft a flow from the session. A step that waits for approval prints with approve? y/n: type y or n to decide it (the oldest, when several wait), or /approve [key] and /deny [key] any time. PISTIS_URL and PISTIS_TOKEN set the defaults.
pistis connect
pnpm pistis connect <server> [--url http://127.0.0.1:7777] [--token …] [--paste <token>]Connects your own account to a per-person MCP server. With OAuth, prints the link to open in a browser signed in to Pistis as you; --paste sends a token for a server that takes one. See Connect with OAuth.
pistis doctor
pnpm pistis doctor --url <url> --token <token> --metrics <metrics url>… [--json out.json] [--target name=seconds]…Measures a deployment against targets and exits 1 if one is missed. See Check your deployment.
pistis rotate-secret
PISTIS_SECRET_KEY=<current> PISTIS_NEW_SECRET_KEY=<new> pnpm pistis rotate-secret --config pistis.jsonRe-encrypts every stored secret with a new key. Stop every server first. See Operate.
pistis docker-proxy
pnpm pistis docker-proxy --namespace <ns> [--listen 0.0.0.0:2375] [--socket /var/run/docker.sock]Gives Pistis Docker access limited to its own sandboxes. See Operate.
pistis verify
pnpm pistis verify [unit]For people working on Pistis itself: runs the repository's end-to-end checks in scripts/verify/. Name one check, or leave it out to run every finished one.
pistisd join
PISTISD_SERVER=… PISTISD_POOL_TOKEN=… pistisd joinJoins one of your own machines to a pool. Settings: PISTISD_NAME, PISTISD_LABELS, PISTISD_SLOTS, PISTISD_WORKDIR, PISTISD_KEEP_DAYS. See Use your own machines.