> ## Documentation Index
> Fetch the complete documentation index at: https://vespin.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud environment

> Variables, software, setup scripts, and run actions for your cloud agents

Each cloud agent works in its own sandbox: a Linux machine with a checkout of the task's repository. **Settings › Cloud environment** sets up what every sandbox in the workspace starts with. Owners and admins edit it. Members can read the scripts, the variable names, and the values of config variables.

![Settings, Cloud environment: Sandbox at 2 vCPUs and 4 GB, five variables with who added each, two of them configs with their values hidden behind a show button, and the install script](https://mintcdn.com/stage-a8145d8f/4EKA_a_AhZy3IBeH/images/cloud-environment.png?fit=max\&auto=format\&n=4EKA_a_AhZy3IBeH\&q=85\&s=1e53d8fa43eaf67c5a24ac8b6702639d)

## Sandbox size

Every cloud agent in the workspace runs at one size, which owners and admins choose under **Sandbox**: 2 vCPUs and 4 GB of memory, 4 vCPUs and 8 GB, or 8 vCPUs and 16 GB. New agents use it right away, and existing ones the next time they start. A workspace starts at 2 vCPUs.

## Variables

Variables are set in every cloud agent's sandbox, in every repository. Use them for the keys your tests and dev server need. A **Secret** is hidden once it's saved. A **Config** stays visible to everyone in the workspace. To change a value, choose **Edit** from the variable's **⋯** menu.

The agent can read a variable's value, so anything it prints may reach its model and transcript. Agents on a Mac don't get these variables; they use the Mac's own environment.

## Install software

The install script runs as root each time a sandbox boots, including when a stopped one starts again, before the repository's setup script. If it fails, the setup script is skipped. Use it for system packages:

```sh theme={null}
apt-get install -y postgresql-client
```

## Setup scripts

A repository's setup script runs once in each agent's checkout, after it's cloned, with the workspace's variables. Use it to install dependencies:

```sh theme={null}
pnpm install
cp .env.example .env
```

The agent starts while the script runs. Its output goes to `/tmp/vespin-setup.log`, which ends with `--- exit N` when it finishes, and the agent reads that log before relying on the setup. A script that fails stops at the failed command and runs again the next time the sandbox is made.

## Run actions

A run action is a named command for a repository, such as a dev server or a test suite. It runs from the **Run** button at the end of the agent's tab row, which runs the default action, or stops it while it runs. <kbd>⌘K</kbd> lists every action too. In the Mac app, <kbd>⌥⌘R</kbd> runs the default.

![The Run button reading Dev server, its menu open: Dev server marked Default with ⌥⌘R, Members tests, Seed pending invites, Email previews, each with its command, and Edit run actions… at the foot](https://mintcdn.com/stage-a8145d8f/EAMsVV_TcNHcjtNJ/images/run-actions.png?fit=max\&auto=format\&n=EAMsVV_TcNHcjtNJ\&q=85\&s=a591c7b72a0f4321f6d743d60e330c60)

An action's output shows in a read-only Terminal tab beside the agent. Each action can run for cloud agents, agents on a Mac, or both. A repository holds up to 20.

## The sandbox

| | |
| - | - |
| Size | The workspace's [sandbox size](#sandbox-size): 2 vCPUs and 4 GB of memory by default, up to 8 vCPUs and 16 GB |
| Base | Ubuntu with Node 24, pnpm, Python, Docker, Playwright with Chromium, `gh`, and the agent CLIs. The agent has passwordless `sudo`. |
| Network | Open internet |
| Stops | After 5 minutes idle, or 24 hours after it starts. The next message starts it again, with the checkout and any unpushed work as they were. |
| Deleted | After 7 days unused, with its checkout. Push work you want to keep. |

From a terminal, `vespin env` manages variables and `vespin setup` manages setup scripts and run actions. See [Workspace](https://vespin.dev/docs/cli/workspace.md).
