Custom sandbox images

Custom sandbox images let you prebake the repository, dependencies, compiled output, and test harness your agents need. Instead of spending minutes provisioning a workspace on every run, your agents start on the actual task immediately.

Why use a custom image

Custom images eliminate cold-start setup work (clone, install, transpile, and bootstrap) so agents spend their time on the actual task. They also reduce setup variance and lower sandbox memory requirements by keeping only what the agent needs.

Build your own custom image

The Faheem Code agent-server sandbox guide provides full documentation on building custom sandbox images. The approach is the same for the Enterprise Replicated VM deployment.

Basic pattern

1. Start from the Faheem Code agent-server base image.
2. Keep the normal Faheem Code entrypoint intact: extend the image, do not replace the entrypoint.
3. Add your repo, docs, tools, and verification wrappers.
4. Pre-run the expensive setup you do not want to repeat at task time.
5. Publish the image to a registry and point the Replicated installer at it.

Warning

Do not override the entrypoint or replace the runtime contract of the base image. The installer expects standard Faheem Code agent-server behavior. Only extend, do not replace.

Base image

FROM ghcr.io/smart-national-solution/faheem-code-agent-server:1.41.0-python

Pin a specific version tag to ensure reproducible builds. Check ghcr.io/smart-national-solution/faheem-code-agent-server for the latest available tags.

Version compatibility

Each Faheem Code Enterprise release expects a specific agent-server version. The base image tag you build from must match the release you run: the faheemcode-sdk inside the sandbox and the one inside the Faheem Code application must agree on major and minor version.

To find the expected tag, enable Use a Custom Sandbox Image in the Admin Console. The Sandbox Image Tag field defaults to the tag the current release expects.

When a conversation starts on a custom image, Faheem Code checks the sandbox's agent-server version. If it does not match the release, the conversation fails with an error naming the expected and actual versions. Rebuild your image from the expected tag and update the Sandbox Image Tag field to fix it.

Note

Rebuild your custom image before each upgrade. The agent-server base image changes with every FCE release, and an image built for an older release will be rejected by the version check.

Example: build and push

docker buildx build \
  --platform linux/amd64 \
  -f your-project/Dockerfile \
  -t ghcr.io/<your-org>/faheem-code-custom-image:<your-tag> \
  --push \
  .

Use --platform linux/amd64 because the Enterprise Replicated VM runs on x86-64.

What to bake in

Good candidates for prebaking:

• Pinned repository checkouts
• Package manager caches and installed dependencies (node_modules, Python virtualenvs, etc.)
• Compiled or transpiled output
• Native system packages (xvfb, libkrb5-dev, pkg-config, etc.)
• Browser or Electron artifacts
• Stable helper scripts such as prepare-* and *-verify wrappers

What to keep out

Warning

Do not bake the following into your image:

• Secrets, API keys, or personal credentials
• Machine-specific paths or environment assumptions
• Uncommitted source changes or task-specific fixes
• Rapidly changing dependencies (use a lightweight prepare-* helper instead)

If the repository or dependencies change frequently, include a prepare-* script in the image so the agent can refresh only the parts that need updating without a full rebuild.

Configure the Replicated VM installer

Once your image is built and pushed to a registry, point the Replicated Admin Console at it.

1. Open the Admin Console at https://admin.<your-base-domain>:30000.
2. Navigate to Config and find the Sandbox Image section.
3. Set the following fields:

Field	Value
Use a Custom Sandbox Image	Enabled
Sandbox Image Repository	Your image repository (e.g. ghcr.io/your-org/faheem-code-custom-image)
Sandbox Image Tag	Your image tag (e.g. v1.2.0)
Registry Server	If your registry requires authentication
Registry Username	If your registry requires authentication
Registry Password or Credentials	If your registry requires authentication

4. Click Save config and then Deploy to apply the change.

Note

This setting applies to the sandbox / agent-server image only (the image that runs inside each agent's isolated workspace). It does not replace the other Faheem Code service images.

Reference

• Faheem Code custom image example repo: Dockerfile, benchmark scripts, and analysis tooling for the VS Code custom image example.
• Agent-server sandbox guide: full SDK documentation on building and configuring custom sandbox images.