Sandboxes

Sandboxes are isolated machines for development, experiments and agent work. Create and manage them in the Avrea console or with the CLI. The console and CLI still call sandboxes VMs in many places, for example the avr vm commands and Create VM.

Before you start

Select your organization in the console, then open Sandboxes. macOS sandboxes are available on request: contact Avrea to enable them for your organization.

For terminal workflows, install and authenticate the CLI, and select your organization with avr config set org <org-id>, or pass --org <org-id> to individual commands. Run avr vm capabilities to discover available operating systems, architectures and sizes rather than assuming every combination is supported.

Create a sandbox

In Sandboxes, choose Create VM. Select a machine, version, vCPU count and time limit. Under Access & setup, add your SSH public keys, or keep your account's default keys, and optionally choose a repository and branch, remote desktop and cache overrides.

The equivalent CLI workflow is:

avr vm capabilities
avr vm create --name dev --os linux --size 2-vcpu \
  --ssh-key @~/.ssh/id_ed25519.pub --ttl 8h --wait

Creation takes time. --wait waits until the sandbox is running and prints connection instructions. Without it, use avr vm show dev to check readiness. Save the one-time password avr vm create prints: it cannot be retrieved later. The console does not show one; choose Rotate password on the sandbox's page when you need a password.

Names can be used instead of IDs in CLI commands. If you omit a name, Avrea generates one.

Time limits

The default time limit is eight hours, with a maximum of seven days. Without a payment method, a sandbox runs for at most two hours from its creation, extensions included, and the default is two hours. A fork is a new sandbox and gets its own two hours. When it ends, a Linux x86_64 sandbox is normally paused and keeps its disk. If its Settings show Delete after instead of Pause after, it is deleted with its disk at the limit. Sandboxes that cannot pause, such as Windows, macOS and Linux arm64, are always deleted with their disk, and so is a sandbox whose organization already keeps as many paused sandboxes as it may.

Paused sandboxes are deleted after 7 days

A paused sandbox is deleted, with its disk, 7 days after its time limit ended. Extend the time limit before then to keep your work.

Agent sandboxes follow different rules.

Start with your repository and caches

Choose a repository and branch in the creation dialog, or use:

avr vm create --name project --os linux --size 2-vcpu \
  --ssh-key @~/.ssh/id_ed25519.pub --repo owner/repository --ref main --wait

Repository preload is best-effort. The branch defaults to the repository's default branch; tags, pull-request refs and raw commit SHAs are unsupported. An attached repository supplies its normal build and CI cache settings. Without one, package-manager mirrors stay available, but repository caches do not. Cache overrides can disable inherited caches, but cannot enable them. The CLI supports repeatable --disable-cache options. See Cache.

Connect and work

Open a running sandbox in the console and use its SSH terminal, which also shows the SSH command for your own terminal.

From your terminal:

avr vm ssh dev
avr vm ssh dev -- uname -a
avr vm ssh dev --session work

--session attaches to a persistent tmux session that survives a dropped connection. For editor access, scp or rsync, add an SSH configuration:

avr vm ssh-config dev --append

Use the generated alias in your SSH client or editor's Remote-SSH extension. Run this command again after a resume to refresh the endpoint. The CLI pins published SSH host keys; when none is published, it warns and uses trust-on-first-use.

Set up tools with the CLI

Bootstrap installs development tools and optionally clones a repository over SSH. This is a CLI workflow:

avr vm bootstrap dev --setup-github --install claude,codex \
  --repo https://github.com/owner/repository

--setup-github forwards your local GitHub authentication. Agent credentials are forwarded only when you explicitly add --forward-agent-creds. Bootstrap changes persist on the preserved disk across pause and resume. For a one-off command that needs environment variables supplied by bootstrap, use a login shell:

avr vm ssh dev --login -- claude -p 'summarize the repository'

Forwarded credentials stay on the disk

Forwarded tokens are stored on the sandbox's disk. They survive pause and resume and are copied into forks. Anyone with admin access to the sandbox or a fork can use them. A forwarded Claude subscription token is valid for a year. Revoke forwarded tokens when you no longer need the sandbox.

Desktops, local ports and public previews

Enable remote desktop at creation, or pass --remote-desktop to avr vm create. Availability depends on the operating system version; on Linux it needs Ubuntu 26.04 on x86_64. Use avr vm rdp dev for Windows or Linux, or avr vm vnc dev for macOS. These commands tunnel through SSH.

Forward application ports to your own computer with --port GUEST or --port LOCAL:GUEST. This example forwards guest port 8080 to local port 8080, and guest port 3000 to local port 9000:

avr vm port-forward dev --port 8080 --port 9000:3000

For public previews and webhooks, see Sandbox HTTPS URLs. The console lists published URLs under HTTPS URLs on the sandbox's page; the CLI can request them at creation with repeatable --https-port options. Anyone with a published URL can reach the application, so add application authentication for sensitive content.

Preserve work and manage lifecycle

Pause is supported for Linux x86_64 sandboxes. Other sandboxes, and those whose Settings show Delete after, are deleted when their time limit ends, so extend the limit or copy your work out first.

An organization can keep one paused sandbox per vCPU of its sandbox quota. Pausing another fails until you delete or resume one.

The console offers Pause on supported sandboxes and Start to resume a paused sandbox. Console pause saves the disk, so running processes do not survive. If its time limit has ended, set Startable for in Settings and save before starting it, within the 7-day retention.

avr vm pause dev --wait
avr vm update dev --ttl 8h
avr vm resume dev --wait

The CLI also offers avr vm pause dev --memory to preserve memory and continue running processes on resume. If memory restoration cannot complete, resume with --discard-memory to boot from the preserved disk instead.

Fork a sandbox

To make an independent copy of a paused sandbox, choose Fork, or run:

avr vm fork dev --name experiment --wait

Fork leaves the source paused. It copies the disk and machine configuration, including SSH host keys, the password and anything stored on the disk, but discards memory state. No password is returned; rotate it if needed.

Not every paused sandbox can be forked: the console shows Fork only when the saved disk supports it. Forking requires admin access to the source and read access to its repository. If the source has its own egress firewall rules, it also requires organization admin. Agent sandboxes cannot be forked.

Change settings

In Settings, change the name, time limit or SSH keys. Updated SSH keys apply immediately to a running sandbox, or on its next resume otherwise. Saving SSH keys on a running sandbox also issues a new one-time password, and the old password stops working.

On a running sandbox, admins can choose Rotate password to obtain a fresh one-time password. CLI equivalents:

avr vm update dev --name dev2 --ttl 8h
avr vm update dev2 --rotate-password

Delete a sandbox

Choose Delete and confirm when finished, or run:

avr vm delete experiment --wait

Deletion is asynchronous while the sandbox is live. --wait waits for it to finish. Delete sandboxes only when you no longer need their saved work.

Metrics and usage

Open the console's Metrics tab to inspect sandbox resource use. The Firewall tab shows its egress controls. From the CLI:

avr vm list
avr vm metrics dev --watch
avr vm usage

Usage reports include deleted sandboxes. Run avr vm --help, or avr vm <command> --help, for all options, including JSON output, time windows and firewall configuration.

Agent sandboxes

A coding-agent service starts an agent sandbox to run one of your sessions. The agent's model runs at the service; the sandbox runs the agent's tools against your repository. The sandbox connects out to the service, and nothing connects in.

Agent sandboxes differ from the sandboxes you create:

• They run Linux on x86_64, with 4 vCPUs unless you choose another size, and have no remote desktop.
• They boot once. They cannot be paused, resumed or forked, and their disk is not kept.
• They are deleted when the session ends, or when their time limit ends. Anything not committed and pushed is lost with them. One that fails shows as Failed and is deleted 7 days after its time limit.
• Their name comes from the service's request.
• Each one is a VM of the organization the service's setup names, and counts toward that organization's quotas and usage.

To list them, choose Agent sandboxes in the console's sandbox list, or run avr vm list --sandbox. avr vm list --no-sandbox lists only the sandboxes people created.

Supported services:

• Claude Code