Devboxes

A devbox is a disposable machine that runs one GitHub repo's full stack: the app, its databases, its queues. Deploy a branch to it and you can test the running app in your browser at a real URL, before anything merges.

One devbox is bound to one repo, permanently. To test two branches side by side, create a sibling devbox for the same repo — it shares the repo's secrets.

Create a devbox

From the dashboard, open Devboxes and click New devbox. You answer three questions: which repo, which network, and how long it should live. By default it deploys the repo's default branch as soon as it is ready, so you get a running preview instead of an empty box.

Agents can do this too. OpenClaw, Hermes and Paperclip create and manage devboxes on their own — ask your agent to "deploy this branch to a devbox" and it handles the rest. Cursor does not drive devboxes today. See Devboxes from your agent.

Deploy a branch

Each devbox has a one-click Deploy button in the dashboard, and agents can deploy any branch. Push the branch first — Sokko deploys from GitHub, not from your agent's working copy.

A devbox moves through a few states: Empty once it is up with nothing deployed yet, Building while the stack comes up, Running once the preview serves, Idle-stopped when it has been quiet for a while (data kept), and Expired when its lifetime runs out. The devbox page has Overview, Logs, Deployments and Repo secrets tabs.

How Sokko runs your repo

Sokko works out how to run the repo — most repos need no config file at all. Around 16 stacks are detected automatically, including docker-compose, Next.js, Nuxt, Remix, Astro, SvelteKit, Vite, Django, FastAPI, Flask, Go, Rails, and a lone Dockerfile.

Every deploy reports the exact command it ran and where that came from. If a guess is wrong, your agent corrects it in one message and Sokko stops guessing for that devbox — and once the corrected setup comes up healthy, it is saved for your organization and reused by every later devbox of the same repo.

To write the answer down in the repo instead, commit a sokko.devbox.yml. A committed file outranks everything else.

Preview URLs and access

The network choice is made when the devbox is created, and it is permanent for that devbox:

• Sokko network — the devbox gets a public URL on sokko.run. Sokko assigns the address. Visitors have to sign in, and only members of your organization get through; Sokko checks every visit.
• Your private network — no public URL at all. The devbox is reachable only inside your own Tailscale tailnet, and your tailnet's own rules decide who gets in. This requires a connected Tailscale account (Settings → Infrastructure). Cloudflare Tunnel private devboxes are not available yet.
• Public — the same sokko.run URL with no sign-in at all: anyone who has the link can open it. Ask your agent for this explicitly when you want an open preview; it is not offered by default.

The preview URL provisions with the devbox and serves a status page until the first deploy is running.

Share links

To test a preview with a tool that cannot sign in to Sokko — curl, Playwright, a CI job — ask your agent for a share link and how long it should last (5 minutes to 24 hours).

Lifetime, idle-stop and data

A devbox lives for 24 hours by default. You or your agent can extend it, up to 72 hours at a time. Idle devboxes stop after 4 hours and keep their data; the next deploy resumes them.

When a devbox expires, its URL dies and the machine and data volume are reclaimed. Repo secrets are kept, so the next devbox for that repo picks them up.

Secrets

Repo secrets live on the Repo secrets tab of the devbox. They belong to the repo, not the machine: they carry over to sibling devboxes and survive expiry. Values are write-only — Sokko stores them and never shows them again, and your agents can see which names are set but never the values. Full details in Secrets and environment.

Plan limits

Devboxes are included in the flat plan price, with no metered billing. They run on their own resource pool, so a busy devbox never slows down your agents. See Plans and pricing for the full plan comparison.

Troubleshooting

• The app did not start. Check the devbox's Logs tab. The most common cause by far is a server bound to 127.0.0.1 instead of 0.0.0.0.
• Sokko ran the wrong command. Correct it once with your agent, or commit sokko.devbox.yml.
• A teammate cannot open the link. On the Sokko network, they must sign in and be a member of your organization. In private mode, they must be inside your tailnet and allowed by its access rules.
• The devbox disappeared. It likely expired. Create a new one for the same repo; its secrets are still there.
• Cursor cannot deploy to it. That is expected today — use OpenClaw, Hermes or Paperclip, or deploy from the dashboard.

Every error code, with its fix, is listed in Troubleshooting.