Vercel

Run your agents in a fast Vercel cloud sandbox with public preview URLs and persistent pause/resume

Run your agents in a fast Vercel cloud sandbox with a public HTTPS preview URL and persistent pause/resume — no local Docker needed. Each box is a remote Vercel sandbox you drive with the same agentbox commands as a local box. It runs on Firecracker, so there's no Docker-in-Docker, and capturing a checkpoint stops the VM first (pause auto-snapshots on stop).

Switch per box with --provider vercel, or pin it project-wide with box.provider: vercel in agentbox.yaml. Comparing options? See local-docker, hetzner, daytona, and e2b.

Set up

The easiest path is the interactive wizard — it signs you in and bakes the base snapshot in one flow:

agentbox install        # then select vercel

Approve the browser CLI login when prompted (or paste an access-token trio / OIDC for CI — the access-token trio is best for long bakes since OIDC dev tokens expire on a ~12h cycle). Credentials persist to ~/.agentbox/secrets.env; project .env files are never harvested. install also bakes the base snapshot (a one-time agentbox prepare --provider vercel under the hood) with the AgentBox runtime — agentbox-ctl, the agents, tmux — so every new box boots ready in seconds.

For CI or scripted setup, run the explicit equivalents:

agentbox vercel login                 # credentials only
agentbox prepare --provider vercel    # bake the base snapshot

WHICH AUTH

OIDC dev tokens expire on a ~12h cycle with no headless refresh. For long-running ops — especially agentbox prepare --provider vercel, whose bake can outlive a token — use the access-token trio. CLI login self-refreshes, so it's fine for interactive use.

See environment for where the VERCEL_* vars and ~/.agentbox/secrets.env live.

Use it

agentbox vercel claude

agentbox vercel create|claude|codex|opencode is sugar for the same command with --provider vercel.

Prepare the base snapshot

Vercel can't build a Dockerfile image, so the base environment is a one-time Vercel snapshot (like Hetzner's prepare). agentbox prepare --provider vercel boots a fresh sandbox, provisions it (agents, relay shims, VNC, Chromium), then snapshots it. The snapshot id is recorded under the per-provider key box.imageVercel, and every create --provider vercel boots from it.

agentbox prepare --provider vercel

A repeat prepare reuses the existing snapshot unless you pass --force. The bake takes a few minutes; the base snapshot is around 1.3 GB. See CLI commands for all flags.

When you upgrade AgentBox, create --provider vercel notices if the new install would bake a different snapshot (the comparison is checksum-based on the baked files — CLI version strings on their own don't count) and offers to rebake inline; with -y or non-TTY it instead warns loudly and boots on the existing snapshot. agentbox vercel login also nudges you toward agentbox prepare --provider vercel on the first successful login.

TIP

Run prepare with the access-token trio in env — the bake can outlive a 12h OIDC dev token.

Create a box

Once you're logged in and prepared, the flow is standard. The workspace is seeded from a host git bundle plus your stash and untracked files (see teleport-a-project). The box runs as user vscode, and /workspace is checked out on branch agentbox/<box-name>.

agentbox create --provider vercel

# sugar: argv-prefix rewrite equivalent to --provider vercel
agentbox vercel claude

agentbox vercel create|claude|codex|opencode all map to the same provider. From there, run an agent and access your box as usual.

Limits

Limit
Region	`iad1` only
Disk	32 GB fixed
RAM	2048 MB per vCPU (coupled)
Exposed ports	≤4 (8080 / 6080 / 8788 reserved + ~1 free), fixed at create, non-privileged only
Session length	45 min (Hobby) / 5 hr (Pro+)
Nested containers	none — `docker` unavailable (no `CAP_SYS_ADMIN`)
SSH	none — attach uses the Vercel CLI PTY

NO IN-BOX DOCKER

If your agentbox.yaml needs Docker-in-Docker — say a postgres:16 service — use the docker or hetzner provider instead. DinD is impossible on Vercel. See docker-in-docker.

Sizing & network policy

Vercel-only keys tune vCPUs (box.vercelVcpus), session length (box.vercelTimeoutMs), and egress lock (box.vercelNetworkPolicy) — see configuration for the full list and precedence. Region is fixed at iad1, so --size is a no-op; use box.vercelVcpus for sizing.

agentbox config set box.vercelVcpus 4 --project
agentbox config set box.vercelNetworkPolicy "github.com,*.npmjs.org" --project

TIP

deny-all plus a tight allowlist gives you egress lockdown without any firewall setup — the box reaches only the domains you list.

Pause / resume

Vercel sandboxes are created persistent, keeping the last snapshot. pause / stop calls sb.stop() (auto-snapshot, then shut down); resume / start calls Sandbox.get({ resume: true }) and brings back the same /workspace on the same branch. So pause == stop and resume == start — free pause/resume, with no per-hour billing.

agentbox pause <box>
agentbox start <box>

The public *.vercel.run URL stays stable across a stop/start — it doesn't rotate. destroy deletes the sandbox and purges its own auto-snapshot; it never touches the shared base snapshot or a checkpoint snapshot.

NOTE

Persistence means pause is essentially free here — unlike hetzner, where a stopped VPS still bills ~€4/mo. The canonical guide is checkpoints-and-pausing.

Checkpoints

Cloud checkpoints map to Vercel snapshots. agentbox checkpoint create snapshots the box; agentbox create --checkpoint <name> boots from it with /workspace intact and skips workspace seeding. Pair checkpoint create with box.defaultCheckpointVercel so repeat creates boot from your project-ready snapshot.

agentbox checkpoint create --name setup
agentbox create --provider vercel --checkpoint setup

HEADS UP

checkpoint create stops the source box to capture the snapshot (it auto-resumes on the next call), so expect a brief pause on a running box. AgentBox self-heals a stale checkpoint: create probes liveness, prunes the dangling manifest, and falls back to the base snapshot.

Specs

Spec
Base image	Amazon Linux 2023
Build method	Baked snapshot — `provision.sh` then `sandbox.snapshot()` (`agentbox prepare --provider vercel`); no Dockerfile
Docker-in-Docker	None (Firecracker + seccomp)
SSH	None — attach uses the Vercel CLI PTY
Arch	x86_64 (amd64)
Live snapshots	Yes, but capturing one stops the VM first (persistent boxes auto-snapshot on stop, auto-resume on start)
Preview URL	Public HTTPS `sandbox.domain(port)` → `https://<box>.vercel.run` (no token); ≤4 ports

Caveats

No live stats — agentbox top / dashboard render — for cloud boxes, and list reports them optimistically as running.
Privileged ports are rejected — the WebProxy runs on 8080 (not 80); agentbox url resolves the 8080 domain.
Push through the relay — use agentbox-ctl git push from a box; the relay holds the credentials. See sync-and-git.
Vercel-only config keys are ignored by other providers — don't expect --size to change a vercel box.

core-concepts — what a box, branch, and worktree are.
teleport-a-project — how /workspace is seeded.
run-an-agent · access-your-box — work in a cloud box.
web-apps-and-tunnels — preview URLs, the 8080 WebProxy, expose: ports.
browser-and-screen — agentbox screen over noVNC on 6080.
checkpoints-and-pausing — pause/resume and checkpoints.
sync-and-git — relay-backed push/pull.
services-and-tasks — agentbox.yaml services and expose.
cli · agentbox-yaml · configuration · environment — reference.

Vercel

On this page