sk8 🛹

// the idea

delegate, don't context-switch

sk8 runs claude headless on a remote box and returns the final answer. It's deliberately small, but no longer just fire-and-wait: block for the result, detach long jobs and poll them, or resume a session so the agent remembers the previous exchange.

🛰️

One tool: run_task

The remote agent runs your prompt in its cwd and hands back the final text answer. Blocking by default, up to 600s.

🔀

Detach & poll

run_task(detach=true) returns TASK_STARTED: <task_id> immediately and runs in the background — poll get_task for status and the answer. Long jobs stop fighting your MCP client's timeout.

🧵

Resumable sessions

Every answer ends with a [session_id]. Pass it back to continue the same conversation in the same workspace — follow-ups can be short instead of restating the brief.

🧬

Profiles baked in

Customize each agent per profile — extra Python packages, bundled Claude Code skills, and a tool / MCP / system-prompt spec compiled into the image at build time.

⚙️

Powered by the Agent SDK

server_sdk.py drives the agent loop through the Claude Agent SDK — a typed async message stream with structured permission control.

📦

Files in & out (optional)

Send small files inline with the files param — no bucket needed — or use GCS-backed signed URLs to move big inputs and artifacts without bloating the prompt.

// 60 seconds

quickstart

Install the CLI, provision an agent on Cloud Run, and wire it into Claude Code.

install the sk8 CLI

# install the `sk8` command from this repo (uv / pipx / pip all work)
uv tool install .

# build the agent image (first time) + provision on Cloud Run
sk8 create iris --build

# custom deps / skills / tools via a profile
sk8 create iris --profile ./profiles/data-analyst --build

connect it to Claude Code & verify

# `sk8 create` prints the exact `claude mcp add ...` line — run it, then:
claude mcp list      # sk8 should show as connected

Then, in a Claude Code session on your laptop:

delegate a task

Use the sk8 run_task tool with prompt:
"list the files in the current directory and summarize them"

// new in 0.7+

detach, poll, resume

Long jobs run detached in the background, and every task hands back a session id you can use to continue the conversation — the remote agent keeps its memory and its workspace between calls.

detached tasks — fire now, poll later

# kick off a long job without blocking your session
run_task(prompt="profile the test suite and find the 5 slowest tests", detach=true)
→ TASK_STARTED: 3f2a91c0…

# poll every 30-60s until it's done (polling also keeps the instance alive)
get_task("3f2a91c0…")
→ {status: "done", result: "…", session_id: "9b1c44d2…"}

sessions — follow up instead of restating

# every answer ends with a session id line
run_task(prompt="write a fibonacci module with a CLI")
→ … final answer …  [session_id: 9b1c44d2…]

# pass it back — same conversation, same workspace, short follow-up
run_task(prompt="now also add tests", session_id="9b1c44d2…")

On GCS-backed agents, transcripts are mirrored to the bucket, so sessions survive even when the scale-to-zero instance is recycled between calls.

// the lifecycle

the sk8 CLI

Scriptable for humans and agents alike — it emits JSON so a running agent can spawn and register its own sub-agents.

sk8 <cmd>

sk8 create iris --build     # build image (first time) + provision
sk8 create iris             # subsequent agents reuse the image
sk8 create iris --json      # {url, token, mcp_add_command} for agents
sk8 create iris --dry-run   # preview the gcloud commands offline
sk8 list                    # list deployed agents in the region
sk8 delete iris --yes       # tear down service + token secret
sk8 suggest 5              # propose adjective-noun names

// fine print

limitations

⏳ 600s per task

Every run — blocking or detached — is capped at a 600s timeout. No streaming; detached tasks report progress only as coarse get_task status.

🚦 Scale-to-zero amnesia

Task records and sessions live on the instance. Without a GCS bucket they vanish when Cloud Run recycles it — poll regularly to keep it warm, or configure a bucket.

🧠 Context is the prompt

Sessions remember prior exchanges, but a fresh task still starts from nothing — write the first prompt as a standalone brief.

⚠ Arbitrary code execution. claude can do anything the host user can. Treat reaching this endpoint as equivalent to a shell on the box — secure it accordingly.

🛹 sk8