Build a custom image

You can run an Agent37 instance from any Docker image. Register it as a workspace template in one of two ways:

Your image	Register with	What Agent37 needs
Not built yet, local, or private	A cloud build	A folder with the `Dockerfile` and the files it `COPY`s. Agent37 runs the build; no local Docker needed.
In a public registry	`image_ref`	A fully qualified reference that Agent37 can pull anonymously during registration.

A cloud build fetches everything itself — the FROM base image and anything RUN downloads — so those sources must be publicly reachable. There is no build-secret or private-registry-credential support yet; if your base image is private, contact support. A complete example — a Dockerfile, an example skill, a registration script, and a tiny LLM proxy — lives in custom-agent-image/, ready to copy into your own repo. This page is the walkthrough; Templates → build on the Hermes base image is the reference for the contract.

When you register a template, Agent37 copies your image once into private storage and pins it by digest. That snapshot is what every instance runs, so registering takes up to a few minutes for a large image. Re-pushing the same tag later does nothing: publish a new tag and update the template, or re-run the cloud build. Your image is stored privately and never republished.

1. Choose a starting image

To customize Hermes, build on ghcr.io/agent37-platform/hermes-base. It includes Hermes, the gateway, Chromium, and the standard toolchain. This example adds a CLI and a skill:

FROM ghcr.io/agent37-platform/hermes-base:latest

USER root
RUN apt-get update && apt-get install -y --no-install-recommends your-cli \
 && rm -rf /var/lib/apt/lists/*
COPY your-skill/ /usr/local/share/agent37/default-skills/your-skill/
USER node

Bake binaries into /usr/local/bin, skills into /usr/local/share/agent37/default-skills/ (the entrypoint copies them to ~/.hermes/skills at boot), and everything else into /usr/local or /opt — never /home/node or /home/linuxbrew, which are masked at runtime. Keep the base ENTRYPOINT. See the full contract. You can also use an existing image or start from any base. Its main process must keep running. If it serves HTTP, bind it to 0.0.0.0 and note its listening port; you will pass that as default_port when you register the template. An image with no HTTP service can omit default_port and be driven through exec, but it still needs a long-running ENTRYPOINT or CMD.

Your built image freezes its base at build time. :latest is convenient while getting started; pin a dated Hermes base tag for reproducible production rebuilds. Find published tags on GHCR, or read the current tag from agent37-hermes’s image_ref on GET /v1/templates.

2. Verify it locally (optional)

You don’t need Docker to publish — the cloud build does the real build. If you have Docker, a local build is still the fastest way to test before publishing. Plain docker build stores the amd64 result in your local Docker, including on an Apple Silicon Mac:

docker build --platform linux/amd64 -t my-agent:v1 .
docker image inspect my-agent:v1 --format '{{.Os}}/{{.Architecture}}'
# linux/amd64

Run the image locally if it is practical: registration validates the image, but only a running container proves that its entrypoint and service work. If you take the public registry path, this local linux/amd64 build is also the artifact you push.

3. Register the image

You have two ways to get the image to Agent37. Either way the resulting image is capped at 8 GB decimal (8,000,000,000 bytes), and either way the platform copies it once into private storage at registration.

Registration is synchronous and can take a few minutes for a large image. The returned image_digest identifies the immutable private copy every instance runs. Re-pushing a mutable source tag does not change that copy.

Build it in the cloud

Use this path when the image isn’t in a public registry — or doesn’t exist yet. You upload a small build context (the Dockerfile and the files it COPYs), and Agent37 builds the image on its own infrastructure:

export AGENT37_API_KEY=sk_live_...
npx agent37 templates build . --name my-custom-agent

What it does:

Packs the directory (default .; it must have Dockerfile at its root) into a gzipped context, excluding .git and your .dockerignore patterns (plain patterns only; ! negations are ignored). The context is capped at 100 MB — it holds the Dockerfile’s inputs, not the image, so it stays small.
Everything else in the folder ships with the context — a stray .env or key file included, and a COPY . . bakes it into the image. Check the folder, or add a .dockerignore, before you build.
Builds the image on Agent37’s infrastructure and streams the live build log to your terminal. On failure the command exits non-zero with the failing step visible.
Publishes the result as the workspace template. --name defaults to the folder name; --default-port <port> sets the template’s default port. Re-building an existing name publishes a new template revision; existing instances never change.
Ctrl-C does not cancel the build; it continues server-side and still publishes on success.

Builds are free, run one at a time per workspace, and time out after 45 minutes. The built image is capped at 8 GB decimal like any template image, and practically tops out around 4 GB today; if you need more, contact support. Everything the build fetches — the FROM base image, anything RUN downloads — must be publicly reachable; there is no build-secret or private-registry-credential support yet. A template published this way has an image_digest but no image_ref, because there is no public registry reference. To script the same flow without the CLI, see the raw contract in Templates → build an image in the cloud.

Import a public registry image

Push the image to any public OCI registry, then register its fully qualified reference. For example:

docker tag my-agent:v1 ghcr.io/you/my-agent:v1
docker push ghcr.io/you/my-agent:v1

On GHCR, make the package public after the first push (Packages → Package settings → Change visibility → Public). The starter example includes a GitHub Actions workflow that builds linux/amd64 and publishes immutable commit tags. Register a specific tag, not latest:

curl

curl -X POST https://api.agent37.com/v1/templates \
  -H "Authorization: Bearer $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "my-custom-agent", "image_ref": "ghcr.io/you/my-agent:v1" }'

Agent37 needs anonymous access only while it copies the image. The template and its instances no longer depend on the source registry after registration. A future image update needs a new public tag.

If your own image serves HTTP on port 8000, declare it: pass --default-port 8000 on the build, or include "default_port": 8000 beside name and image_ref. The bare instance URL then routes to that port, and instance creation probes it at boot. Omit it for hermes-base, whose gateway uses the 3737 fallback, or for a long-running private sandbox with no HTTP service.

4. Create an instance

curl

curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template": "my-custom-agent" }'

The result is a standard Agent37 instance running your image: same lifecycle, exec, and routed URLs as any other. Confirm your CLI shipped, without needing a model:

curl

curl -X POST https://api.agent37.com/v1/instances/<id>/exec \
  -H "Authorization: Bearer $AGENT37_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "command": "your-cli --version" }'

If the instance comes up failed instead of running, read its logs. An entrypoint that exits, a missing binary, or a service that never listens on default_port are the usual causes. exec cannot help until the container is running.

5. Bring your own model

hermes-base is clean: it boots with no LLM provider (standard Agent37 instances use Agent37’s managed model; this base is for bringing your own). To run an instance on your own model, point Hermes at any OpenAI-compatible endpoint — your own proxy, or a provider directly — by writing ~/.hermes/config.yaml on the instance:

model:
  provider: "custom:MyProvider"
  default: "moonshotai/kimi-k2.7-code"        # the model id your endpoint serves
custom_providers:
  - name: "MyProvider"
    base_url: "https://your-llm-proxy.example.com/v1"   # must end in /v1
    api_key: "your-proxy-token"
    api_mode: "chat_completions"
    model: "moonshotai/kimi-k2.7-code"

Your endpoint must serve the two OpenAI-compatible routes Hermes uses: GET /v1/models (to resolve the model id) and POST /v1/chat/completions (the turn). The example folder includes a ~40-line llm-proxy/ that implements exactly these and forwards to OpenRouter with your key — a minimal pattern to deploy and adapt. Write the config over exec or the instance terminal; it lives on the persistent volume, so it survives restarts. Then send a message and the agent runs on your model.

Want chat to work out of the box on Agent37’s managed model instead? Build FROM ghcr.io/agent37-platform/hermes:<tag> (tags on GHCR) — the full image wires the managed model — and pass a budget on create.

Keep it current

Your image freezes its base; rebuilding is how it picks up platform updates. Each template revision is an immutable snapshot, so a new build takes effect only after the template changes: re-run the cloud build under the same name, or publish a new registry tag and PATCH image_ref. Every successful build and every changed image_ref increments the template’s automatic revision; a re-build counts even when its digest matches the previous image. PATCHing the same image_ref string deliberately reuses the existing snapshot and revision. Existing instances keep their installed template_revision. Update each instance to recreate it from the template’s current revision. A skill already seeded into an instance’s ~/.hermes/skills is not overwritten on update — only fresh instances get a changed skill.

Troubleshooting

Error or symptom	What to check
`build_failed`	A Dockerfile step failed. Read the build log — the CLI streams it, and `GET /v1/template-builds/{id}/logs` keeps it readable afterward; the failing step is at the end.
`build_conflict`	One build runs at a time per workspace. Wait for the running build to finish, then start again.
`build_timeout`	The build ran past the 45-minute limit. Trim the Dockerfile’s slowest steps and retry.
`image_too_large`	The built or imported image is over 8 GB decimal. Remove build caches and unnecessary layers, or contact support.
`invalid_request` for `image_ref`	Use a fully qualified tag and confirm the registry allows anonymous pulls. For an image that isn’t public, run a cloud build from its Dockerfile instead.
`image_ingest_failed`	The private copy failed on Agent37’s side. Retry once — re-run the build or the registration — then contact `support@agent37.com`.
Instance status is `failed`	Read instance logs; confirm the main process stays alive and `default_port` listens when set.

Get started

Build with Agent37

Hosting API

Agent API

Reference

Build a custom image

1. Choose a starting image

2. Verify it locally (optional)

3. Register the image

Build it in the cloud

Import a public registry image

4. Create an instance

5. Bring your own model

Keep it current

Troubleshooting

​1. Choose a starting image

​2. Verify it locally (optional)

​3. Register the image

​Build it in the cloud

​Import a public registry image

​4. Create an instance

​5. Bring your own model

​Keep it current

​Troubleshooting

1. Choose a starting image

2. Verify it locally (optional)

3. Register the image

Build it in the cloud

Import a public registry image

4. Create an instance

5. Bring your own model

Keep it current

Troubleshooting