Sandbox

Recipes

Task-oriented recipes for common Tenki Sandbox workflows, including running AI agents, checkpointing environments, caching dependencies, and executing untrusted code.

Short, end-to-end workflows built from the sandbox primitives. Each recipe assumes you have authenticated (see the Quickstart) and links to the reference for the APIs it uses.

Run an AI agent against a repository

Give an agent a disposable, isolated place to work. Clone a repo into a fresh session and run your agent inside it, so it can run commands and edit files without touching your machine.

from tenki_sandbox import Sandbox

# The `with` block tears the session down on exit.
with Sandbox.create(name="agent-run", cpu_cores=2, memory_mb=4096) as sb:
    sb.git.clone("https://github.com/org/repo", depth=1, directory="/home/tenki/repo")

    # Run the coding agent of your choice inside the VM. Everything it does
    # stays in the sandbox.
    result = sb.exec("bash", "-lc", "cd /home/tenki/repo && my-agent run --task 'fix the failing tests'")
    print(result.stdout_text)

To act on a pull request instead of a branch, swap the clone for sb.git.fetch_pr(<number>, directory="/home/tenki/repo"). To run OpenCode in the session, pass enable_opencode=True at create time. See the SDK Reference for Git helpers.

Checkpoint a prepared environment

Set up an environment once, snapshot it, and restore that exact state whenever you need it, instead of reinstalling every time.

# Prepare a session
tenki sandbox create --name baseline-build
tenki sandbox exec -c 'apt-get update && apt-get install -y strace && npm ci'

# Capture the prepared state
tenki sandbox snapshot create --session <session-id> --name baseline

# Later, restore it as a new session (no reinstall)
tenki sandbox create --snapshot <snapshot-id>

Snapshots capture VM state, not attached volumes, so reattach any volumes explicitly on the restored session. See Snapshots.

Cache dependencies across sessions

Put a package cache on a persistent volume so dependency installs stay warm between sessions.

# Create a workspace-scoped volume once
tenki sandbox volume create --workspace <workspace-id> --name pnpm-cache --size 20GB

# Mount it into a session at create time
tenki sandbox create --name dev --volume <volume-id>:/workspace/.pnpm-store
tenki sandbox exec --session <session-id> -c 'pnpm install'

# A later session reuses the warm cache
tenki sandbox create --name dev-2 --volume <volume-id>:/workspace/.pnpm-store

The volume survives session termination, so the second pnpm install reuses what the first one downloaded. See Persistent Volumes.

Share a read-only dataset

Load a dataset onto a volume once, then mount it read-only into many sessions at the same time, with no per-session copy.

# Create a volume and load your dataset into it
tenki sandbox volume create --workspace <workspace-id> --name fixtures --size 10GB

# Mount it read-only (the :ro suffix) into any session
tenki sandbox create --volume <volume-id>:/mnt/fixtures:ro

The same volume can back many concurrent sessions read-only. See Persistent Volumes.

Run untrusted code and collect output

Execute code you don't trust in a disposable session, capture its result, and tear it down.

tenki sandbox create --name scratch --cpu 2 --memory-mb 4096
tenki sandbox exec --session <session-id> --timeout 2m -c './untrusted-script.sh'
tenki sandbox read --session <session-id> --path /home/tenki/build.log --out ./build.log
tenki sandbox terminate --session <session-id>

exec streams stdout and stderr and reports the exit code and duration, so you can gate on the result. Nothing runs on your host; the session is a fresh microVM that you throw away. See Sessions.

LinkedIn