Troubleshooting

The problems people run into most, by what you see. The server's log has one line with its reason for anything off the normal path (Logs).

No model keyCopy Anchor Link

You see: the web app opens on Connect a model provider instead of the task box, a session over the API is refused with "Connect a model provider first", and the log says no model provider has a key yet.

Why: the agent runs on a model provider's API, and no provider has a key.

Fix: paste a key under Control center → Models, or set one such as ANTHROPIC_API_KEY in the server's environment and restart it. A key pasted in the web app works from the next session, with no restart.

No free network for a new sandboxCopy Anchor Link

You see: a new session never gets a sandbox, and the log says no free /28 in 10.234.0.0/16 after 64 tries, or Docker says it could not find an available, non-overlapping address pool.

Why: with Docker, every sandbox gets a network of its own. Pistis takes their addresses from 10.234.0.0/16; networks left behind by sandboxes removed outside Pistis, or another program using that range, can fill it. Docker's own address pools, which other networks use, hold only about 30 networks.

Fix: Pistis removes sandbox networks whose sandbox is gone (after five minutes) and tries again by itself. If it still fails, see what holds the addresses:

docker network ls --filter label=pistis.net=sandbox
docker network prune     # every unused network, not only Pistis's

If other programs need many networks too, give Docker larger pools with default-address-pools in /etc/docker/daemon.json and restart Docker.

pi-env exited before it was readyCopy Anchor Link

You see: pi-env exited with code 1 before it was ready in the log, often as checkpoint.failed, or a step ends "Outcome unknown · not run again".

Why: pi-env is the program Pistis talks to a sandbox through. Pistis reached for a sandbox that wasn't there to answer: it was killed, removed or restarted, or it was still reconnecting after the relay restarted.

Fix: usually none. Pistis waits for the sandbox to come back and connects once more; if it is gone, the session gets a new sandbox with its files restored from the last checkpoint (the copy of its files saved after each turn). A command that was running is not run again, and the agent is told. A checkpoint that failed is taken again after the next turn. If it happens to every session, check that the relay runs and sandboxes reach it:

docker ps --filter label=pistis.role=relay
docker logs <a sandbox's container>

The relay answers 401Copy Anchor Link

You see: new sessions get no sandbox and the log says relay enroll failed: HTTP 401 (the relay is the service sandboxes connect to), or a sandbox's own log shows 401 from the relay.

Why: the relay doesn't know the key it was given. Either the relay and the Pistis servers have different admin keys (PISTIS_RELAY_KEY was changed and only one side restarted), or a relay from a run that crashed is still answering on the same network.

Fix: remove relays that aren't this install's, and restart the relay and the servers with the same key:

docker ps -a --filter label=pistis.role=relay
docker rm -f <a relay that isn't this install's>
docker compose up -d --force-recreate relay brain1 brain2

Running sandboxes keep redialling and reconnect once the relay knows them.

The disk is fullCopy Anchor Link

You see: "no space left on device" in a step's output, in the log or from Docker; image builds fail; Postgres stops taking writes.

Why: Docker images and build cache grow with every build; stopped sandboxes keep their disks for seven days; each session keeps a checkpoint of its files, up to 256 MiB each.

Fix: see what takes the space, then free what isn't needed:

docker system df
docker builder prune     # build cache
docker image prune       # images no container uses

End sessions you're done with: ending one removes its sandbox and its checkpoints, and the transcript stays (DELETE /sessions/<id>, see the HTTP API). To keep sandboxes for less time, shorten lifecycle in pistis.json.