Tier 2 — CLI agent

Tier 2 gives the agent a shell and a real filesystem inside a microVM. It is the tier for software work: clone, build, test, migrate, inspect.

Capability

The guest is a real Linux kernel. Inside it the agent has root. That root is confined to the guest.

Runtime: microVM

Each tier 2 session is a Firecracker-class microVM with a minimal device model: virtio-blk, virtio-net, virtio-vsock, a serial console, and nothing else. No USB, no PCI passthrough, no BIOS, no graphics.

Three properties matter:

• The VMM is itself confined. The Firecracker process runs under a jailer: unprivileged user, seccomp filter, own network namespace, own chroot, cgroup limits. A VMM escape lands somewhere with almost no privileges.
• There is no network path to the host. Guest to control-plane traffic goes over vsock to the node agent, not over TCP. Guest to internet traffic goes out through a tap device into the egress proxy's namespace.
• Starts come from snapshots, not boots. A booted microVM is a few hundred milliseconds. A restored one is tens of milliseconds, because the memory image is already correct.

The CLI allowlist

Tier 2's shell is real, but which binaries it may execute is policy. Enforcement is in the guest agent via an exec interposer, with a deny-by-default list per project.

# policy: pol_build_tools
cli_allowlist:
  mode: allowlist
  binaries:
    - git
    - node
    - pnpm
    - python3
    - pytest
    - make
    - tar
  deny_always:
    - curl         # force network through registered tools or allowlisted hosts
    - ssh
    - nc

An allowlist at tier 2 is the main tool for granting shell-shaped capability without granting everything. See policy engine.

Latency

Warm means a snapshot restore of a pre-booted microVM for that template and size class. Cold means a kernel boot plus init plus template materialisation.

Metering

Working with it

Exec, streaming

curl -N "$WB_BASE_URL/sessions/$SESSION/exec?stream=true" \
  -H "Authorization: Bearer $WB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "command": ["bash", "-lc", "pnpm install && pnpm test"], "cwd": "/workspace/app" }'

Server-sent events arrive as stdout, stderr and a terminal exit frame.

Interactive PTY

wss://connect.workspaces.build/v1/sessions/{id}/pty?token=wb_st_…

A multiplexed WebSocket carrying a real PTY, used by the dashboard terminal and by agents that need to drive an interactive program.

Expose a port

Declared once, at session creation — not a separate call, and not addable after boot. See Filesystem and ports for the full recipe, including the no-token public form.

curl -sS "$WB_BASE_URL/sessions" -H "Authorization: Bearer $WB_API_KEY" -H "Content-Type: application/json" \
  -d '{ "tier": 2, "execution_mode": "long_running", "image": "'"$IMAGE"'",
        "expose_ports": [{ "port": 5173, "protocol": "http" }] }'

Running a real browser

A headless browser is not a special mode — it's an ordinary binary, run the same way pytest or git would be, since Tier 2 is a full general-purpose microVM. Confirmed live end to end, twice: Chromium via Playwright, launched inside a real Kata microVM, navigating a real page through the mandatory egress proxy — on both the dev cluster and production.

# image: any base with Chromium + the Playwright python package baked in
# (e.g. FROM mcr.microsoft.com/playwright/python:v1.48.0-jammy, then pip install playwright)
curl -sS "$WB_BASE_URL/sessions" -H "Authorization: Bearer $WB_API_KEY" -H "Content-Type: application/json" \
  -d '{ "tier": 2, "execution_mode": "one_shot", "image": "'"$IMAGE"'",
        "resources": { "vcpu": 2, "memory_mib": 2048 },
        "egress": { "allow": ["example.com"] } }'

import os
from urllib.parse import urlparse
from playwright.sync_api import sync_playwright

# The proxy's credentials ride in https_proxy's URL (user:pass@host) -- Playwright does NOT parse
# that the way curl does; split it into separate username/password fields or the browser silently
# never connects.
u = urlparse(os.environ["https_proxy"])
proxy = {"server": f"{u.scheme}://{u.hostname}:{u.port}", "username": u.username, "password": u.password}

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True, args=["--no-sandbox", "--disable-dev-shm-usage"], proxy=proxy)
    page = browser.new_page()
    page.goto("https://example.com")
    print(page.title())

Templates

Snapshot and restore

The pattern that replaces holding a session open:

# end of an agent turn
SNAP=$(curl -sS "$WB_BASE_URL/sessions/$SESSION/snapshot" \
  -H "Authorization: Bearer $WB_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "turn-7", "include_memory": true }' | jq -r .id)

curl -sS -X DELETE "$WB_BASE_URL/sessions/$SESSION" -H "Authorization: Bearer $WB_API_KEY"

# start of the next turn, possibly hours later
curl -sS "$WB_BASE_URL/sessions" -H "Authorization: Bearer $WB_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"tier\": 2, \"restore_from\": \"$SNAP\" }"

With include_memory: true the restored session resumes with running processes intact — a dev server still listening, a REPL still holding its state.

When to move up to tier 3

The work needs a rendered DOM. A headless browser can be installed in a tier 2 template, but tier 3 exists because browsers need a different egress posture, a different resource profile and a different recording pipeline. Running Chromium at tier 2 gets you none of that and costs more than tier 3 to operate.