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

# Dev Environment

> How Twill's per-workspace sandbox and per-task forks host every connected repo so the agent works against a real environment

Twill gives each workspace a long-lived dev environment — a **workspace sandbox** — that hosts every connected repository. Every task runs in a cheap **fork** of that sandbox, so the agent never works in a vacuum: it has the real environment, with running services, installed dependencies, and `.env` files already in place.

## Workspace sandbox

Each workspace gets one persistent sandbox. It's where you set up your dev environment once, and Twill reuses it for every task.

* **One per workspace.** Set it up once — install deps, configure `.env` files, get the dev server running — and every future task starts from that state.
* **All connected repos live on it.** Each connected repo is cloned to `/root/workspace/{owner}/{repo}`. Multiple repos in the same workspace share the same sandbox.

<Info>
  Manage the workspace sandbox (env variables, SSH access) from the
  **Environment** page in the Twill app.
</Info>

## Task forks

When you start a task, Twill forks the workspace sandbox. The fork inherits every file, every dependency, every running process — so the agent works against a real, running environment from the first second.

* **One fork per task.** Concurrent tasks don't step on each other's files, ports, or processes.
* **Reused on retry.** If you re-run a job on the same task, Twill keeps the same fork. Running dev servers, installed deps, and any `.env` edits from the previous attempt all survive.
* **Isolated from the workspace sandbox.** Changes the agent makes during a task stay in the fork — they never pollute your base environment.

## Fixing your dev environment

Two ways to fix or extend your dev environment, depending on whether you want a guided agent or hands-on control.

### Talk to the Dev Environment Agent

Twill ships with a specialized **Dev Environment Agent** that handles install steps, missing system packages, broken dev servers, and `.env` updates. Start a task with **Dev Env** mode selected (or send a follow-up message in Dev Env mode on an existing task) and the agent will pick it up.

What makes this different from a regular task: the Dev Environment Agent runs **directly on the workspace sandbox**, not in a fork. Anything it installs, configures, or writes to `.env` persists to every future task fork.

Good prompts:

* "The dev server won't start — figure out why and fix it."
* "Add `STRIPE_SECRET_KEY` to my `.env` and restart the API."
* "Install Postgres and run the migrations."

See [Automatic Environment Setup](/auto-onboarding) for how the agent bootstraps a brand-new repo.

### SSH in directly

For hands-on debugging, click **Ssh & Preview** in the task header or on the Environment page. Twill returns a 60-minute, token-scoped SSH command and lets you hand off to your preferred client.

<CardGroup cols={3}>
  <Card title="Local Terminal" icon="terminal">
    Copies the `ssh` command and opens your default `ssh://` handler.
  </Card>

  <Card title="VS Code" icon="code">
    Opens VS Code with the Remote-SSH extension pointed at the sandbox.
  </Card>

  <Card title="Cursor" icon="code">
    Opens Cursor with its Remote-SSH integration pointed at the sandbox.
  </Card>
</CardGroup>

SSH works for both the workspace sandbox and any task fork:

* Use a **workspace sandbox** session when you want the change to persist across every future task (installing a system package, editing the entrypoint script, updating shared `.env`).
* Use a **task fork** session when you're just unblocking the current task and don't need the change to outlive it.

## What's preinstalled

Both the workspace sandbox and its forks start from the same Ubuntu 22.04 snapshot, with common tooling already in place.

### Languages and runtimes

* **Node.js** (LTS) with npm, managed via nvm
* **Python 3** with pip
* **Bash**

Need a different language version? The [Dev Environment Agent](/auto-onboarding) installs additional runtimes as part of your project's entrypoint script.

### Package managers

| Manager | Use case                                     |
| ------- | -------------------------------------------- |
| pnpm    | Fast, disk-efficient Node.js package manager |
| npm     | Bundled with Node.js                         |
| uv      | Fast Python package manager                  |
| pip     | Standard Python packages                     |

### Docker

A full Docker engine is preinstalled. The agent can build images, run containers, and use Docker Compose to spin up databases, caches, and other services.

```bash theme={"theme":"github-dark"}
# The agent can run your project's Docker Compose stack
docker compose up -d
```

<Info>
  Docker Compose is available as a plugin (`docker compose`), not as a
  standalone binary.
</Info>

### CLI tools

| Tool       | Purpose                                 |
| ---------- | --------------------------------------- |
| git        | Version control                         |
| gh         | GitHub CLI for PRs, issues, and actions |
| jq         | JSON processing                         |
| make       | Build automation                        |
| curl, wget | HTTP requests                           |
| openssl    | TLS and crypto utilities                |

### Cloud CLIs

Agents can interact with cloud services when you provide credentials through workspace environment variables:

* **AWS CLI v2**
* **Google Cloud CLI**

<Tip>
  Add cloud credentials as workspace or repository env variables in the
  **Environment** page. The agent picks them up automatically when it runs
  deploys, accesses cloud databases, or pulls assets during builds.
</Tip>

### Browser automation

A headless Chromium browser is preinstalled. The agent uses it to:

* Verify UI changes by navigating your running app
* Take screenshots of before/after states
* Test form submissions and navigation flows
* Record browser sessions for review

Puppeteer and Playwright pick up the preinstalled browser automatically — no extra download or configuration needed.

### Virtual display

A virtual display (Xvfb) is available for testing desktop applications or tools that require a screen. This powers Twill's computer-use capabilities, including screenshot capture and mouse/keyboard automation.

## Live previews

Any port the agent opens inside a task fork is exposed as a unique public preview URL, so you can validate UI and behavior before approving the PR. See [Live Previews](/live-previews) for details.