Skip to main content

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.

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.
Manage the workspace sandbox (env variables, SSH access) from the Environment page in the Twill app.

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

Local Terminal

Copies the ssh command and opens your default ssh:// handler.

VS Code

Opens VS Code with the Remote-SSH extension pointed at the sandbox.

Cursor

Opens Cursor with its Remote-SSH integration pointed at the sandbox.
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 installs additional runtimes as part of your project’s entrypoint script.

​
Package managers

ManagerUse case
pnpmFast, disk-efficient Node.js package manager
npmBundled with Node.js
uvFast Python package manager
pipStandard 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. 
# The agent can run your project's Docker Compose stack
docker compose up -d
Docker Compose is available as a plugin (docker compose), not as a standalone binary.

​
CLI tools

ToolPurpose
gitVersion control
ghGitHub CLI for PRs, issues, and actions
jqJSON processing
makeBuild automation
curl, wgetHTTP requests
opensslTLS 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
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.

​
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 for details.