# Recipes (https://tenki.cloud/docs/sandbox/recipes)

> For the complete documentation index, see [llms.txt](https://tenki.cloud/llms.txt)

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](/docs/sandbox/quick-start-sandbox)) and links to the reference for the APIs it uses.

Run an AI agent against a repository [#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.

```python
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](https://opencode.ai) in the session, pass `enable_opencode=True` at create time. See the [SDK Reference](/docs/sandbox/sdk) for Git helpers.

Checkpoint a prepared environment [#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.

```bash
# 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](/docs/sandbox/snapshots).

Cache dependencies across sessions [#cache-dependencies-across-sessions]

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

```bash
# 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](/docs/sandbox/volumes).

Share a read-only dataset [#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.

```bash
# 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](/docs/sandbox/volumes).

Run untrusted code and collect output [#run-untrusted-code-and-collect-output]

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

```bash
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](/docs/sandbox/sessions).