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

# Automatic Environment Setup

> How Twill boots your repo into a working sandbox so it can run the app and self-verify changes

When you connect a new repository, Twill doesn't require manual configuration. A specialized **Dev Environment Agent** analyzes your codebase, creates a complete sandbox environment, and gets your project running so the agent can verify its work against a real system.

## How It Works

The Dev Environment Agent runs when:

1. **First task on a repository** — No environment exists yet
2. **Environment failure detected** — Existing setup has errors

The agent inspects your repository structure, detects your stack, and generates an idempotent entrypoint script that bootstraps everything needed to run your project.

## What the Agent Analyzes

The agent examines your repository to understand:

* **Package manager** — Lockfiles like `pnpm-lock.yaml`, `package-lock.json`, `poetry.lock`
* **Framework** — Next.js, Django, Rails, FastAPI, etc.
* **Infrastructure** — `docker-compose.yml`, database requirements
* **CI/CD workflows** — GitHub Actions, GitLab CI for environment hints
* **Config files** — `.env.example`, framework configs, build scripts

## The Bootstrap Process

The generated entrypoint script follows five phases:

1. **System dependencies** — Installs missing packages and version managers
2. **Project dependencies** — Runs the appropriate install command for your package manager
3. **Infrastructure services** — Starts Docker Compose and waits for healthy status
4. **Database setup** — Runs migrations and seeds test data
5. **Development server** — Starts your dev server in the background with logging

## Learning and Persistence

Environment fixes aren't throwaway. The Dev Environment Agent runs **directly on the workspace sandbox**, not in a per-task fork, so anything it installs or configures persists for every future task. Learn more about [the workspace sandbox and task forks](/sandbox-environment).

When the agent updates the configuration:

1. Changes are written to special files in the sandbox
2. Twill detects and validates these updates
3. New configuration is persisted to the database
4. Future tasks use the improved environment

This creates a learning loop—each fix makes the environment more robust for future runs.

<Info>
  For complex or non-standard setups, you can SSH into the workspace sandbox and
  configure it directly. See [Dev
  Environment](/sandbox-environment#fixing-your-dev-environment).
</Info>