Authoring Templates

This document explains how to create custom Agent Sandbox templates, including the directory structure, adapting an existing project, and publishing with the CLI.

Three ways to start, all of them local files only (publish later with abx deploy):

Template Directory Structure

A complete template directory structure is as follows:

my-template/
├── template.yaml      # Required — template definition
├── Dockerfile         # Optional — custom Docker build (takes priority over build steps in template.yaml)
├── commands.py        # Optional — register custom commands via @sandbox.register
└── README.md          # Optional — template description

template.yaml is the only required file.

template.yaml Basic Example

name: my-python-template
version: "1.0.0"
description: "Python data analysis environment with pre-installed pandas and matplotlib"
author: "Your Name"
tags:
  - python
  - data-analysis

env:
  PYTHONUNBUFFERED: "1"
  APP_DIR: "/app"

capabilities:
  - shell
  - files
  - code
  - terminal

ports:
  - 8080

Field Reference, Capabilities and Named Commands

The template.yaml fields and the capabilities vocabulary (shell, files, code, terminal, ports) are part of the shared template contract. Named commands are not declared in template.yaml: register them on the in-sandbox server (@registry.command) and call them with abx run <id> <name> --arg k=v (list them with abx sandbox command list <id>). The fields and capabilities are specified in the SDK documentation listed in Related SDK documentation.

Dockerfile Customization

The actual build process uses Dockerfile directly along with language-native dependency files (requirements.txt / package.json):

FROM python:3.11-slim

RUN apt-get update && apt-get install -y \
    curl git \
    && rm -rf /var/lib/apt/lists/*

RUN pip install --no-cache-dir \
    pandas matplotlib numpy

WORKDIR /app

ENV PYTHONUNBUFFERED=1

The Dockerfile in the template directory is the sole source for building images. template.yaml only defines runtime configuration (capabilities, commands, environment variables, resources) and does not contain build instructions.

Provider template profile

The HTTP server inside the image does not depend on a sandbox provider. commands.py imports only agent_sandbox.server and calls serve(port=9000) under if __name__ == "__main__". Port 9000 is the server default.

Which FROM, whether ENTRYPOINT may be replaced, CMD versus a platform start_cmd / ready_cmd, architecture, workdir, reserved ports, and registry notes come from the selected provider's template profile. abx resolves that provider the same way as every other command: --provider, then ABX_PROVIDER, then the configured default (alicloud-express). The template guide, the codegen prompt, and abx template init describe that one profile.

• alicloud-express uses FROM fc-e2b-registry.<region>.cr.aliyuncs.com/runtime/base:<tag>, does not set CMD or ENTRYPOINT, and starts the server with the platform start_cmd / ready_cmd. Workdir is /home/user/app. Ports 49983, 5000, and 49999 are reserved by that profile.
• Any other provider uses the generic profile (FROM python:3.12-slim, CMD ["python3", "commands.py"], WORKDIR /app) unless its abx-provider.toml declares a [template] table. A missing profile is not the FC image; the generator names the provider id that had none.
• The image installs agent-sandbox-server, not the client package.

Adapt an existing project

abx template init --adopt is for a directory that already has application code and is missing the sandbox template files. Qwen Code reads a copy of that project and abx writes the template files back into the same directory. Nothing is built, pushed, or launched; publish with abx deploy afterwards.

abx template init --adopt . --hint "the API listens on 8080"
abx template init --adopt ./app --dry-run          # list the files; send nothing
abx template init --adopt ./app --name my-api -y   # non-interactive
abx deploy ./app --acr-namespace my-ns

--hint is free text for facts the code does not show (the listen port, a sidecar, a private constraint). --name sets the template name: it must match ^[a-z0-9][a-z0-9-]*$. When --name is omitted, abx slugs the directory name. A name that cannot be slugged (a Chinese-only directory, for example) needs --name.

Files written back

Only these files are written, and only after you confirm the preview (or pass -y):

Application source stays as it is. A file the agent creates or edits outside that list is reported and discarded. A replaced file is kept as *.abx-bak; an existing backup is never overwritten (the next one is .abx-bak.1).

What is sent to the model

abx copies candidate files into a temporary directory (abx-adopt-… under the system temp dir, never ~/.abx) and asks before sending them. The agent runs only in that copy.

Left out of the copy: .git, node_modules, virtualenvs, and similar heavy directories; .env and other secret-named files (keys, credentials*, kubeconfig, …); files whose contents look like a secret; symlinks; binaries; files larger than 1 MiB. The copy stops above 2 000 files or 20 MiB and tells you to point --adopt at a subdirectory.

--dry-run prints that file list and deletes the copy. It does not call the model and does not write the project. A non-interactive shell (CI, piped input, --json) must pass -y; otherwise the command stops before any copy is made.

The agent process does not inherit cloud or registry credentials (ALICLOUD_*, E2B_*, ACR_*, AWS_*, GITHUB_TOKEN). It does receive the Qwen Code key from abx config.

This sends your project source to the model. abx template init "DESCRIPTION" sends only the sentence you typed.

Checks before anything is written

abx rejects the result, leaves the project unchanged, and prints the staging path when:

• the Dockerfile has no FROM, or commands.py does not start agent_sandbox.server
• port 9000 is missing from template.yaml ports or from EXPOSE
• a COPY / ADD names a file that is missing or ignored (COPY *.whl is the wheel abx deploy injects at build time, so it is allowed)
• a secret-named file would still be in the Docker build context after .dockerignore and Dockerfile.dockerignore
• an ignore file excludes *.whl, which would block the SDK wheel

An existing .dockerignore that does not exclude .env (including one re-included with !) fails before the model is called, with the lines to add. An existing .dockerignore is never rewritten.

Replacing files that are already there

abx template init --from <local directory> requires a template.yaml in that directory. A source tree without one is refused and the message points at --adopt, so .env and .git are not copied as template source.

If generation fails, the project is unchanged and the error includes the staging directory. Delete that abx-adopt-… directory after you have inspected it.

--adopt cannot be combined with -t, --from, or --list. --hint and --dry-run require --adopt.

Publishing Templates

Publish to GitHub

Push the template directory to a GitHub repository, and other users can install it with:

abx template install your-org/your-template

Local Installation

abx template install ./my-template --registry-type local

Installed templates are saved in the ~/.abx/templates/ directory.

Building and Registering Templates Locally (template deploy)

When you need to register a custom Docker image as a sandbox template, use the template deploy subcommand. It automatically performs: local Docker build → ACR push → CreateTemplate API call.

Prerequisites: - Docker daemon is running - Alibaba Cloud AK/SK credentials (configured in .env or environment variables) - The official Alibaba Cloud template API client (@alicloud/fcsandbox20260509) is bundled with @agent-sandbox/cli — no extra install is needed

# Default: official CreateTemplate API
abx template deploy ./my-template \
  --acr-namespace my-ns --acr-repo my-template

# Specify resource parameters
abx template deploy ./my-template \
  --acr-namespace my-ns --cpu 4 --memory 4096 --disk-size 10240 --internet-access

# Use legacy v3/v2 API (old script compatibility)
abx template deploy ./my-template \
  --acr-namespace my-ns --legacy-api

Two paths explained:

Region note: The official API uses the region configured via abx config set region (else cn-hangzhou). A single deployment can override it with the command-level --region/-r option on template deploy/build/create/push/list/info/install/delete. Cross-region ACR access may require VPC-related parameters.

Creating Templates from Existing Images

If the image is already pushed to ACR, you can create a template directly without local building:

abx template create registry.cn-hangzhou.aliyuncs.com/ns/repo:tag --name my-template

Next Steps

• Using Templates — Install and use templates

Related SDK documentation

The template.yaml contract and the Python-side authoring guides live in the python-sdk repository:

• Template YAML Spec — precise definitions for all fields
• Authoring Templates (SDK) — field reference, capability declarations, custom commands, @sandbox.register
• Template System — tiers, name resolution, versioning
• Declarative Usage — the @sandbox decorator