Coding

Guide

Run coding sessions on your own machine

Add a computer you own so your coding sessions run there, use your Claude subscription with Claude Code, and keep the runner up to date.

At the end of this guide, a computer you own (a work laptop or a desktop) is connected to Volobox and runs your coding sessions in place of a cloud sandbox. You install a small runner with one command; the machine then connects to Volobox by itself and opens no port. Any person can add their own machine once an administrator has set this up for the deployment.

Before you begin

  • Docker, or another container engine that offers the Docker API (Docker Desktop, OrbStack, Colima, Rancher Desktop, Podman), running for your user account.
  • macOS, Linux, or Windows x64. No administrator rights are needed: the runner installs for your user only.
  • The machine can reach your Volobox workspace over HTTPS. Nothing needs to reach the machine.
  • Own machines set up for your deployment. Until an administrator does that, Your machines says Your own machines cannot be added on this deployment yet.
  • To use Claude Code: Claude Code installed on this or another computer, to create the sign-in token with claude setup-token.

Add the machine

  1. In Volobox, open your avatar menu, choose Settings to open Personal Settings, then AI → Your machines, and click Add machine.
  2. Enter a Name (only you see it) and click Continue.
  3. Choose macOS and Linux or Windows (PowerShell) and click Copy command.
  4. Open a terminal on that machine and paste the command. Run it as your own user, not as root or with sudo: the install refuses root. The command carries a one-time code and works for a limited time, shown under it.
  5. Keep the dialog open. It shows Waiting for the machine to run the command…, then that the machine is enrolled, then {name} is connected. Click Done.
  6. The machine's card shows Online.

If you close the dialog early, click Finish later. The card shows Not installed and Get install command until the machine connects.

Tip

The first coding session on a machine downloads the sandbox image and installs the coding agents, once. To get that out of the way, click Prepare now under Coding sandbox image on the machine's card, and wait until it reads Downloaded.

Choose what the machine runs

Under What this machine runs on the machine's card, keep Coding sessions on. The other switches let the machine also run agent tools in your own unshared chats, the read-only checkout for repository questions, your personal workflows, and custom app page builds. Turn any of them off to keep that work in the cloud.

A machine runs only work that is yours alone. Team chats, shared chats and sessions, work items and shared workflows never run on it.

Start a coding session on the machine

  1. Create a coding session as usual. In the new-session dialog, or in Start coding work on a task, click the place chip.
  2. Under Where it runs, choose My machine.
  3. Start the session.

To make the machine your usual place, open Personal Settings → AI → Coding agents and set New coding sessions run on to My machine, when it is online. Repository sessions you start without choosing a place then run there, and fall back to the cloud sandbox while the machine is offline. The setting does not apply to sessions linked to a task: choose My machine under Where it runs for those.

Where a session runs is chosen when it is created and does not change later. A session on your own machine cannot be shared with other people; start a new session to work on something together.

Use your Claude subscription with Claude Code

Claude Code runs only on a machine signed in to a Claude subscription, never in the cloud sandbox. Nothing about the subscription is stored in Volobox: you sign in on the machine.

  1. On the machine, in a terminal, run:

    Bash
    volobox-host agent login claude
  2. It asks for a token. In another terminal, run Claude Code's own command, approve in the browser that opens, and copy the token it prints:

    Bash
    claude setup-token
  3. Paste the whole token into the first terminal. The input is hidden, and the runner keeps the token in a file only your user can read.

  4. In Volobox, under Your machines, turn on Use my Claude subscription on the machine's card. After a short wait the card says Signed in on this machine.

  5. Start a coding session and choose Claude Code as the coding agent. Where it runs is fixed to your machine, and you pick the model in the same place.

Volobox receives one fact from the machine: whether a sign-in exists. The token is never sent to Volobox. Usage counts against your Claude plan, not the organization's AI spend. Only your own turns use it, and a session cannot switch to or from Claude Code once it exists.

Note

OpenCode runs on the organization's models; Cursor and Codex run on a person's own account; Claude Code runs only on a person's own machine signed in to their Claude subscription, never in the cloud sandbox.

Keep the runner running and up to date

The runner updates itself when a newer version is published: it downloads it, checks its signature, restarts and reconnects, and sandboxes on the machine keep running. These commands work on the machine:

CommandWhat it does
volobox-host statusShows what is and is not running, including paused sandboxes.
volobox-host logsShows the runner's log, for example why it is not connecting.
volobox-host updateInstalls the newest runner now.
volobox-host stopTakes the machine offline until you start it again, also across restarts. Its registration, settings and sign-ins stay, and sandboxes on it keep running.
volobox-host startConnects the machine again.
volobox-host runRuns the runner in the terminal in front of you, to watch it live.
volobox-host agent logout claudeRemoves the Claude sign-in from the machine.

To take the machine offline for a while, use volobox-host stop rather than Remove. Pause in the card's ⋯ menu stops it from taking new work; Capacity… sets how many sandboxes it runs at once.

Check that it works

  • The machine's card shows Online, and Coding sessions is on under What this machine runs.
  • A new coding session with Where it runs set to My machine starts, and its startup card says what the machine is doing.
  • With Claude Code set up, the coding agent picker lists Claude Code as ready on your machine.
A machine's card under Personal Settings, AI, Your machines: Online, its platform, container engine and runner version, the coding sandbox image downloaded, and the switches for the work it runs.

Troubleshooting

SymptomFix
The card stays Not installed after running the commandThe command failed or its code expired. Read the terminal output, then use Get install command for a new code.
The card shows OfflineThe computer is off or asleep, Docker is not running, or it lost its network. On the machine, run volobox-host status and volobox-host logs.
volobox-host is not recognized or command not foundThe terminal was opened before the install. Open a new terminal window.
The card shows Needs attention with cannot start its sandbox serverThe text under the message is Docker's own reason, usually Docker not running. Fix it and wait; the machine comes online by itself.
The card stays Offline after a reinstall, and the log says another run is activeThe earlier runner still holds the machine. Run the install command once more.
Claude Code is greyed out in the coding agent pickerOne part is missing: a machine of yours that runs Coding sessions, Use my Claude subscription turned on for it, and a sign-in (volobox-host agent login claude).
A turn says The coding agent rejected your credential on a Claude Code sessionThe token expired or was revoked. Run volobox-host agent login claude again with a new token from claude setup-token, then start a new session.
A coding session says You have no machine that can run thisNo machine of yours is enrolled, unpaused and set to run Coding sessions.
Work still runs in the cloud while the machine is OnlineThe work is shared, uses a sandbox template chosen explicitly, is a kind the machine does not run, or the machine is paused or at its capacity.

Next steps