Custom Images

Run any agent as a managed agent, not only the built-in ones. Bring a container image with your agent in it. Archestra supplies the rest:

• The task and every follow-up.
• Models through the LLM Proxy, and tools and skills through the MCP Gateway.
• Persistent storage and the live terminal.

Use Your Image

1. In the agent's Runtime picker, pick Custom image.
2. Set Image, and set Command to your agent's executable and arguments.
3. Set Inference API to the protocol your agent speaks: Anthropic Messages, OpenAI Responses, or OpenAI Chat Completions.
4. Start a run.

Your agent reaches models through the supplied LLM Proxy URL and virtual key, and tools and skills through the supplied MCP Gateway.

What the Image Needs

For the full contract and working examples, see the image contract and the maintained images.

Add a Toolchain

Extend your agent's current image to install a compiler such as Go while keeping its agent and runtime setup.

Save this as Dockerfile:

ARG BASE_IMAGE
FROM ${BASE_IMAGE}
USER root
RUN apt-get update \
 && apt-get install -y --no-install-recommends golang-go \
 && rm -rf /var/lib/apt/lists/*
USER 1000:1000

1. Build the image, replacing the base image with the value in your agent's Image field:

   bash

   docker build --build-arg BASE_IMAGE=<current-agent-image> -t <registry>/claude-code-go:v1 .
   docker push <registry>/claude-code-go:v1
   

2. Set the agent's Image to your published image. Keep its existing Command and Inference API.

3. Start a new run and ask the agent to run go version, then compile your project.

What to know:

• This example uses the Debian-based built-in image and Debian's packaged Go version. Install the version your project requires if it differs.
• The Kubernetes cluster must be able to pull your published image.
• Supply repository tokens through the agent's environment settings, rather than including them in the image.

Send the Run Headers

Send four headers on every request to the LLM Proxy and the MCP Gateway. They tie each model call and tool call to its run, so its logs group together and its Guardrails restrictions carry across follow-ups.

Each value is an environment variable that Archestra sets in the container.

• Maintained images: an image built on a maintained image sends all four when it runs that image's launcher. Keep the base tag current, because a launcher sends only the headers its version knows.
• Every turn: the binding is new for each turn, and Archestra starts your command again for each turn. Set the header from the variable on every start, not once per container. A copy saved from an earlier turn is rejected.
• A credential: send the binding only to the supplied LLM Proxy and MCP Gateway. Never print it, and never pass it to a model provider or a tool.

Troubleshooting

Each of these is an HTTP 400 on a model request while Guardrails are on.