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

# Environments

> Configure sandbox environments for your sessions — repositories, setup scripts, dev servers, preview URLs, and environment variables.

## What is an environment?

An **environment** defines how the sandbox is set up when you start a session. It tells Magnet which repository to clone, how to install dependencies, and optionally how to run a dev server with a live preview.

You can create multiple environments — one per project or repository — and select which to use when starting a session.

## Creating an environment

Go to **Settings** > **Sandbox** and click **New Environment**, or create one during the [setup wizard](/quickstart#step-3-create-an-environment).

### Repository

Choose a GitHub repository and branch. The sandbox will clone this repo when a session starts.

* **GitHub Repository** — select from your connected repositories
* **Branch** — the branch to clone (defaults to `main`)

### Environment settings

* **Name** — a label for this environment (auto-suggested from the repo name)
* **Enabled** — disabled environments can't be used for sessions
* **Default** — the environment pre-selected when starting new sessions

### Setup script

Commands that run after the repo is cloned — typically used to install dependencies.

```bash theme={null}
pnpm install
```

You can run multiple commands:

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

### Run script

A command to start your development server. This runs in the background while the agent works.

```bash theme={null}
pnpm dev
```

### Preview port

The port your dev server listens on. When configured, Magnet provides a **preview URL** that lets you see your app running live inside the sandbox.

For example, if your Next.js app runs on port `5173`, set the preview port to `5173`. You'll get a URL you can open in your browser to see the app as the agent makes changes.

<Note>
  Port `3000` is reserved for Magnet's internal server. Use a different port for your app.
</Note>

### Node.js version

Choose between Node 20 (LTS Active) and Node 22 (LTS Current).

### Environment variables

Add environment variables and secrets that your project needs. These are injected into the sandbox when the session starts.

Common use cases:

* **API keys** for third-party services
* **Database connection strings**
* **Feature flags**

Variables marked as **secret** are encrypted and never displayed after saving.

## Managing environments

### Viewing environments

Go to **Settings** > **Sandbox** to see all your environments. Each card shows the environment name, repository, branch, and whether it's enabled.

### Editing an environment

Click on any environment card to open the edit dialog. Changes take effect for new sessions — running sessions are not affected.

### Multiple environments

You can create environments for different projects or configurations:

* `acme/web-app` — your main web application
* `acme/api` — your backend service
* `acme/web-app (staging)` — same repo but different branch or env vars

When starting a session, select which environment to use from the environment picker.

## Preview URLs

When you configure a **run script** and **preview port**, Magnet starts your dev server in the sandbox and gives you a URL to access it. This lets you:

* See your app running live as the agent makes changes
* Test the agent's work before merging the PR
* Share the preview with teammates for review

The preview URL is active for the duration of the session.