Run it for a team

The compose file in deploy/compose runs everything a team needs on one Docker host: HTTPS, a database and two Pistis servers that cover for each other. Then you set up sign-in, code hosts and agents in the web app.

Before you startCopy Anchor Link

• A Linux host with Docker and compose
• A domain name pointing at the host, for a real certificate

Start itCopy Anchor Link

1. Get the compose file and create the settings file with its keys:

git clone https://github.com/akshay5995/pistis && cd pistis/deploy/compose
cp .env.example .env && sh keys.sh >> .env

1. Edit .env. Set PISTIS_DOMAIN to your domain, PISTIS_TLS to your email for a Let's Encrypt certificate, and PISTIS_MODEL with its provider's key (ANTHROPIC_API_KEY for the one it starts with). You can also leave the key empty and paste it in the control center. PISTIS_VERSION is the release to run.
2. Start it. Compose pulls that release's images from GitHub's container registry:

docker compose up -d

1. Find the setup link in the logs of the two Pistis servers, brain1 and brain2 (a brain is a Pistis server process):

$ docker compose logs brain1 brain2 | grep "setup link"
brain1-1  | pistis serve: no administrator yet — setup link https://pistis.example.com/link/8a8b…#k=rK4z…

1. Open the link and type your name. You are the first administrator. The link works once, for an hour.

Set it up in the control centerCopy Anchor Link

As an admin, click Control center in the sidebar. Its first page lists what's left to set up, with a button for each step:

1. Connect a model provider. Paste an API key on Models → Connect a provider. Its models can be picked from the next session on, with no restart. Keys are encrypted with PISTIS_SECRET_KEY and never shown again.
2. Connect a code host. Source control → Add GitHub App. See Connect GitHub.
3. Invite your team. Add a sign-in method (Sign-in → Add OpenID Connect or Sign-in → Add GitHub), then let your colleagues in with your email domain. See Sign-in and people.
4. Run a first session. Start opens a new session with a one-line task filled in. It needs a model provider but no repository.

The same page then shows what runs now, which sessions wait for someone's approval or answer, and tokens and spend over the last two weeks. Usage breaks spend down by person and by model, Fleet lists the Pistis servers and each live session's sandbox, and People lists everyone with their role.

Pick a modelCopy Anchor Link

.env starts with PISTIS_MODEL=anthropic/claude-sonnet-5-5 and an empty ANTHROPIC_API_KEY. Every session gets that model by default while its provider has a key, else the first model that has one. Set PISTIS_MODEL=provider/model-id and run docker compose up -d again to change the default. A key in .env works as well as one pasted in the control center. With no key at all, the web app's first screen asks for one and sessions don't start.

People can switch a session to any model from a provider with a key. To choose which ones they see, open Models, untick the ones to hide under Choose what people can pick and click Save. A model from a key you add later is offered until you untick it. Sessions already on a model you hide keep it; nobody can switch to it.

What runsCopy Anchor Link

Keep .env private: it holds the keys. docker compose down and up keep all data, and running sandboxes reconnect. To move to a new release, see Upgrade.

ImagesCopy Anchor Link

Each release is published as four images on GitHub's container registry, for amd64 and arm64, tagged with its version:

Compose takes the version from PISTIS_VERSION and the registry from PISTIS_REGISTRY in .env. Set PISTIS_SANDBOX_IMAGE to run sessions on another image, such as the browser one or your own.

To build the images yourself instead, run pnpm install && pnpm images in the repository (it needs Node 24, pnpm 10 and Bun). It also writes docker-compose.override.yml next to the compose file, which compose reads on its own, so docker compose up -d runs your builds. Delete that file to go back to the published images.

If a server diesCopy Anchor Link

The other Pistis server takes over its sessions within seconds. A task that was running finishes there. A command that was cut off is not run again; the agent is told. The sandbox kept running, so its files are still there.

Run a single process insteadCopy Anchor Link

Without compose, pistis serve runs Pistis from one config file:

PISTIS_SECRET_KEY=… DATABASE_URL=… pnpm pistis serve --config pistis.json

See Configuration for every key.