Private VM sandboxes

A Private VM is a machine you own — a laptop, a workstation under a desk, a VM you rent — connected to Retask with the CLI so it can host sessions. Everything else about it stays yours: the tools you installed, the accounts those tools are signed in to, and the networks the machine can reach.

That’s the trade against a Cloud sandbox. Retask provisions and bills a Cloud sandbox for you. You supply a Private VM, and in return every session on it starts with everything that machine already has.

Why connect one

Your AI subscriptions do the work, not API credits

This is the big one. A session runs the coding tools installed on that machine, signed in the way you signed them in. If Claude Code, Codex, or Gemini CLI is already logged into your subscription there, that’s the account the session uses, with the usage that subscription already includes.

No API key has to be on file with Retask for those tools, and nothing meters per token — so an agent that grinds away all afternoon doesn’t quietly turn into a bill.

One machine, your whole team

Share the sandbox with your workspace and everyone can run on it — teammates and AI Agents. One machine, set up once, becomes shared capacity instead of something only its owner benefits from.

It reaches whatever your machine reaches

A VPN, an internal Git server, a staging database, a private package registry, licensed tooling, a GPU, hardware plugged into a USB port. If the machine can get to it, a session on that machine can too — no inbound access into your network required.

Set up once

Repositories, environment, credentials, and logins all live on the machine already. Nobody else installs anything, and the tenth teammate gets the same environment as the first.

Before you start

1. Install and authenticate the Retask CLI on the machine — see the CLI getting started guide.

2. Install the AI tools the sessions will run, and sign each one in. This is the step people skip. A session launches a tool like claude or codex non-interactively; it cannot complete a login for you, so a tool that isn’t authenticated yet will just sit at its sign-in prompt. Run each one by hand once, finish the login, and confirm it works before you connect the machine.

3. Install everything else the work needs, signed in the same way — git and gh, Docker, language toolchains, a VPN client, database access.

4. Keep the machine awake and online for as long as you want it available. Check its sleep settings: a laptop that suspends drops the connection.

1. Create the sandbox

In the app

1. Go to Dev Sandboxes → Sandboxes and click New sandbox. Give it a name your team will recognise — “Private VM” is fine.

2. On the sandbox page, set Type to Private VM.

3. Set Sharing to Workspace edit so teammates and agents can use it. (What each option means.)

4. Add the repositories each session should start from.

5. Set the Session init command — what runs when a session starts. The Claude Code and Codex chips fill in the usual ones, and $SEED_PROMPT receives the prompt or task the session started with.

6. Add integrations. A GitHub or GitLab token here is what lets a session clone your private repositories — see Integrations.

7. Save, and copy the sandbox ID from the page URL.

With the CLI

retask sandbox create \
  --name "Private VM" \
  --type PRIVATE \
  --sharing WORKSPACE_EDIT \
  --session-init-command 'claude --dangerously-skip-permissions "$SEED_PROMPT"' \
  --integration-provider-id github

The command prints the new sandbox_id — that’s what you connect to.

Three flags carry most of the meaning:

• --type PRIVATE makes it a Private VM. Without it you get a Cloud sandbox, and retask sandbox connect will refuse it.
• --sharing WORKSPACE_EDIT opens it to the workspace. Leave it out and the sandbox is yours alone — see below.
• --integration-provider-id github hands sessions your GitHub credentials, which is what lets them clone your private repositories. Connect the provider first — see Integrations — then reference it here. Use gitlab for GitLab, and repeat the flag if you need both.

For Codex, swap the init command for codex --yolo "$SEED_PROMPT".

Note

--sharing needs CLI v0.26.0 or newer. Run retask -v to check, and retask upgrade if you’re behind.

Sharing decides who can use it

A sandbox is Private unless you say otherwise, and a private sandbox is invisible to everyone else — including agents.

Sharing	Who can run sessions on it	Who can change its settings	Can agents target it?
Workspace edit	every workspace member	every workspace member	Yes
Workspace view	every workspace member	you, plus workspace owners and admins	Yes
Private	you	you	No

Both workspace options let the whole workspace use the machine; they differ only in who can edit the sandbox’s configuration.

An agent’s Execution target list only ever shows workspace-shared sandboxes, which is why a private one can never be picked by one. That’s deliberate: an agent acts on behalf of whoever triggers it, so a machine only you can see shouldn’t quietly become team infrastructure.

To change it later:

retask sandbox update <sandbox-id> --sharing WORKSPACE_EDIT

2. Connect your machine

On the machine itself, run:

retask sandbox connect <sandbox-id>

That’s the whole thing. The machine is now a sandbox: it goes Ready in the app, and it stays connected for as long as the command runs. Press Ctrl-C and it goes offline.

If you don’t have the ID to hand:

retask sandbox list --type PRIVATE

Options worth knowing

The command above is all you need. These are extras, not requirements.

• Where you run it is where sessions land. Each session’s working directory is created inside the folder you ran connect from, and so is retask.log. Somewhere you don’t mind collecting folders is a good choice.
• --mode headless swaps the terminal UI for plain logging on stderr — handy when the command runs somewhere nobody is watching it.
• --auto-open opens a local terminal tab for each new session, so you can watch work land on your own screen.
• --log-file and --no-log-file move or switch off retask.log, which otherwise sits next to you and rotates through retask.log.1, retask.log.2, and so on.

Every flag is in the sandbox connect reference.

Serving more than one workspace

One machine can back a Private VM in several workspaces at once — useful if you consult for more than one client, or keep work and side projects apart.

Create a sandbox in each workspace, then run one connect per sandbox, each using the profile you logged that workspace in under:

# In ~/retask/acme
retask sandbox connect <acme-sandbox-id> --profile acme

# In ~/retask/beta
retask sandbox connect <beta-sandbox-id> --profile beta

Give each one its own folder. Session folders and retask.log are created in the working directory, so two connects started from the same place would pile their sessions together and write over each other’s logs.

A dropped connection is not a lost session

Network trouble doesn’t stop a running agent. Both lanes reconnect on their own with backoff, and output produced while a session was disconnected is buffered and flushed when it comes back.

3. Run work on it

A session

Click Session at the top of the app, and under Execution target choose your Private VM by name. Add a prompt and it starts there.

An agent

Go to Settings → Members → Agents, edit the agent, and set Execution target to your Private VM. From then on every task that agent picks up runs on that machine. See Agents.

What the machine’s owner can see

Retask draws a line between the person who connected the machine and the people whose sessions run on it:

• Every session gets its own folder. Sessions never share a working directory.
• The connecting operator’s own Retask credentials are stripped from every session’s environment.
• Each session runs with a token minted for whoever started it — that teammate, or that agent — not for whoever ran connect.

What none of that can do is protect anything from the machine itself. Whoever controls the machine can read any session’s folder, inspect the environment of any session process — including that session’s Retask token and any integration secrets it was handed — and type straight into a running session’s terminal.

Connecting a machine is granting shell access

Sharing a Private VM with your workspace means trusting its owner with everything your sessions do there, and it means the machine’s owner is trusting your team with their machine. Connect hardware you and your team trust, and share it only with people who should have that level of access to each other’s work.

If a piece of work shouldn’t run on someone else’s hardware, run it on a Cloud sandbox instead.

How a session starts on your Private VM

Your machine never accepts an inbound connection. When retask sandbox connect starts, it dials out to Retask’s sandbox proxy and holds two kinds of connection open.

That’s why a Private VM works from behind NAT, a corporate firewall, or a home router with nothing forwarded.

When a session starts

1. A session is requested. Someone starts one from the app, or an agent picks up a task. The proxy sends a new_session message down the data lane, carrying the sandbox’s configuration, the session’s system prompt, and its seed prompt.

2. Your machine opens a session lane for it and streams setup progress into it — so whoever started the session watches the machine prepare it, live.

3. A session folder is created, named after the session, inside the folder you ran connect from.

4. Agent instructions are written into that folder as CLAUDE.md and AGENTS.md, so whichever tool runs picks up the session’s system prompt.

5. Repositories are cloned into the folder, each on its configured branch. A GitHub or GitLab token from the sandbox’s integrations authenticates the clone through a host-scoped git header, so the token never lands in the clone URL or in the repository’s .git/config. A repository already there is fetched and reset rather than re-cloned.

6. The environment is assembled in three layers, each overriding the last: the machine’s own environment — minus the operator’s Retask credentials, and minus the variables that describe your terminal rather than the session’s — then the sandbox’s configured variables and secrets, then the session’s own: its ID, its seed prompt, the workspace, and that per-session Retask token.

7. The session init command runs in a terminal, from inside the session folder. Its output is what streams back up the session lane to the browser. If you didn’t set one, you get a plain shell.

When a session stops

Stopping a session sends stop_session down the data lane. Your machine ends that session’s process and closes its session lane. A stopped session is finished: it can’t be resumed, and picking the work back up means starting a new one.

Its folder stays on the machine, though, and folders accumulate. Delete the ones you no longer need to reclaim the space — a future release of the CLI will clear them out for you.

Meanwhile the proxy pings the data lane on a regular interval and your machine answers. If enough consecutive pings go unanswered, the sandbox is marked as errored and its sessions are closed — that’s how a machine that went to sleep or lost power stops looking available.

Troubleshooting

sandbox ... must be type PRIVATE — connect refuses a Cloud sandbox. Switch the sandbox’s Type to Private VM, or create a new one with --type PRIVATE.

It doesn’t appear as an agent’s Execution target — its sharing is still Private. Run retask sandbox update <sandbox-id> --sharing WORKSPACE_EDIT, or change Sharing on the sandbox page.

The AI tool starts, then asks you to log in — that tool isn’t authenticated on the machine. Run it by hand there, complete the sign-in, then start a fresh session.

Repositories fail to clone — the session had no GitHub or GitLab token. The setup log warns when it finds none, and offers Retry, Continue, or Exit. Connect the integration and add it to the sandbox.

The sandbox shows an error after you closed your laptop — the heartbeat went unanswered. Reconnect with retask sandbox connect <sandbox-id> and it returns to Ready.