Quick start

You will start Pistis, give an agent a task in the browser and watch it run. Then you will crash its sandbox and see that nothing is lost.

Before you startCopy Anchor Link

• Docker, with the daemon running
• An API key from one model provider, such as Anthropic, OpenAI or Google
• Node 24 or newer

Start PistisCopy Anchor Link

1. Make a folder for your server:

npm create pistis my-server
cd my-server

It has one example flow in flows/ and a .env.example that names the key. Copy it to .env and fill in your key, or paste the key in the browser later.

1. Start Pistis:

$ npx pistis dev
Open http://127.0.0.1:7777 in your browser

The first start downloads the sandbox images, which takes a few minutes. Then Pistis opens the address in your browser. Leave the terminal running.

To work on Pistis itself, run it from a clone instead. This also needs pnpm 10 and Bun 1.2 or newer, and the first start builds the images:

git clone https://github.com/akshay5995/pistis && cd pistis
pnpm install
ANTHROPIC_API_KEY=… pnpm pistis dev

1. Type your name and continue. You are now the administrator.

Started without a key? The first screen asks you to connect a model provider. Click Add an API key, paste the key on the Models page and come back. No restart is needed.

Give the agent a taskCopy Anchor Link

1. Under What should the agent do?, type this task:

Show which machine you're on and list /workspace

1. Click Start session.
2. Watch the session. Each step shows a command the agent ran, then its output as it arrives. The status at the top reads Working, then Idle when the agent is done. The first command can take up to 30 seconds while the sandbox starts.

Crash the sandboxCopy Anchor Link

1. Click New session and start a task that takes a while:

Run sleep 60 in the shell, then tell me it finished

1. While it runs, kill this session's sandbox from a second terminal. Use the session id from the address bar (/s/ses_…):

docker kill $(docker ps -q --filter label=pistis.session=ses_…)

1. Look at the step. It shows Outcome unknown · not run again. Pistis can't know how far the command got, so it tells the agent instead of running it twice.

1. In the reply box, Ask for a change or a follow-up, type List the files in /workspace again and click Send. Pistis brings the sandbox back and the session carries on with its files.

This is what stops a half-finished deploy or migration from running twice. The agent stops and asks you.

Pick a modelCopy Anchor Link

Sessions start on the first model with a key. To choose the default, start Pistis with --model provider/model-id:

ANTHROPIC_API_KEY=… npx pistis dev --model anthropic/claude-sonnet-5-5

From a clone, it is pnpm pistis dev with the same flags. Any hosted provider works the same way, with its key in its usual environment variable (OPENAI_API_KEY, GEMINI_API_KEY, …) or pasted on the Models page. Your sessions and settings stay in .pistis/.

Next stepsCopy Anchor Link