How template builds work

A template is a saved sandbox state. It contains the filesystem, the configured user and working directory, and processes started during the build.

AgentBox builds a template in this order:

1. create an environment from a base image or another template;
2. execute each instruction in order;
3. run the start command, when configured;
4. wait until the ready command succeeds;
5. save the ready state.

When you call Sandbox.create("my-template"), the new sandbox receives that state. Installed packages and copied files are already present, and the saved process is already running.

Each instruction creates a layer. AgentBox can reuse unchanged layers from the cache, so keep stable setup near the beginning and frequently changed files near the end of the definition.

See start and readiness and your first template.