Devboxes from your agent
Ask an agent to deploy a branch and hand you a link. What it can do, what it will ask you first, and how to correct a wrong guess.
Your agent can run the whole devbox loop by itself: create the box, deploy a branch, watch it come up, and give you a URL to click. You never have to open the dashboard for it.
Works with OpenClaw, Hermes and Paperclip. Cursor cannot drive devboxes today.
What to say
Plain English is enough. These all work:
- "Deploy this branch to a devbox and send me the link."
- "Spin up a preview of the
checkout-redesignbranch." - "The preview is showing the old build — redeploy it."
- "Keep that preview alive until tomorrow."
- "Show me the logs from the last deploy."
- "Tear the devbox down."
Your agent needs the repo to be covered by your organization's GitHub App installation. If it is not, connect it under Settings → GitHub and ask again. See Integrations.
The one question it must ask you
Which network. Your agent is required to ask and is not allowed to choose for you, because the three answers have very different consequences:
| Answer | Who can open the preview |
|---|---|
| Sokko network | Anyone with the link who signs in to Sokko and is a member of your organization. Sokko checks every visit. |
| Private | Only devices on your Tailscale tailnet. Your tailnet's rules are the lock — Sokko does not check visitors. |
| Public | Anyone at all. No sign-in. Ask for this only when you truly want an open link. |
The choice is permanent for that devbox. To change it, create a sibling devbox for the same repo — it shares the repo's secrets, so nothing is set up twice.
Cloudflare Tunnel devboxes are not available yet; private devboxes are Tailscale only.
What it can do
| Ask for | Your agent does |
|---|---|
| A new devbox | Creates it, bound to one repo forever |
| A deploy | Deploys a branch, replacing what was running |
| Status | Reports the state, the services, and any error with a fix |
| A dry run | Reports what Sokko would run, without deploying |
| Logs | Pulls the build and app output |
| A link | Gives you the preview URL, or a share link for tools outside Sokko |
| More time | Extends the lifetime, up to the plan cap |
| Cleanup | Destroys the devbox — permanent, and it will confirm first |
Share links
If you want to test a preview with something that cannot sign in to Sokko — curl, Playwright, a CI job — ask your agent for a share link and how long you want it to live (5 minutes to 24 hours).
A share link is a password in URL form. Anyone who has it can open the preview until it expires, and it cannot be revoked early — destroying the devbox is the only way to kill it. Keep the lifetime short.
When the guess is wrong
Sokko works out how to run most repos on its own. When it cannot, or when it picks the wrong command, every deploy tells you what it ran and where that came from — so the fix is one message:
"That's wrong, it needs
npm ci && npm run build && npm starton port 8080."
Your agent passes that with the next deploy. From then on:
- This devbox stops guessing. The command is stored and reused on every later deploy.
- Once it comes up healthy, your whole organization benefits. Sokko saves the working setup for that repository, so the next devbox anyone creates for it starts from what worked. A setup that crash-looped is never saved.
No repo change, no commit, no push. If you would rather have it written down and
reviewable, put the same values in
sokko.devbox.yml — the keys are identical.
Things worth knowing
- "Empty" means ready, not stuck. A fresh devbox sits at
emptyuntil something is deployed. That is a resting state. - One deploy at a time per devbox. A second one while the first is running is refused; the agent waits instead of retrying.
- Never dictate secrets to an agent. Anything you type into a chat goes through a model. Put credentials in the Repo secrets tab instead, and tell your agent to redeploy.
- Destroying is permanent. The machine, the disk and the URL all go. Repo secrets survive.