# Environments

An environment saves how a repository is prepared — variables and secrets,
install and start scripts, and common commands — so every new task on it
starts ready to build and test. Environments are optional: without one, a task
starts from the platform's base image with your personal global variables.

Manage them in **My Settings → Environments**.

## Create an environment

Choose **New environment**, give it a name and a repository, and fill in its
sections. Each repository can have several environments; **Make default**
picks the one new tasks on that repository use. Saving creates a new version;
**History** lists earlier versions, and **Restore** saves one of them again.

### Variables

Variables are given to the agent and to your project's code. Each is **Plain**
or **Secret**. A Secret must be at least 8 characters and is never shown again
after you save it. **Import .env** pastes a `.env` file in one step; its values
become Secrets unless you mark them Plain.

**Available during** limits when a variable is set: **Install only** values are
not given to the agent or the start script, and **Runtime only** values are not
given to the install script.

Platform names such as `CLAUDE_*`, `CODEX_*`, `PATH` and `HOME` are reserved.
`OPENAI_API_KEY`, `OPENAI_BASE_URL`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`
and `ANTHROPIC_BASE_URL` reach your code and the commands the agent runs, but
the agent's own model calls still go through FreeInference. Setting one of a
provider's names replaces all of them, so add its base URL too if you use one.

### Scripts

| Script | When it runs | Time limit |
|---|---|---|
| **Install script** | Once in each new workspace, to install dependencies, for example `npm ci`. Skipped when the workspace starts from a saved installation | 15 minutes |
| **Update script** (optional) | Instead of the install script when the workspace starts from a saved installation, for steps that follow the source such as code generation or migrations | 15 minutes |
| **Start script** | After installation, and whenever the sandbox starts again. Start background services, wait until they are ready, then exit | 2 minutes |
| **Verification command** | Only when you test the environment, for example `npm test` | 5 minutes |

**Suggest from lockfiles** proposes an install command from the lockfiles at
the repository root.

### Actions

Actions are saved commands, such as running the tests or a dev server, that you
can run with one click from a task's **Environment** tab.

### Test and prebuild

**Test** runs the install script, start script and verification command in a
temporary sandbox, without an agent. The scripts run for real and can affect
external services. A passing test queues a prebuild: a saved installation that
new tasks start from, skipping the install script, as long as the lockfiles
have not changed.

## Personal global variables

**Personal global variables**, on the Environments page, are used in
every task, including tasks [from scratch](from-scratch.md). A variable with
the same name in an environment takes precedence.

## In a task

A new task on a repository uses the repository's default environment. To pick
another, or **No environment**, open **+ → Environment** in the composer before
you send the first message.

Preparation starts with the first turn, or when you open a terminal. The
**Environment** tab in the workspace pane shows its progress and output:

- **Preparation failed** shows which step failed; **Retry preparation** runs it
  again.
- **Skip the start script next turn** lets your next turn start even if the
  start script is failing. Services it starts may be unavailable.
- **Actions** run your saved commands; **Open terminal** shows their output.
- **Update runtime variables** takes the latest saved variable values from the
  next turn. Installed dependencies stay as they are, and running services keep
  their current values.

A workspace keeps the environment version it started with. When a newer
version is saved, the tab offers **Start a new task with the latest version**.

## Keep in mind

Variables and Secrets are readable by the agent and by any code that runs in
the sandbox, and the sandbox can reach the public internet. Known Secret values
are masked in what the platform shows and checked before it publishes, but an
agent that is told to can still send them elsewhere. Give an environment only
credentials you would hand to the agent, and prefer narrowly scoped ones. See
[Sandbox and security](security.md).