Skip to main content

Custom sandbox

The sandbox is where the agent performs its tasks. Instead of running commands directly on your computer (which could be risky), the agent runs them inside a Docker container.

How the sandbox works in V1​

In Faheem Code V1 the sandbox container is the Faheem Code agent-server. By default Faheem Code runs ghcr.io/alsairy/faheem-code-agent-server:<release>-python, which already includes Python and Node.js. The image is resolved from two environment variables:

  • AGENT_SERVER_IMAGE_REPOSITORY (default ghcr.io/alsairy/faheem-code-agent-server)
  • AGENT_SERVER_IMAGE_TAG (default <release>-python)

Because the sandbox is the agent-server, you can't just swap in an arbitrary base image — the container has to keep running the agent-server. To add custom tooling you build a custom agent-server image on top of your chosen base image, then point Faheem Code at it.

Building a custom agent-server image​

The agent-server is built from a Dockerfile in the Faheem Code SDK that accepts a BASE_IMAGE build argument. Any Debian-based image works as the base.

For example, to layer the agent-server onto an image that has ruby installed, first build (or pick) your base image. To build one:

# Dockerfile.base
FROM nikolaik/python-nodejs:python3.12-nodejs22

# Install required packages
RUN apt-get update && apt-get install -y ruby
docker build -t my-base:latest -f Dockerfile.base .

Then build the agent-server image on top of it. Clone the Faheem Code SDK and, from the repository root, run:

docker buildx build \
  --build-arg BASE_IMAGE=my-base:latest \
  --target binary \
  -f faheemcode-agent-server/faheemcode/agent_server/docker/Dockerfile \
  -t my-agent-server:custom \
  --load \
  .
  • --build-arg BASE_IMAGE= selects the base image to layer the agent-server onto.
  • --target binary matches how the default published -python image is built — it bundles a self-contained agent-server binary (no Python virtual environment at runtime) and includes VSCode and VNC. Other targets are available if you need them: source runs the agent-server from a Python virtual environment (handy for development and debugging), and the binary-minimal / source-minimal targets drop VSCode and VNC for a smaller image.
  • --load makes the resulting image available to your local Docker daemon.

This produces a local image called my-agent-server:custom.

Pointing Faheem Code at your image​

Set both environment variables so Faheem Code launches your image as the sandbox. They must be set together — if either is missing, Faheem Code falls back to the default image:

docker run -it --rm --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=my-agent-server \
    -e AGENT_SERVER_IMAGE_TAG=custom \
    ...

If you start Faheem Code with Docker Compose, set the same variables there:

environment:
  - AGENT_SERVER_IMAGE_REPOSITORY=my-agent-server
  - AGENT_SERVER_IMAGE_TAG=custom

When the sandbox starts, Faheem Code launches your image on port 8000 and polls /health until the agent-server is ready.