# Sandboxes

import { Aside } from '@astrojs/starlight/components';

Sandboxes are isolated machines for development, experiments and agent work.
Create and manage them in the [Avrea console](https://console.avrea.com) or
with the [CLI](/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](/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:

```bash
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](#preserve-work-and-manage-lifecycle) as it may.

<Aside type="caution" title="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.
</Aside>

[Agent sandboxes](#agent-sandboxes) follow different rules.

### Start with your repository and caches

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

```bash
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](/cache/overview/).

## 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:

```bash
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:

```bash
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:

```bash
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:

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

<Aside type="caution" title="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](#fork-a-sandbox). 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.
</Aside>

### 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:

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

For public previews and webhooks, see [Sandbox HTTPS URLs](/sandbox-https/).
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](#time-limits) 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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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](/agent-sandboxes-claude-code/)