Why Environments Matter
Environments let agents verify their work against a running preview before completing a task. Instead of blindly generating code, agents can start your app, run tests, and confirm everything works end-to-end.
How Environments Are Created
When Twill runs on a repository without an environment configured, it automatically analyzes your codebase and creates one:
- Detects your stack — package managers, frameworks, databases, Docker services
- Creates entrypoint script — installs dependencies, starts services, runs dev server
- Identifies ports — exposes the right ports for previews
- Extracts environment variables — from
.env.example and config files
The agent can also fix broken environments. If the entrypoint fails or
services don’t start correctly, the agent will diagnose and repair the
configuration automatically.
Manual Configuration
You can customize or override the auto-generated environment in the Environments page.
| Setting | Purpose |
|---|
| Snapshot | Base sandbox image with OS, tools, and resources |
| Entrypoint Script | Shell script that runs on sandbox startup |
| Exposed Ports | Ports accessible for live previews |
| Environment Variables | Secrets and config injected at runtime |
Snapshots
Choose the sandbox size based on your project’s needs:
| Snapshot | Resources |
|---|
| Twill Small | 2 vCPU · 4 GiB RAM · 8 GiB Disk |
| Twill Medium | 4 vCPU · 8 GiB RAM · 12 GiB Disk |
| Twill Large | 8 vCPU · 16 GiB RAM · 16 GiB Disk |
Need a custom snapshot with specific dependencies? Contact support.
Entrypoint Script
The entrypoint script runs when the sandbox starts—use it to install dependencies, start services, and run your dev server.
Requirements
- Idempotent — Must succeed when run multiple times
- No .env handling — Environment variables are injected automatically; don’t create or source
.env files in the script
- Use
$TWILL_ENTRYPOINT_LOG_DIR — For logs and PIDs
Example
#!/bin/sh
set -e
LOG_DIR="${TWILL_ENTRYPOINT_LOG_DIR:-/root/entrypoint-logs}"
mkdir -p "$LOG_DIR"
# Install dependencies
pnpm install
# Start infrastructure
docker compose up -d
# Run migrations
pnpm db:migrate
# Start dev server (check if already running)
if ! curl -fsS http://localhost:3000 >/dev/null 2>&1; then
nohup pnpm dev > "$LOG_DIR/dev-server.log" 2>&1 &
echo $! > "$LOG_DIR/dev-server.pid"
fi
Service Logging
Use $TWILL_ENTRYPOINT_LOG_DIR to create separate log tabs in the preview UI:
#!/bin/sh
mkdir -p "$TWILL_ENTRYPOINT_LOG_DIR"
pnpm run api >> "$TWILL_ENTRYPOINT_LOG_DIR/api.log" 2>&1 &
exec pnpm dev >> "$TWILL_ENTRYPOINT_LOG_DIR/frontend.log" 2>&1
Exposed Ports
List ports that should be accessible for live previews:
Ports can be separated by commas, spaces, or newlines. The first port is treated as the primary preview port.
Example (also valid):
Each port gets a unique preview URL.
Environment Variables
Add secrets and configuration in the Environment Variables tab. You can paste from a .env file.
Don’t handle .env files in your entrypoint script. Twill automatically
injects all configured environment variables into the sandbox before the
entrypoint runs.
Dynamic Variables
Twill expands these variables at runtime:
| Variable | Expands To |
|---|
${TWILL_SANDBOX_URL} | Public sandbox URL |
NEXTAUTH_URL=${TWILL_SANDBOX_URL}:3000
API_URL=${TWILL_SANDBOX_URL}:8080
Accessing Previews
From any task, click Preview to access your running application:
- Web Preview — View your app on any exposed port
- SSH — Connect VSCode/Cursor directly to the sandbox
- Logs — Monitor services in real-time
