Templates

A template is a reusable filesystem image used to boot runtimes (sandboxes). Gravix Layer ships three system base templates, and you can build your own from a public Docker image or a Dockerfile. POST /v1/agents/runtime

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
print(sandbox.template)
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
console.log(sandbox.template);
await sandbox.kill();

gravixlayer runtime create --wait

# Requires: GRAVIXLAYER_API_KEY
curl -sS -X POST "https://api.gravixlayer.ai/v1/agents/runtime" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template":"base-small","cloud":"aws","region":"us-east-1"}'

Base templates

These are the foundational images for coding agents, code execution, and shell work. All three share the same toolchain; they differ only in CPU, memory, and disk.

Template	vCPU	Memory	Disk	Cloud / Region
`base-small`	1	1 GB	4 GB	aws / us-east-1
`base-medium`	2	2 GB	6 GB	aws / us-east-1
`base-large`	4	4 GB	8 GB	aws / us-east-1

What’s included

Category	Contents
OS	Ubuntu 24.04
Languages	Python 3.14.6 (uv-managed), Node.js 24.18.0
Package managers	uv 0.11.29, npm 12.0.1, pip (via venv)
Developer	git, vim, nano, build-essential
Networking	curl, dig, nslookup, ping, traceroute, nc, netstat, iproute2

Full definition: base.Dockerfile in the Python SDK examples.

Users and layout

User	Purpose
`agent`	Login identity for SSH and the web terminal (home: `/workspace`)

/workspace/                 # Home directory (agent user)
  .bashrc, .profile         # Shell init (PATH, VIRTUAL_ENV, UV_PYTHON_INSTALL_DIR)
  .venv/                    # Writable Python venv (pip / uv pip install)
  .uv/python/               # uv-managed Python installs
  .ssh/                     # SSH keys for the agent user

Python is managed by uv, not apt python3. The seeded workspace venv is on PATH (python / pip resolve there). Prefer pip install or uv pip install into /workspace/.venv.

Which size to pick

Template	Good for
`base-small`	Quick scripts, light agent tools, short evals
`base-medium`	Typical coding-agent sessions and package installs
`base-large`	Heavier deps, longer sessions, more concurrent work

Agent templates (Claude Code / Codex)

Gravix Layer provides platform agent templates with the coding CLI already installed. Use them by name when creating a runtime — for example --template claude / template="claude".

Platform template	CLI	Reference Dockerfile (what’s included)	Official install
`claude`	`claude`	`agent-claude.Dockerfile`	Claude Code setup — `https://claude.ai/install.sh`
`codex`	`codex`	`agent-codex.Dockerfile`	Codex CLI — `https://chatgpt.com/codex/install.sh`

Building from the Dockerfile yourself is optional (custom packages, baked CLAUDE.md, private variants). Prefer 8 GB+ disk if you do build a custom image. Sandboxes deny egress by default. For the agent to call the model API:

Create an Identity provider secret — ANTHROPIC_API_KEY for Claude, OPENAI_API_KEY for Codex — and attach it when creating the runtime.
Create a network policy allowlist that includes the vendor API hosts (at minimum api.anthropic.com / api.openai.com on TCP 443; add auth and package-registry hosts as needed) and attach it to the runtime.

Step-by-step Claude Code usage: Claude Code on Gravix Layer.

Build a custom template

Build a template when you need packages, files, or a different base image baked in before the runtime boots. To save the state of a runtime that is already running, use a snapshot instead. You can build from:

A public Docker image (from_image) plus SDK build steps, or
A Dockerfile string (dockerfile) for full control of the image layers

The call blocks until the template is ready when you use build_and_wait (raise timeout_secs for large images). POST /v1/agents/template/build

From a Docker image

from gravixlayer import GravixLayer, TemplateBuilder

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

builder = (
    TemplateBuilder("my-python-app", "FastAPI with curl")
    .from_image("ghcr.io/astral-sh/uv:python3.14-bookworm-slim")
    .vcpu(2)
    .memory(1024)
    .disk(4096)
    .apt_install("curl")
    .pip_install("fastapi", "uvicorn")
    .mkdir("/app")
    .copy_file(
        """
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def health():
    return {"status": "ok"}
""".strip()
        + "\n",
        "/app/main.py",
    )
    .start_cmd("uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app")
    .ready_cmd(TemplateBuilder.wait_for_port(8080), timeout_secs=120)
)

status = client.templates.build_and_wait(
    builder,
    timeout_secs=600,
)

print(status.template_id, status.status)

# Use when ready:
# sandbox = client.runtime.create(template=status.template_id)

import { GravixLayer, TemplateBuilder } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

const app = `
from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def health():
    return {"status": "ok"}
`.trim();

const builder = new TemplateBuilder('my-python-app', 'FastAPI with curl')
  .fromImage('ghcr.io/astral-sh/uv:python3.14-bookworm-slim')
  .vcpu(2)
  .memory(1024)
  .disk(4096)
  .aptInstall('curl')
  .pipInstall('fastapi', 'uvicorn')
  .mkdir('/app')
  .addFile('/app/main.py', `${app}\n`)
  .startCmd('uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app')
  .readyCmd(TemplateBuilder.waitForPort(8080), 120);

const status = await client.templates.buildAndWait(builder, { timeoutMs: 600_000 });
console.log(status.templateId, status.status);

// Use when ready:
// const sandbox = await client.runtime.create({ template: status.templateId });

CONTENT_B64=$(printf '%s' 'from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def health():
    return {"status": "ok"}
' | base64)

gravixlayer template build \
  --name my-python-app \
  --description "FastAPI with curl" \
  --docker-image ghcr.io/astral-sh/uv:python3.14-bookworm-slim \
  --vcpu-count 2 \
  --memory-mb 1024 \
  --disk-mb 4096 \
  --build-step '{"type":"apt_install","args":["curl"]}' \
  --build-step '{"type":"pip_install","args":["fastapi","uvicorn"]}' \
  --build-step '{"type":"mkdir","args":["/app"]}' \
  --build-step "{\"type\":\"copy_file\",\"args\":[\"/app/main.py\"],\"content\":\"$CONTENT_B64\"}" \
  --start-cmd 'uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app' \
  --ready-cmd 'python -c "import socket; s=socket.create_connection((\"127.0.0.1\",8080),2)"' \
  --ready-timeout-secs 120 \
  --wait \
  --build-timeout 600 \
  --output json | jq .

# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")
CONTENT_B64=$(printf '%s' 'from fastapi import FastAPI
app = FastAPI()

@app.get("/")
def health():
    return {"status": "ok"}
' | base64)

curl -sS -X POST "$API/agents/template/build" "${AUTH[@]}" \
  -d "{
    \"name\": \"my-python-app\",
    \"description\": \"FastAPI with curl\",
    \"docker_image\": \"ghcr.io/astral-sh/uv:python3.14-bookworm-slim\",
    \"vcpu_count\": 2,
    \"memory_mb\": 1024,
    \"disk_mb\": 4096,
    \"start_cmd\": \"uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app\",
    \"ready_cmd\": \"python -c \\\"import socket; s=socket.create_connection(('127.0.0.1',8080),2)\\\"\",
    \"ready_timeout_secs\": 120,
    \"build_steps\": [
      {\"type\": \"apt_install\", \"args\": [\"curl\"]},
      {\"type\": \"pip_install\", \"args\": [\"fastapi\", \"uvicorn\"]},
      {\"type\": \"mkdir\", \"args\": [\"/app\"]},
      {\"type\": \"copy_file\", \"args\": [\"/app/main.py\"], \"content\": \"$CONTENT_B64\"}
    ]
  }" | jq .

From a Dockerfile

Pass the Dockerfile contents directly. Put system packages and language installs in the Dockerfile; you still set start_cmd / ready_cmd on the builder so Gravix can launch and verify the app during the snapshot phase.

from gravixlayer import GravixLayer, TemplateBuilder

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

dockerfile = """\
FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
ENV UV_SYSTEM_PYTHON=1
RUN uv pip install --system --no-cache fastapi "uvicorn[standard]"
WORKDIR /app
COPY main.py /app/main.py
EXPOSE 8080
"""

builder = (
    TemplateBuilder("my-dockerfile-app")
    .dockerfile(dockerfile)
    .vcpu(2)
    .memory(1024)
    .disk(4096)
    .start_cmd("uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app")
    .ready_cmd(TemplateBuilder.wait_for_port(8080), timeout_secs=60)
)

status = client.templates.build_and_wait(
    builder,
    timeout_secs=600,
)

print(status.template_id)

import { GravixLayer, TemplateBuilder } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

const dockerfile = `FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
ENV UV_SYSTEM_PYTHON=1
RUN uv pip install --system --no-cache fastapi "uvicorn[standard]"
WORKDIR /app
COPY main.py /app/main.py
EXPOSE 8080
`;

const builder = new TemplateBuilder('my-dockerfile-app')
  .dockerfile(dockerfile)
  .vcpu(2)
  .memory(1024)
  .disk(4096)
  .startCmd('uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app')
  .readyCmd(TemplateBuilder.waitForPort(8080), 60);

const status = await client.templates.buildAndWait(builder, { timeoutMs: 600_000 });
console.log(status.templateId);

# Write Dockerfile to a local file first, then:
cat > /tmp/my-dockerfile-app.Dockerfile <<'EOF'
FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
ENV UV_SYSTEM_PYTHON=1
RUN uv pip install --system --no-cache fastapi "uvicorn[standard]"
WORKDIR /app
COPY main.py /app/main.py
EXPOSE 8080
EOF

gravixlayer template build \
  --name my-dockerfile-app \
  --dockerfile /tmp/my-dockerfile-app.Dockerfile \
  --vcpu-count 2 \
  --memory-mb 1024 \
  --disk-mb 4096 \
  --start-cmd 'uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app' \
  --ready-cmd 'python -c "import socket; s=socket.create_connection((\"127.0.0.1\",8080),2)"' \
  --ready-timeout-secs 60 \
  --wait \
  --build-timeout 600 \
  --output json | jq .

# Requires: GRAVIXLAYER_API_KEY, jq
API="https://api.gravixlayer.ai/v1"
AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

DOCKERFILE=$(jq -Rs . <<'EOF'
FROM ghcr.io/astral-sh/uv:python3.14-bookworm-slim
ENV UV_SYSTEM_PYTHON=1
RUN uv pip install --system --no-cache fastapi "uvicorn[standard]"
WORKDIR /app
COPY main.py /app/main.py
EXPOSE 8080
EOF
)

curl -sS -X POST "$API/agents/template/build" "${AUTH[@]}" \
  -d "{
    \"name\": \"my-dockerfile-app\",
    \"dockerfile\": $DOCKERFILE,
    \"vcpu_count\": 2,
    \"memory_mb\": 1024,
    \"disk_mb\": 4096,
    \"start_cmd\": \"uvicorn main:app --host 0.0.0.0 --port 8080 --app-dir /app\",
    \"ready_cmd\": \"python -c \\\"import socket; s=socket.create_connection(('127.0.0.1',8080),2)\\\"\",
    \"ready_timeout_secs\": 60
  }" | jq .

Set disk large enough for the image layers plus packages you install during the build. If the build fails with a disk check error, increase .disk(...).

Supported vs not supported

Gravix exports the Docker filesystem into the runtime image. Some Dockerfile / image settings are applied; others are ignored so platform defaults stay in control.

Supported

Capability	Notes
Public Docker images	Ubuntu, Debian, and Alpine-based images
`from_image` or `dockerfile`	Exactly one base source per build
Build steps	`run`, `apt_install`, `pip_install`, `npm_install`, `bun_install`, `copy_file`, `copy_dir`, `git_clone`, `mkdir`
Resources	`vcpu`, `memory`, `disk` on the template
Environment	`env` / `envs` (persisted into the guest)
`WORKDIR`	Applied so app paths resolve correctly
Docker `ENV`	Merged into the guest (except platform-owned keys below)
`EXPOSE` / ports	Used for port discovery when present
SDK `start_cmd` / `ready_cmd`	How Gravix launches and verifies processes during build

Not supported (silently ignored)

These may appear in a Dockerfile or image config. Gravix builds anyway and uses platform defaults instead — the build does not fail because of them.

Setting	Behavior
`ENTRYPOINT`	Ignored; platform defaults are used
`CMD`	Ignored; platform defaults are used
`USER`	Ignored; platform defaults are used (`agent` / `/workspace`)

Platform-owned env keys from the image are also skipped when merging: PATH, HOME, HOSTNAME, SHELL, USER, LOGNAME.

If your Dockerfile relies on CMD or ENTRYPOINT to start a server, set .start_cmd(...) (and usually .ready_cmd(...)) on TemplateBuilder, or start processes with run_cmd after create.

Not supported (will fail or is unavailable)

Limitation	Guidance
Private registries without credentials	Use a public image, or bake layers into a Dockerfile you upload
Disk smaller than the image	Increase `.disk(...)` so layers + packages fit
Conflicting `from_image` + `dockerfile`	Choose one

TemplateBuilder reference

Area	Python	TypeScript
Base	`from_image`, `dockerfile`	`fromImage`, `dockerfile`
Build steps	`run`, `apt_install`, `pip_install`, `npm_install`, `bun_install`, `copy_file`, `copy_dir`, `git_clone`, `mkdir`	`run`, `aptInstall`, `pipInstall`, `npmInstall`, `bunInstall`, `addFile`, `addFiles`, `gitClone`, `mkdir`
Launch / ready	`start_cmd`, `ready_cmd` (`wait_for_port`, `wait_for_process`)	`startCmd`, `readyCmd` (`waitForPort`, `waitForProcess`)
Resources	`vcpu`, `memory`, `disk`	`vcpu`, `memory`, `disk`
Metadata	`env`, `envs`, `tags`	`env`, `envs`, `tags`
Build	`client.templates.build_and_wait(..., timeout_secs=...)`	`client.templates.buildAndWait(..., { timeoutMs })`

Manage templates

GET /v1/agents/template · GET /v1/agents/template/:id · DELETE /v1/agents/template/:id

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

page = client.templates.list()
for t in page.templates:
    print(f"{t.name}: {t.status}")

if page.templates:
    info = client.templates.get(page.templates[0].template_id)
    print(info.template_id, info.status)
    # client.templates.delete(info.template_id)

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

const page = await client.templates.list();
for (const t of page.templates) {
  console.log(`${t.name}: ${t.status}`);
}

if (page.templates.length > 0) {
  const info = await client.templates.get(page.templates[0].templateId);
  console.log(info.templateId, info.status);
  // await client.templates.delete(info.templateId);
}

gravixlayer template list --output json | jq .

# Get one template by ID
# gravixlayer template get "$TEMPLATE_ID" --output json | jq .

# Delete a custom template
# gravixlayer template delete "$TEMPLATE_ID" -y

# Requires: GRAVIXLAYER_API_KEY
API="https://api.gravixlayer.ai/v1"

curl -sS "$API/agents/template?limit=100" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

# curl -sS "$API/agents/template/$TEMPLATE_ID" \
#   -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

# curl -sS -X DELETE "$API/agents/template/$TEMPLATE_ID" \
#   -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Build status

Status	Meaning
`queued`	Waiting to start
`building`	In progress
`ready`	Usable with `runtime.create`
`failed`	Build failed — check `status.error`
`cancelled`	Build was cancelled

Prefer build_and_wait for a simple blocking workflow. It starts the build and polls until a terminal status.

Getting Started

Runtime

Support

Base templates

What’s included

Users and layout

Which size to pick

Agent templates (Claude Code / Codex)

Build a custom template

From a Docker image

From a Dockerfile

Supported vs not supported

Supported

Not supported (silently ignored)

Not supported (will fail or is unavailable)

TemplateBuilder reference

Manage templates

Build status

​Base templates

​What’s included

​Users and layout

​Which size to pick

​Agent templates (Claude Code / Codex)

​Build a custom template

​From a Docker image

​From a Dockerfile

​Supported vs not supported

​Supported

​Not supported (silently ignored)

​Not supported (will fail or is unavailable)

​TemplateBuilder reference

​Manage templates

​Build status

Base templates

What’s included

Users and layout

Which size to pick

Agent templates (Claude Code / Codex)

Build a custom template

From a Docker image

From a Dockerfile

Supported vs not supported

Supported

Not supported (silently ignored)

Not supported (will fail or is unavailable)

TemplateBuilder reference

Manage templates

Build status