Sandboxes

A sandbox is an isolated environment on this computer that runs a CoDev Code server of its own. The agent inside it reaches your machine only through the folders you mount, and reaches the network only through the model gateway — so it can run commands, install packages and rewrite files without touching anything you did not hand it.

That is what makes Work different from Code: because there is nothing to protect you from, permission prompts are skipped by default and you can hand it a task and walk away.

Under the hood a sandbox is a lightweight virtual machine or container — Virtualization.framework on macOS, a managed WSL 2 distribution on Windows, bubblewrap on Linux.

Getting one

Click Work. If you have no sandbox yet, the app explains what a sandbox buys you and offers to set one up: an isolated environment on this computer that the agent can only reach through the folders you mount into it.

It asks for nothing. It creates a sandbox called default-sandbox with the standard image and the standard limits, and once it is ready it asks you to mount a project — the folder on this computer you want to work on. That folder is the only part of your machine it can reach. (The sandbox's own scratch folder is the app's business and is not offered to you anywhere, including in the Mount project dialog.)

Cancelling leaves you on Code. Reaching the same dialog deliberately from Settings is unchanged.

If you have turned Show Work off there is no Work to click — create the sandbox from Settings → Servers → + → Add sandbox instead, and Work comes back on its own once you have one.

The sandbox image is downloaded on first use. It is well over a gigabyte, so the first sandbox on a machine takes a while; every sandbox after that reuses it.

Creating one yourself

Settings → Servers → + → Add sandbox keeps the full form, for a second sandbox or one pointed at a particular folder from the start.

Name — checked as you type. Duplicates, names too long for the environments they name, and characters that are unsafe in a Windows distribution or a folder name are all caught in the dialog, with a message saying what to change, rather than after a large download has already happened.

Project folder — the only part of your computer the sandbox can reach. It cannot be changed after the sandbox is created, and the agent edits files in it without asking for permission. The dialog says so above the field.

CPUs and Memory — macOS only, where each sandbox is its own virtual machine and the limits actually apply. They sit side by side, show their defaults (4 CPUs and 4 GB) and say how high you can go. Windows sandboxes follow the VM-global limits in your .wslconfig; the Linux backend has no per-sandbox limits.

Sandbox image — dev builds only. Release and beta builds can only use the published image, so the field would be a question with one answer. Where it is offered, the file is checked as soon as you choose it and the dialog says plainly what is wrong — not a sandbox image, an image for a different operating system, or one built for a different kind of processor. The file is read where it sits rather than copied, and it is remembered, so resetting rebuilds from the same file.

While the image downloads the dialog shows a progress bar with the downloaded and total size, and Cancel stays available: cancelling aborts the download without registering the sandbox, and the bytes already fetched are kept so the next attempt resumes. A connection that drops resumes from where it stopped rather than failing the whole create.

What it costs

Creating a sandbox is near-instant, and a sandbox costs roughly nothing on disk until the guest writes something: a new sandbox is a copy-on-write clone of the shared disk image.

The shared image itself is the big download, once per machine.

Running, stopping, resetting

Every sandbox's menu in Settings → Servers carries its lifecycle:

Stop shuts the environment down. Files on its disk are kept; running terminals and in-flight work stop. A stopped sandbox stays stopped across relaunches, so a machine only runs the sandboxes you actually want running — three sandboxes no longer mean three virtual machines holding memory whether or not anything is happening in them.

Start brings it back. A stopped sandbox's tabs wait for it and return on their own.

Reset re-clones the disk from the image, discarding everything inside — including every session in it. Each sandbox records which image it was provisioned from, so when a new image is published, Reset re-provisions from that one; when the image has not changed, Reset is as fast as it ever was. Resetting a stopped sandbox rebuilds it without starting it.

Delete erases the sandbox's disk, taking every session, terminal and file created inside it permanently. It asks first and spells that out — and clarifies that folders mounted from this computer are not deleted, the sandbox just loses access to them. It also clears the sandbox's remembered projects, last-selected project and recently closed folders, so a new sandbox with the same name starts clean instead of inheriting its predecessor's list.

These operations queue. Creating, resetting or deleting one sandbox no longer cancels another one's work, and a sandbox waiting its turn says so. Cancelling one that is waiting takes effect immediately without disturbing whatever is running.

Windows: WSL 2

A sandbox on Windows runs inside WSL 2. If the machine does not have it, both create-sandbox dialogs offer Install WSL and do it for you: CoDev downloads the installer for your processor, asks Windows for permission once, and enables the Virtual Machine Platform feature in the same step. You see the download's progress, then the install, and the dialog carries straight on to setting up the sandbox.

• The installer comes from the CoDev storage host, so it works on networks that cannot reach Microsoft's servers, and falls back to Microsoft's own installer when that host is unreachable.
• A download that is cut off resumes where it stopped, and an installer that arrives damaged is rejected rather than run.
• ARM64 machines are covered, not only Intel ones.
• A Windows too old for the installer is told so — naming its build and the one it needs — before anything is downloaded.

If Windows must restart. On a machine that never had WSL 2, the install enables a Windows feature that only starts working after a restart. The dialog says so, and offers a Restart Windows button there and then rather than sending you to the Start menu: it confirms first, since restarting closes CoDev and everything else, and an application holding unsaved work can still hold the restart — Windows is asked to restart, not forced to.

Windows 10 additionally needs the Windows Subsystem for Linux component itself, which the installer enables. Windows 10 22H2 is supported and warns about nothing; builds older than 22H2 still warn, because those versions are out of support and may not run WSL 2 at all.

When something goes wrong

"Your sandbox is not running yet." The sidebar says this while a sandbox is being created or started. Pinned and Recents stay empty next to it rather than filling with the local machine's sessions, and the main pane shows a spinner and Loading sandbox... with the search box hidden, because there is nothing to search yet.

A sandbox that failed to boot says so in the same place, shows the failure message, and offers a retry in place — you do not have to go looking in Settings → Servers to find out.

"nft is missing from the guest image" means the sandbox is on an image older than the one the current app requires. Use Reset to pick the new image up.

A sandbox that will not start after a force quit clears itself: the leftover file that used to cause address already in use from then on is removed on the next start.

More in Troubleshooting.

What is inside

The sandbox image ships a working toolchain, and the Office skills — Word, Excel, PowerPoint and PDF — with everything they depend on: LibreOffice 26.2.5, pandoc 3.10.1, .NET 8.0.423, a browser for rendering PDF covers, and a fixed set of Python packages.