Quickstart

This guide gets you from zero to a working local Autopilot instance — orchestrator, worker, and your first task.

Prerequisites

• Bun installed
• A git repository to work in
• An API key for your AI provider (e.g., Anthropic for Claude Code)

Install

bun add -g @questpie/autopilot

Bootstrap your project

In your repo root:

autopilot bootstrap

Bootstrap walks you through setup interactively:

1. Choose mode: local-first (scaffold and run locally) or join-existing (connect to an existing orchestrator)
2. Choose operator surface: Claude Code + MCP (recommended) or CLI-only
3. Enter company/project basics
4. Select a starter workflow template

This creates the .autopilot/ directory with your config:

.autopilot/
├── company.yaml
├── project.yaml
├── agents/
│   └── dev.yaml
├── workflows/
│   └── default.yaml
└── context/
    ├── company.md
    └── project.md

Set your AI provider credentials as environment variables:

export ANTHROPIC_API_KEY=sk-ant-...

Start locally

For local development, boot both orchestrator and worker:

autopilot start

This is equivalent to running autopilot server start and autopilot worker start separately.

Create your first task

autopilot tasks create --title "Add a health check endpoint" --type feature --description "Add a GET /health endpoint that returns 200 OK with uptime info"

The task enters the default workflow. The worker claims the resulting run and begins execution.

Watch progress

autopilot inbox --watch

This shows real-time updates as the task progresses through workflow steps.

Review and act

When a task needs review or reaches an approval step:

# See what needs attention
autopilot inbox

# Approve a task
autopilot tasks approve <task-id>

# Reject with reason
autopilot tasks reject <task-id> --message "Needs error handling"

# Reply with additional context
autopilot tasks reply <task-id> --message "Use the existing middleware pattern"

Inspect results

# View task details
autopilot tasks show <task-id>

# List runs for a task
autopilot runs --task <task-id>

# Show run details and artifacts
autopilot runs show <run-id>

If the run produced previews, the orchestrator serves them at the URL shown in the run's artifacts section.

Install a surface pack

To add a notification or conversation surface (e.g., Telegram), declare it in your company config and sync:

packs:
  - ref: questpie/telegram-surface

autopilot sync

This materializes the provider and handler into .autopilot/. See Packs and Distribution for details and Telegram Surface for the full setup guide.

Next steps

• Architecture — understand orchestrator, worker, and truth boundaries
• Operator Guide — full CLI workflows and async operation
• Providers and Handlers — providers, handlers, and surfaces
• Packs and Distribution — install integrations via the pack system
• Cloud and Deployment — multi-worker and remote deployment