Give the sandbox what it needs

A session's sandbox starts from an image with git, and Pistis copies the repository in. Your tests may need more: a language toolchain, a browser, a package registry, a database. This page shows how to give the sandbox each of them.

Your own imageCopy Anchor Link

Build an image on the base you already use and copy Pistis's sandbox program into it. Any Linux base works, glibc or musl:

FROM node:24-bookworm
COPY --from=ghcr.io/akshay5995/pistisd:<version> /usr/local/bin/pistisd /usr/local/bin/pistisd-musl /usr/local/bin/pi-env /usr/local/bin/pistisd-entry /usr/local/bin/
RUN mkdir -p /workspace
WORKDIR /workspace
ENTRYPOINT ["/usr/local/bin/pistisd-entry"]

Put in it whatever a fresh checkout needs to build and test: compilers, package managers, system libraries. Then tell Pistis to use it:

With Docker, Pistis never pulls a sandbox image: it must be on the host already. Compose pulls the one in PISTIS_SANDBOX_IMAGE for you; elsewhere, docker pull or build it on the host. On Kubernetes the nodes pull it as usual.

A browserCopy Anchor Link

For the agent to open web pages, the image needs Chromium; Pistis finds it and offers the browser tools by itself. On Debian, add apt-get install -y chromium, or start from ghcr.io/akshay5995/pistis-browser, which has Debian's Chromium, Node and git. Other bases are listed in A browser in the sandbox.

Network accessCopy Anchor Link

Pistis clones the repository on your server, so the sandbox needs no network for git. By default it reaches nothing else. To install packages during a session:

• Docker: list the hosts it may reach in sandboxes.allow (shorthands npm, pypi, crates and go), or --allow-registry npm with pistis dev. A proxy lets those through and logs each request. sandboxes.internet opens the internet but not other sandboxes.
• Kubernetes: sandboxes.egress=open lets sandbox pods reach the internet but never private address ranges.

Faster and safer still: install the packages in your image, so a session needs no network at all. See Sandboxes for how each setting works.

Databases and servicesCopy Anchor Link

A database or service your tests need can run inside the sandbox: install it in the image and start it from the tests, or from a setup script the agent runs. Nothing outside the sandbox can reach it.

Secrets your tests needCopy Anchor Link

Pistis can't yet give one agent's sandboxes a secret of their own, such as a token for a test account. Until it can:

• Prefer tests that need no secret. Run the database in the sandbox, and fake the outside services the tests call.
• Put work that needs a real key in a tool on your server: an MCP server or a plugin tool. It keeps the key, every call is recorded, and it can wait for approval.
• If you must, bake a low-value test key into your own image. Every session on that image can read it, and so can any code the agent runs, so use a key that can only touch test data and that you can revoke.