For AI agents: The documentation index is at https://docs.digitalocean.com/llms.txt. Markdown versions of pages use the same URL with index.html.md in place of the HTML page (for example, append index.html.md to the directory path instead of opening the HTML document).

Harness Runtime sandboxes start from a template that defines what is preinstalled in the microVM. Stock templates cover adapters such as Codex, Claude Code, and OpenCode. Bring-Your-Own-Template (BYOT) lets you register a team-owned OCI image so sessions start from your dependencies, CLIs, and configuration instead of only the catalog image.

DigitalOcean builds your image on top of a required base template (for example coding-codex) when you register it. Sessions that set template to your custom template name use that environment.

Prerequisites

You need:

• A DigitalOcean account with a payment method on file and funds in at least one balance.
• A DigitalOcean personal access token with write access.
• doctl authenticated for your account, with Harness Runtime commands available (doctl harness-runtime --help).
• A Container Registry in your team, and Docker (or another OCI client) that can push to it.
• A working environment spec for the adapter you want to run. See Create an Environment Using a Coding Adapter.

Push an Image to Container Registry

Build an image that installs the packages, CLIs, and any background services your agent needs. Push it to Container Registry. Harness Runtime pulls images from your team’s registry without extra registry credentials in the environment spec.

docker build -t registry.digitalocean.com/<your-registry>/custom-agent:v1 .
docker push registry.digitalocean.com/<your-registry>/custom-agent:v1

Replace <your-registry> with your registry name.

Register the Template

Create a template that points at your registry image and a base template. The base template supplies runtime wiring (entrypoints and control-plane event handling) that your image alone does not provide.

doctl harness-runtime template create \
  --name custom-finops-agent \
  --base-template coding-codex \
  --source-oci-ref registry.digitalocean.com/<your-registry>/custom-agent:v1

Harness Runtime supports the following BYOT base templates:

Choose the base template that matches the adapter you plan to run.

List templates and wait until the new one shows as ready:

doctl harness-runtime template list

Related commands include get, update, delete, and list-builds.

Custom template storage is billed per GB. See Harness Runtime Pricing.

Start a Session From the Template

Write an environment spec that sets template to your registered template name. Keep agent aligned with the base template you chose (for example codex with coding-codex):

name: finops-session-01
agent: codex
template: custom-finops-agent
secrets:
  OPENAI_API_KEY: ${OPENAI_API_KEY}

Export the key so doctl can expand ${OPENAI_API_KEY}, then create the session:

export OPENAI_API_KEY=<your-openai-key>
doctl harness-runtime create --spec <your-environment-spec>.yaml

To confirm custom binaries are on the path before you attach interactively:

doctl harness-runtime exec finops-session-01 -- sh -c "which <your-custom-cli> && <your-custom-cli> --version"

Attach to the session:

doctl harness-runtime launch finops-session-01

For the full template field and other agent fields, see Environment Spec Reference.

Reach Services Running in the Sandbox

If your image starts a long-lived service on a sandbox port, open a local tunnel with doctl harness-runtime port-forward. See Forward Sandbox Ports.

Troubleshooting

Template Creation Fails When --base-template Is Omitted

--base-template is required when you register a template. Harness Runtime uses the base template (for example coding-codex) for runtime dependencies, entrypoint definitions, and event handling between the sandbox and the control plane. Omitting it prevents the Firecracker snapshot from linking correctly, so registration fails.

Claude Code Skills or Plugins Are Missing

To add custom skills or plugins for Claude Code, put the skill definitions under /workspace in your container image during the Docker build. After DigitalOcean builds the template snapshot, /workspace content from that snapshot is fixed for that template version. You cannot add skills dynamically after the template is registered.