# Billing and Payments
Source: https://docs.capy.ai/admin/billing
Manage your Capy subscription, monitor real-time usage, add balance manually or with auto-reload, and view per-task cost breakdowns from the dashboard.
## Subscription
Manage your subscription at [capy.ai/settings/org/billing](https://capy.ai/settings/org/billing).
## Usage monitoring
Monitor usage in the dashboard:
* Real-time balance
* Per-task cost breakdown
* Historical usage
## Adding balance
You can add funds to your organization in two ways:
### Manual balance purchase
1. Navigate to [Settings → Billing](https://capy.ai/settings/org/billing)
2. Click the "Add balance" button in the Extra Balance section
3. Choose from preset amounts (\$10, \$25, \$50) or enter a custom amount (\$5-\$5,000)
4. Complete the Stripe checkout process
The "Add balance" button is also available in the sidebar for quick access.
### Auto reload
Auto reload automatically adds funds when your balance falls below a threshold. This ensures uninterrupted service without manual intervention.
#### Setting up auto reload
1. Go to [Settings → Billing](https://capy.ai/settings/org/billing)
2. Scroll to the "Auto-reload" section (owner only)
3. Toggle "Enable auto-reload" to on
4. Configure your preferences:
* **When balance goes under:** Set the dollar threshold that triggers a reload (e.g., \$5)
* **Bring balance back up to:** Set the target balance after reload (e.g., \$10)
#### How auto reload works
* When your balance drops below the threshold, the system automatically adds funds
* Balance is brought up to the reload amount you specified
* Reload amount must be greater than or equal to the threshold
* The system checks your balance after each usage event
* Payment is processed through your saved payment method
**Example:** If you set threshold to \$5 and reload amount to \$10:
* When balance drops below \$5, auto reload triggers
* System adds enough funds to bring balance to \$10
* You can continue working without interruption
## Upgrading
Upgrade to higher plans for more monthly usage allowance and concurrent sessions.
## Enterprise
Contact us for custom billing arrangements, volume discounts, and annual contracts.
# Team Members and Roles
Source: https://docs.capy.ai/admin/members
Manage your Capy organization — invite team members, assign Owner, Admin, or Member roles, and control access to projects and settings.
## Roles
Every organization member has one of three roles:
| Role | What they can do |
| ---------- | ----------------------------------------------------------------- |
| **Owner** | Full control - billing, members, settings, integrations, projects |
| **Admin** | Manage members, projects, integrations, and settings |
| **Member** | Create and run tasks, view projects they have access to |
Each organization has exactly one owner. Ownership can be transferred to another member.
## Inviting members
1. Go to [Settings → Members](https://capy.ai/settings/org/members)
2. Click **Invite**
3. Enter one or more email addresses
4. Choose a role (admin or member)
5. Send the invite
Invited users receive an email with a link to join. Pending invitations appear in the members list and can be revoked before they're accepted.
## Managing members
From the members page, admins and owners can:
* **Change roles** - promote a member to admin, or demote an admin to member
* **Remove members** - remove someone from the organization
* **Transfer ownership** - hand over the owner role to another member (owners only)
Members and admins can leave the organization from Settings → General. Owners must transfer ownership or delete the organization first.
## Notifications
### Push notifications
Enable browser push notifications to get alerted when a task finishes. Toggle this at [Settings → Notifications](https://capy.ai/settings/notifications).
### Email notifications
Control which emails you receive:
| Notification | Where to configure | Who sees it |
| ------------------ | ------------------------------ | ----------- |
| Referral rewards | Settings → Notifications | You |
| Auto-reload alerts | Settings → Org → Notifications | Admins |
| Member invited | Settings → Org → Notifications | Admins |
# Referrals
Source: https://docs.capy.ai/admin/referrals
Earn up to $500 in credits per referral by sharing your unique link. When your friend makes a paid subscription or credit purchase, you both get bonus credits.
Share your referral link from the [referral dashboard](https://capy.ai/settings/referrals). When your friend makes a paid subscription or credit purchase, you both earn bonus credits. You need an active subscription to participate.
## How it works
1. Share your unique referral link from the [referral dashboard](https://capy.ai/settings/referrals)
2. Your friend signs up using your link
3. Your friend makes a paid subscription or credit purchase
4. Both you and your friend receive bonus credits
## Rewards
* **Referrers** earn up to \$500 in credits per qualified referral
* **Referees** also receive the same amount in bonus credits for their organization
* Credits can be applied to any organization you're a member of
## Qualification requirements
For a referral to qualify:
* You must have an active subscription to refer others
* Your friend must sign up using your referral link
* Your friend must make a paid subscription or credit purchase within 90 days of signing up
* Referrals expire after 90 days if the referee doesn't qualify
## Applying credits
1. View your earned credits in the [referral dashboard](https://capy.ai/settings/referrals)
2. Select the organization you want to apply credits to
3. Choose the amount to apply (minimum \$1)
## FAQ
Credits are awarded once your friend makes their first paid transaction.
Yes, there's no limit on the number of referrals you can make.
# Security
Source: https://docs.capy.ai/admin/security
Learn how Capy protects your code — isolated VMs per task, encrypted OAuth tokens, scoped GitHub permissions, and infrastructure security practices.
## VM isolation
Each task run executes in an isolated Ubuntu 22.04 VM. VMs are:
* Completely isolated from other users
* Destroyed after the task ends
* Unable to access other users' data
## GitHub permissions
* OAuth tokens are encrypted at rest
* Tokens are scoped to your authorized repos only
* Revoke access anytime in GitHub settings
## Data handling
* Code is processed only for your requests
* No training on your code
* Conversation history is stored securely
## Compliance
Contact us for enterprise compliance requirements.
# Create browser snapshot
Source: https://docs.capy.ai/api-reference/browser-snapshots/create-snapshot
POST /v1/projects/{projectId}/browser-snapshots
Create a new browser snapshot with cookies and localStorage state. Domains are automatically extracted from cookie domains.
# Delete browser snapshot
Source: https://docs.capy.ai/api-reference/browser-snapshots/delete-snapshot
DELETE /v1/projects/{projectId}/browser-snapshots/{snapshotId}
Delete a browser snapshot.
# Get browser snapshot
Source: https://docs.capy.ai/api-reference/browser-snapshots/get-snapshot
GET /v1/projects/{projectId}/browser-snapshots/{snapshotId}
Get a browser snapshot by ID including its full storage state.
# List browser snapshots
Source: https://docs.capy.ai/api-reference/browser-snapshots/list-snapshots
GET /v1/projects/{projectId}/browser-snapshots
List browser snapshots for a project. Private snapshots are only visible to their creator.
# Browser snapshots
Source: https://docs.capy.ai/api-reference/browser-snapshots/overview
Inject authenticated browser state into agent sessions via cookies and localStorage
## What are browser snapshots?
Browser snapshots store authenticated browser state — cookies and localStorage — that gets injected into agent VMs at startup. This lets agents interact with authenticated services (dashboards, staging environments, internal tools) without needing to log in.
## How it works
1. **Create a snapshot** with your cookies and localStorage via `POST /browser-snapshots`
2. **Mark it as default** so it's automatically applied to all sessions, or pass specific snapshot IDs when creating threads
3. **Agents get authenticated sessions** — cookies and localStorage are injected into Chrome on the VM before the agent starts
## Using snapshots with threads
Pass `browserSnapshotIds` when creating a thread or sending a message to control which snapshots are applied:
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer capy_xxxx" \
-H "Content-Type: application/json" \
-d '{
"projectId": "your-project-id",
"prompt": "Test the login flow on staging",
"browserSnapshotIds": ["snapshot-id-1", "snapshot-id-2"]
}' \
https://capy.ai/api/v1/threads
```
If you don't pass `browserSnapshotIds`, the agent uses all snapshots marked as **default** for the project.
## Visibility
* **Public snapshots** (`isPrivate: false`) are visible to all project members
* **Private snapshots** (`isPrivate: true`) are only visible to their creator
* Snapshots marked **default** (`isDefault: true`) are automatically applied to all agent sessions unless overridden
## Quick start
### 1. Create a snapshot
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer capy_xxxx" \
-H "Content-Type: application/json" \
-d '{
"name": "Staging Auth",
"storageState": {
"cookies": [
{
"name": "session",
"value": "your-session-token",
"domain": "staging.yourapp.com",
"path": "/",
"expires": 1798761600,
"httpOnly": true,
"secure": true,
"sameSite": "Lax"
}
],
"origins": []
}
}' \
https://capy.ai/api/v1/projects/{projectId}/browser-snapshots
```
Domains are automatically extracted from your cookies — you don't need to
specify them separately.
### 2. Verify it was created
```bash theme={null}
curl -H "Authorization: Bearer capy_xxxx" \
https://capy.ai/api/v1/projects/{projectId}/browser-snapshots
```
### 3. Use it in a thread
```bash theme={null}
curl -X POST \
-H "Authorization: Bearer capy_xxxx" \
-H "Content-Type: application/json" \
-d '{
"projectId": "your-project-id",
"prompt": "Check the admin dashboard for errors",
"browserSnapshotIds": ["your-snapshot-id"]
}' \
https://capy.ai/api/v1/threads
```
The `storageState` format matches [Playwright's storage
state](https://playwright.dev/docs/api/class-browsercontext#browser-context-storage-state).
You can export state from Playwright and use it directly.
# Update browser snapshot
Source: https://docs.capy.ai/api-reference/browser-snapshots/update-snapshot
PATCH /v1/projects/{projectId}/browser-snapshots/{snapshotId}
Update browser snapshot metadata. Only the snapshot creator can change the isPrivate flag.
# List models
Source: https://docs.capy.ai/api-reference/models/list-models
GET /v1/models
List models available to the API.
# Models reference
Source: https://docs.capy.ai/api-reference/models/models-reference
All available model IDs for the Capy API, with provider details and pricing.
Use these model IDs when creating tasks or threads via the API. Model IDs follow [models.dev](https://models.dev) conventions.
## Available models
| Model ID | Name | Provider | Context | Reasoning | Captain eligible |
| ------------------------ | ----------------- | ------------- | ------- | --------- | ---------------- |
| `auto` | Auto | Capy | 262K | Always on | No |
| `claude-opus-4-6` | Claude Opus 4.6 | Anthropic | 1M | Adaptive | Yes |
| `claude-opus-4-5` | Claude Opus 4.5 | Anthropic | 200K | Binary | No |
| `claude-sonnet-4-6` | Claude Sonnet 4.6 | Anthropic | 1M | Adaptive | Yes |
| `claude-haiku-4-5` | Claude Haiku 4.5 | Anthropic | 200K | Binary | No |
| `gpt-5.6-sol` | GPT-5.6 Sol | OpenAI | 1M | Levels | Yes |
| `gpt-5.6-terra` | GPT-5.6 Terra | OpenAI | 1M | Levels | Yes |
| `gpt-5.6-luna` | GPT-5.6 Luna | OpenAI | 400K | Levels | No |
| `gpt-5.5` | GPT-5.5 | OpenAI | 1M | Levels | Yes |
| `gpt-5.5-pro` | GPT-5.5 Pro | OpenAI | 1M | Levels | Yes |
| `gpt-5.4` | GPT-5.4 | OpenAI | 1M | Always on | No |
| `gpt-5.4-mini` | GPT-5.4 Mini | OpenAI | 400K | Always on | No |
| `gpt-5.3-codex` | GPT-5.3 Codex | OpenAI | 400K | Always on | No |
| `gemini-3.1-pro-preview` | Gemini 3.1 Pro | Google | 1M | Levels | No |
| `gemini-3-flash-preview` | Gemini 3 Flash | Google | 1M | Levels | No |
| `grok-4-1-fast` | Grok 4.1 Fast | xAI | 2M | Binary | No |
| `glm-5` | GLM 5 | Fireworks | 200K | Always on | No |
| `glm-5-turbo` | GLM 5 Turbo | Z.AI | 203K | Always on | No |
| `glm-4.7` | GLM 4.7 | Google Vertex | 131K | Off | No |
| `kimi-k2.5` | Kimi K2.5 | Fireworks | 262K | Always on | No |
| `qwen3-coder` | Qwen 3 Coder | Google Vertex | 262K | Off | No |
## Example
```bash theme={null}
curl -X POST "https://capy.ai/api/v1/tasks" \
-H "Authorization: Bearer $CAPY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"projectId": "your-project-id",
"prompt": "Add a health check endpoint",
"model": "gemini-3-flash-preview",
"start": true
}'
```
# API Reference
Source: https://docs.capy.ai/api-reference/overview
Programmatic access to Capy's agent platform
## Authentication
All API requests require a Bearer token in the `Authorization` header:
```bash theme={null}
curl -H "Authorization: Bearer capy_xxxx" https://capy.ai/api/v1/projects
```
Generate API tokens at [capy.ai/settings/tokens](https://capy.ai/settings/tokens).
## Base URL
All endpoints are served from `https://capy.ai/api/v1/`.
## Pagination
List endpoints support cursor-based pagination:
* `limit` (query, default: 20, max: 100)
* `cursor` (query, opaque string from previous response)
Responses include `items`, `nextCursor` (null if no more), and `hasMore`.
## Errors
All errors return a consistent JSON structure:
```json theme={null}
{
"error": {
"code": "validation_error",
"message": "Request body validation failed",
"details": {}
}
}
```
| Status | Code | Description |
| ------ | ------------------ | ----------------------------------------- |
| 401 | `unauthorized` | Missing or invalid API token |
| 403 | `forbidden` | Token doesn't have access to the resource |
| 404 | `not_found` | Resource not found |
| 422 | `validation_error` | Invalid request parameters |
| 500 | `internal_error` | Unexpected server error |
## Task identifiers
Task IDs accept both formats:
* UUID: `550e8400-e29b-41d4-a716-446655440000`
* Identifier: `SCO-123` (project prefix + number)
# Get project
Source: https://docs.capy.ai/api-reference/projects/get-project
GET /v1/projects/{projectId}
Get a single project.
# List projects
Source: https://docs.capy.ai/api-reference/projects/list-projects
GET /v1/projects
List projects available to the API token.
# Session identity tokens
Source: https://docs.capy.ai/api-reference/sessions/overview
Verify that a request came from a real, active Capy session
## What session identity tokens are for
Session identity tokens let code running inside a Captain VM prove which Capy session it came from. Typical uses include enforcing per-session limits, binding external resources to a specific session, or accepting requests only from active sessions you expect.
Each token represents one Captain session. Capy signs the token, refreshes it while the session stays active, and invalidates it when the session ends.
Treat the token as an opaque bearer-style string. It is a JWT, but customers
should not parse or verify it locally.
## Where to read the token
You can get the current token in either place:
* Inside the Captain VM at `/etc/capy/session-token` (`chmod 600`)
* Via `GET /v1/threads/{threadId}/session-token`
If your code is already running inside the session VM, read the file directly instead of calling the API from inside the agent.
## Token lifecycle
* Minted when the session starts
* Expires 30 minutes after issuance
* Refreshed automatically in the background on each Captain VM heartbeat, typically about every 15 minutes before expiry
* Cleared when the session stops or is archived
As long as the session stays active, the token at `/etc/capy/session-token` and the value returned by `GET /v1/threads/{threadId}/session-token` stay current.
## Recommended verification pattern
When a service receives a session token from agent-controlled code:
1. Send the token to `POST /v1/sessions/verify`
2. Confirm the response has `valid: true`
3. Confirm `projectId` matches the project you expected
4. Optionally confirm `threadId` matches the specific session you expected
5. Trust the session identity only after those checks pass
Do not trust a session token based only on its shape, header, or decoded JWT
claims. Always call the verify endpoint before making authorization or routing
decisions.
## Security model
Capy signs session identity tokens with a Capy-managed key that is separate from internal infrastructure secrets. Customers must never attempt to verify the JWT cryptographically themselves.
`POST /v1/sessions/verify` is the only authoritative verification path. It confirms that the token matches a real session and that the session is still valid for the caller's project access.
Failure responses are intentionally opaque:
* `expired` means the token was valid but is no longer current
* `invalid` covers malformed tokens, signature failures, wrong issuer, wrong audience, wrong purpose, and other verification failures
This prevents the verify endpoint from becoming a useful oracle for attackers.
The caller of `POST /v1/sessions/verify` must have API access to the project
that owns the session. This prevents cross-project and cross-tenant
enumeration.
## End-to-end example
```bash Get token theme={null}
curl "$CAPY_API_BASE/v1/threads/$THREAD_ID/session-token" \
-H "Authorization: Bearer $CAPY_API_TOKEN"
```
```bash Verify token theme={null}
TOKEN=$(curl -s "$CAPY_API_BASE/v1/threads/$THREAD_ID/session-token" \
-H "Authorization: Bearer $CAPY_API_TOKEN" | jq -r '.token')
curl -X POST "$CAPY_API_BASE/v1/sessions/verify" \
-H "Authorization: Bearer $CAPY_API_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"token\":\"$TOKEN\"}"
```
A successful verify response looks like:
```json theme={null}
{
"valid": true,
"threadId": "jam_123",
"projectId": "proj_123",
"orgId": "org_123",
"userId": "user_123",
"instanceId": "vm_123",
"issuedAt": "2026-04-28T12:00:00.000Z",
"expiresAt": "2026-04-28T12:30:00.000Z"
}
```
# Verify session token
Source: https://docs.capy.ai/api-reference/sessions/verify-session
POST /v1/sessions/verify
Verify a session identity token issued for a captain session. The caller must have access to the project that owns the session so the endpoint cannot be used for cross-tenant enumeration. Failure responses are intentionally opaque: only `expired` is distinguished from `invalid`, and callers should always confirm the returned `projectId` matches the project they expect before trusting the result.
# Get Setup
Source: https://docs.capy.ai/api-reference/setup/get-setup
GET /v1/projects/{projectId}/setup
Get Setup used for future project runs. Setup contains VM size, three automatic repository scripts, opt-in Commands, terminals, previews, and pre/post tool hooks. Environment variables are configured separately.
# Setup
Source: https://docs.capy.ai/api-reference/setup/overview
Configure the project's dev environment
**Setup** is the editable project-level object used to prepare future agent runs in the **Dev environment** settings area. It defines:
* **VM size** — compute resources for runs
* **Initialize** — blocking setup for a fresh environment or snapshot build, after configured environment variables are injected
* **Update after checkout** — blocking maintenance after a later checkout from reused or snapshotted state, with environment variables available
* **Startup** — blocking service startup after setup is ready, with environment variables available
* **Commands** — named executable commands agents may run while working; they never run automatically during Setup
* **Hooks** — optional pre/post tool hooks
Read Setup with `GET /setup` and save it with `PATCH /setup`. The read response
reports which source is authoritative: `setup`, `legacy`, or `none`.
Saving applies the new Setup to future runs immediately; revision history and
rollback are managed internally.
**Snapshots** are separate: enabling or disabling cached VM state does not change Setup, and Setup can be saved or tested whether or not Snapshots are enabled.
Within each lifecycle phase, scripts for independent repositories execute in
parallel. A fresh environment runs **Initialize** and then **Startup**; it does
not immediately repeat **Update after checkout**. Avoid putting the same
expensive install in both phases unless it is required in both fresh and
post-checkout states.
On a reused environment, Capy selects the lifecycle per repository. A changed
Setup revision or a repository that has not been prepared runs **Initialize**
then **Startup**. A changed branch or resolved commit runs **Update after
checkout** then **Startup**. An unchanged repository runs **Startup** only.
```json theme={null}
{
"source": "setup",
"legacyHooks": {
"status": "ignored",
"repositories": ["acme/app"],
"checkComplete": true
},
"setup": {
"vmSize": "medium",
"repositories": [
{
"repository": "acme/app",
"branch": "main",
"scripts": {
"initialize": "pnpm install",
"updateAfterCheckout": "pnpm install --frozen-lockfile",
"startup": "nohup pnpm dev >/tmp/dev.log 2>&1 &"
},
"timeouts": {
"initialize": 900,
"updateAfterCheckout": 300,
"startup": 300
},
"commands": [
{
"name": "Test",
"command": "pnpm test"
}
]
}
],
"hooks": { "pre": { "bash_run": ["pnpm lint"] } }
}
}
```
## Migrating deprecated hooks
If `source` is `legacy`, `.capy/settings.json` hooks remain active until you
explicitly switch. Carry any needed scripts and tool hooks into Setup, then
update with `?replaceLegacyHooks=true`; afterward Setup is authoritative and
legacy hooks are ignored.
Do not include secret values, credentials, or environment variable values in
Setup. Configure environment variables separately in the UI; the public API
omits them and rejects these fields.
# Update Setup
Source: https://docs.capy.ai/api-reference/setup/update-setup
PATCH /v1/projects/{projectId}/setup
Save Setup for future project runs. The update becomes active immediately; secret and environment variable fields are not accepted.
# Get Snapshots
Source: https://docs.capy.ai/api-reference/snapshots/get-snapshots
GET /v1/projects/{projectId}/snapshots
Get whether optional Snapshots are enabled for the project. Snapshots are independent from Setup.
# Snapshots
Source: https://docs.capy.ai/api-reference/snapshots/overview
Enable or disable optional cached VM state
**Snapshots** optionally cache a project's VM state to speed later starts. They are independent from **Setup**: Setup can always be saved and tested with a fresh run whether Snapshots are enabled or disabled.
Environment Snapshots are currently available to select Enterprise customers.
[Contact us](https://cal.com/team/capy/enterprise) to request access for your
organization.
The public interface intentionally exposes one setting only:
```json theme={null}
{ "enabled": true }
```
Saving Setup is required before enabling Snapshots. Enabling can:
* Reuse a matching current artifact (`reusedSnapshot`)
* Start the first build immediately (`initialBuildId`)
* Queue the first build behind one already running (`queuedBehindActiveBuild`)
If the first build cannot be admitted or dispatched, Snapshots remain disabled.
Snapshot builds clone each repository at its configured base branch, run
Initialize, scrub platform-managed credentials and environment files, and then
capture the VM. Restored runs receive current environment variables and
credentials before Update after checkout and Startup are evaluated.
# Update Snapshots
Source: https://docs.capy.ai/api-reference/snapshots/update-snapshots
PATCH /v1/projects/{projectId}/snapshots
Enable or disable optional Snapshots. This does not gate saving or testing Setup.
# Create tag
Source: https://docs.capy.ai/api-reference/tags/create-tag
POST /v1/projects/{projectId}/tags
Create a reusable captain-thread tag for the project's organization. Reusing an existing tag name restores it and updates its color.
# List tags
Source: https://docs.capy.ai/api-reference/tags/list-tags
GET /v1/projects/{projectId}/tags
List reusable captain-thread tags defined for the project's organization.
# Set thread tags
Source: https://docs.capy.ai/api-reference/tags/set-thread-tags
PUT /v1/threads/{threadId}/tags
Replace the tags assigned to a captain thread. Every tag must already be defined for the project's organization.
# Create PR
Source: https://docs.capy.ai/api-reference/tasks/create-pr
POST /v1/tasks/{taskId}/pr
# Create task
Source: https://docs.capy.ai/api-reference/tasks/create-task
POST /v1/tasks
# Get diff
Source: https://docs.capy.ai/api-reference/tasks/get-diff
GET /v1/tasks/{taskId}/diff
Get the current diff for a task by UUID.
# Get task
Source: https://docs.capy.ai/api-reference/tasks/get-task
GET /v1/tasks/{taskId}
Get a task by UUID.
# List tasks
Source: https://docs.capy.ai/api-reference/tasks/list-tasks
GET /v1/tasks
# Send message
Source: https://docs.capy.ai/api-reference/tasks/send-message
POST /v1/tasks/{taskId}/message
# Start task
Source: https://docs.capy.ai/api-reference/tasks/start-task
POST /v1/tasks/{taskId}/start
# Stop task
Source: https://docs.capy.ai/api-reference/tasks/stop-task
POST /v1/tasks/{taskId}/stop
# Archive thread
Source: https://docs.capy.ai/api-reference/threads/archive-thread
POST /v1/threads/{threadId}/archive
Archive a captain thread. If the thread is actively running, the archive succeeds first and then the API attempts to stop the active run on a best-effort basis.
# Create and start thread
Source: https://docs.capy.ai/api-reference/threads/create-thread
POST /v1/threads
Create a new captain thread and immediately start execution, optionally assigning existing project tags.
# Get session token
Source: https://docs.capy.ai/api-reference/threads/get-session-token
GET /v1/threads/{threadId}/session-token
Fetch the current session identity token for a captain thread. The caller must have access to the project that owns the thread. The same token is also written inside the captain VM to `/etc/capy/session-token` with permissions `0600`, so code running inside the VM can read it locally. A `410` response means the session has already ended. A `422` response with code `session_not_ready` means the token has not been minted yet during initial bootstrap; retry with backoff.
# Get thread
Source: https://docs.capy.ai/api-reference/threads/get-thread
GET /v1/threads/{threadId}
Get a single captain thread.
# List messages
Source: https://docs.capy.ai/api-reference/threads/list-messages
GET /v1/threads/{threadId}/messages
List messages in a captain thread.
# List threads
Source: https://docs.capy.ai/api-reference/threads/list-threads
GET /v1/threads
List captain threads for a project.
# Send message
Source: https://docs.capy.ai/api-reference/threads/send-message
POST /v1/threads/{threadId}/message
Send a message to an existing thread.
# Stop thread
Source: https://docs.capy.ai/api-reference/threads/stop-thread
POST /v1/threads/{threadId}/stop
Stop an actively running captain thread.
# Unarchive thread
Source: https://docs.capy.ai/api-reference/threads/unarchive-thread
POST /v1/threads/{threadId}/unarchive
Unarchive a captain thread. This does not restart or resume execution.
# Automations
Source: https://docs.capy.ai/automations
Schedule recurring AI coding tasks in Capy — daily cleanups, weekly dependency updates, nightly builds, or anything you want an agent to do on repeat.
## Overview
Automations run tasks on a schedule - daily cleanups, weekly reports, nightly builds, or anything else you'd want an agent to do on repeat.
## Creating an automation
1. Open a project and go to the **Automations** tab
2. Click **New automation**
3. Configure the automation:
| Field | Description |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Name** | A descriptive name (e.g., "Weekly dependency updates") |
| **Prompt** | What the agent should do - same as a task prompt |
| **Trigger** | Schedule (cron), GitHub webhook (PR/review events), or Incoming webhook (external HTTP POST) |
| **Schedule** | Pick a preset (daily, weekly, custom) or write a cron expression |
| **Timezone** | Which timezone the schedule runs in |
| **Agent type** | Build (for coding) or Captain (for planning and delegation) |
| **Model** | Which AI model to use |
| **Base branch** | The branch to work from |
## Schedule options
You can use presets or write a custom cron expression:
| Preset | Schedule |
| ------ | -------------------------------------------------------------------- |
| Daily | Every day at a set time |
| Weekly | A specific day and time each week |
| Custom | Any valid cron expression (e.g., `0 9 * * 1-5` for weekdays at 9 AM) |
All schedules respect the timezone you set.
## How runs work
When a schedule triggers:
1. Capy creates a new task in the project
2. The agent runs with your prompt, on the base branch you configured
3. The run appears in the automation's **Run history**
Each run is a normal task - you can review the diff, create a PR, or send feedback just like any other task.
## Incoming webhooks
Every automation has a unique webhook URL. Use it to trigger the automation from any external service - CI/CD pipelines, monitoring alerts, Zapier, custom scripts, or anything that can make an HTTP POST.
### Triggering an automation
```bash theme={null}
curl -X POST https://capy.ai/api/webhooks/automations/trigger/{token} \
-H "Content-Type: application/json" \
-d '{"deployment_id": "abc123", "environment": "staging", "status": "failed"}'
```
The response includes the automation ID and run status:
```json theme={null}
{ "ok": true, "automationId": "...", "runStatus": "running" }
```
### Passing context
Any JSON fields in the request body are interpolated as template variables in your automation prompt. When the prompt uses no template variables or leaves any unresolved, the full payload is attached to the run as webhook context:
| Variable | Value |
| -------------------------- | ----------------------------- |
| `{{payload}}` | Full JSON body as a string |
| `{{payload.field}}` | Top-level field value |
| `{{payload.nested.field}}` | Nested field via dot notation |
| `{{trigger.timestamp}}` | ISO 8601 trigger time |
Example prompt:
```
A deployment to {{payload.environment}} just failed (ID: {{payload.deployment_id}}).
Check the logs and open a fix PR.
```
### HMAC signature verification
For additional security, configure a webhook secret on the automation. Sign your requests using HMAC-SHA256 and include the signature in the `X-Capy-Signature` header:
```bash theme={null}
SIGNATURE=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | sed 's/^.* //')
curl -X POST https://capy.ai/api/webhooks/automations/trigger/{token} \
-H "X-Capy-Signature: sha256=$SIGNATURE" \
-H "Content-Type: application/json" \
-d "$BODY"
```
Compatible with GitHub's webhook signature format (`X-Hub-Signature-256`).
### Rate limits
60 requests per minute per webhook URL. Requests over the limit receive a `429` response with a `Retry-After` header.
## Managing automations
* **Enable/disable** - toggle an automation without deleting it
* **Edit** - update the prompt, schedule, model, or branch
* **Webhook URL** - copy or rotate the webhook URL for any automation
* **Webhook secret** - configure optional HMAC signature verification
* **Run history** - view past runs with status and timestamps
* **Delete** - remove the automation entirely
## Example automations
**Daily lint fix**
```
Run `pnpm lint --fix` and commit any auto-fixable issues.
```
**Weekly dependency updates**
```
Check for outdated dependencies with `pnpm outdated`. Update patch and minor
versions, run tests, and summarize what changed.
```
**Nightly test suite**
```
Run the full test suite with `pnpm test`. If any tests fail, investigate the
failures and fix them. If all tests pass, report the results.
```
# Dev environment
Source: https://docs.capy.ai/configs/dev-environment
Configure how Capy prepares and maintains project VMs with Setup scripts, commands, environment variables, and snapshots.
Every Build and Captain run happens in an isolated VM. **Setup** defines how
Capy prepares and maintains that VM: which branches to use, which scripts run
automatically, which commands agents can invoke, and how much compute the VM
receives.
Configure it at **Settings → Project → Dev environment**.
Review runs use a separate, fixed environment: a Medium VM with only the pull
request checkout. Project Setup scripts, Commands, tool hooks, environment
variables, VM size, and Snapshots do not apply to Review.
## Let Captain manage it
You do not have to write Setup by hand. Captain inspects your repositories and
configures the environment for you.
Open **Settings → Project → Dev environment** and click **Set up with
Captain** — or tell Captain in any thread: *"Set up this project's dev
environment."*
Captain reads package manifests, lockfiles, READMEs, and agent instructions
for every attached repository. It chooses lifecycle scripts, useful
commands, and a fitting VM size, then saves Setup for future runs.
Captain starts a fresh validation run, exercises the configured environment,
and fixes Setup if anything fails.
Already have Setup? **Improve with Captain** reviews it against the current
state of your repositories.
Saved changes apply to future runs immediately. The **History** section records
changes made by people and Captain.
## Manual setup
Open a repository from **Setup & commands** to edit its base branch, lifecycle
scripts, per-script timeouts, and named Commands. Tool hooks and VM size are
configured on the main Dev environment page.
The equivalent Setup object looks like this:
```json theme={null}
{
"vmSize": "medium",
"repositories": [
{
"repository": "acme/app",
"branch": "main",
"scripts": {
"initialize": "pnpm install --frozen-lockfile",
"updateAfterCheckout": "pnpm install --frozen-lockfile",
"startup": "nohup pnpm dev >/tmp/dev.log 2>&1 &"
},
"timeouts": {
"initialize": 900,
"updateAfterCheckout": 300,
"startup": 300
},
"commands": [
{ "name": "Check", "command": "pnpm check" },
{ "name": "Test", "command": "pnpm test" }
]
}
]
}
```
Scripts are optional. Leave a script empty when that lifecycle phase has no
work to do.
## What Setup defines
| Section | What it controls |
| ---------------- | ----------------------------------------------------------- |
| **VM size** | Compute resources allocated to Build and Captain runs |
| **Repositories** | Per-repo base branch, lifecycle scripts, and named commands |
| **Tool hooks** | Optional commands that run before/after agent tool calls |
Environment variables and Snapshots are configured alongside Setup and are covered below.
## Mental model
| Concept | What it is |
| ------------------- | ----------------------------------------------------------------------- |
| **Setup** | The source of truth for branches, scripts, Commands, hooks, and VM size |
| **Run preparation** | The lifecycle Capy selects for each repository before the agent works |
| **Snapshot** | An optional cached VM produced from Setup to avoid repeating Initialize |
Setup is always authoritative. Snapshots cache its results; they do not replace
it. Run preparation reconciles whichever VM Capy obtains with the active Setup
and requested checkout.
## How a run becomes ready
Before the agent starts working, Capy:
1. Allocates a new VM, restores a snapshot, or resumes the thread's existing VM.
2. Loads shared project environment variables. When a VM is prepared for a run
you start, your [personal variables](#environment-variables) are layered
afterward and override shared variables with the same name.
3. Refreshes GitHub credentials and attaches each repository at the requested
branch and commit.
4. Selects the required Setup path for each repository based on the VM's saved
state, active Setup revision, and current checkout.
5. Runs the selected scripts. A Build agent becomes ready only after every
blocking script succeeds.
Shared environment variables and credentials are refreshed after restoring or
resuming cached VM state. A snapshot is never the authority for those values.
## Lifecycle scripts
Each repository has three automatic scripts:
| Script | Purpose | Default timeout |
| ------------------------- | --------------------------------------------------------------------- | --------------- |
| **Initialize** | Prepare a repository on a new VM, after cloning and environment setup | 15 min |
| **Update after checkout** | Maintain dependencies after a reused environment moves to new code | 5 min |
| **Startup** | Start services required for the run after repository preparation | 5 min |
The path is selected per repository:
| Environment state | Automatic scripts |
| -------------------------------------------------------- | ------------------------------- |
| New VM or repository not previously prepared | Initialize → Startup |
| Existing VM after Setup changes | Initialize → Startup |
| Existing VM after its requested branch or commit changes | Update after checkout → Startup |
| Existing VM with the same Setup revision and checkout | Startup |
| Snapshot build | Initialize, then capture |
| Run restored from a snapshot with a changed checkout | Update after checkout → Startup |
| Run restored from a snapshot with the captured checkout | Startup |
The same phase runs across independent repositories in parallel, but phases
remain ordered: all selected Initialize work finishes before Startup begins.
### Initialize
Use Initialize for work needed to make a clean repository usable:
* Install language runtimes, system packages, and global tools
* Authenticate a private package registry before the first dependency fetch
* Install project dependencies
* Compile native dependencies or generate required artifacts
Initialize runs from the repository directory with environment variables loaded.
It also runs while building a snapshot. It does not run again on every unchanged
resume.
```bash Initialize example theme={null}
node scripts/setup-npm-auth.js && pnpm install --frozen-lockfile
```
If dependency installation requires authentication, bootstrap credentials
explicitly before invoking the package manager. A package-manager `preinstall`
hook cannot authenticate the dependency fetch that must happen before the hook
is available.
### Update after checkout
Update after checkout is the maintenance phase. It repairs a prepared VM after
Capy checks out a different branch or commit. Keep it fast and safe to rerun:
* Synchronize dependencies from the current lockfile
* Regenerate code derived from the checkout
* Apply local, idempotent schema preparation needed by the development stack
* Refresh repository-scoped configuration
```bash Update after checkout example theme={null}
pnpm install --frozen-lockfile
```
Capy records the repository, requested branch, resolved commit, Setup revision,
and whether maintenance completed successfully. It skips Update after checkout
when those inputs still match the last successful preparation. A changed
checkout or an unsuccessful previous preparation causes it to run again.
Do not duplicate an expensive bootstrap in both Initialize and Update after
checkout unless both clean and reused environments genuinely require it.
### Startup
Startup runs after the selected preparation phase whenever the run needs its
services started. Use it for development servers, local databases, and other
processes that must be available while the agent works.
Startup is blocking, so the script itself must exit. Launch long-running
processes in the background and wait until they are ready:
```bash Startup example theme={null}
nohup pnpm dev >/tmp/dev.log 2>&1 &
for attempt in {1..30}; do
curl -fsS http://127.0.0.1:3000 >/dev/null && exit 0
sleep 1
done
exit 1
```
Startup runs again when an existing VM resumes. Make the script idempotent:
reuse a healthy service or replace stale processes instead of starting
duplicates.
### Execution and failures
Scripts run:
* From the corresponding repository directory
* In Bash with `set -e`
* With shared and applicable personal environment variables loaded
* With root access inside the isolated VM
* With configurable timeouts from 60 to 3600 seconds
An exit code other than zero, a timeout, or a transport failure fails the phase.
Build runs stop before the agent starts and show **Setup failed**. Captain
threads receive the failure and continue in a degraded environment so Captain
can inspect and repair Setup.
The VM status menu shows live and most recently recorded Setup steps, including
the repository, phase, duration, and result.
## Multiple repositories
All repositories in a run share one VM but have separate working directories.
Within a lifecycle phase, their scripts execute in parallel. The next phase
starts only after the current phase succeeds for every configured repository.
Avoid scripts that depend on another repository finishing first. If repositories
need the same global tool or system package, make the installation idempotent
and safe under concurrent execution. Repository-specific dependency work should
stay in that repository's script.
## Commands
Commands are named, opt-in actions agents can run while working — build, test, lint, typecheck. They never run automatically during Setup; agents invoke them when relevant.
| Name | Command |
| ---------- | ------------------ |
| Type check | `pnpm check-types` |
| Test | `pnpm vitest run` |
| Build | `pnpm build` |
Keep Commands executable and specific. Prose guidance ("always run lint before committing") belongs in [agent instructions](/configs/instructions), not Commands.
## Tool hooks
Setup can define commands that run before or after specific agent tools. Tool
hooks are useful for policy checks and lightweight automatic formatting:
```json theme={null}
{
"pre": {
"bash_run": ["echo 'About to run command'"]
},
"post": {
"edit": ["pnpm prettier --write ${file_path}"],
"write": ["pnpm prettier --write ${file_path}"]
}
}
```
Available tools: `bash_run`, `edit`, `multi_edit`, `write`, `read`, `glob`, `grep`.
## VM size
| Size | CPU | RAM | Disk | Cost/hour |
| ------ | -------- | ----- | ----- | --------- |
| Small | 2 cores | 4 GB | 20 GB | \$0.30 |
| Medium | 4 cores | 8 GB | 30 GB | \$0.60 |
| Large | 8 cores | 16 GB | 40 GB | \$1.20 |
| Ultra | 16 cores | 32 GB | 50 GB | \$2.40 |
| Hyper | 16 cores | 64 GB | 50 GB | \$3.00 |
Small is the default and works for most tasks. Use larger sizes for heavy builds, large test suites, or resource-intensive compilation. Changes apply to the next run.
## Environment variables
Configure variables at **Settings → Project → Environment variables**:
* **Shared** variables are available to every project run.
* **Personal** variables are available only in project runs you start. A
personal value overrides a shared variable with the same name.
Shared variables are available during snapshot builds. Personal variables are
not stored in snapshots; Capy injects them when preparing the VM for your run.
When a VM resumes, Capy refreshes shared project variables before lifecycle
scripts execute.
You can add key-value pairs directly or paste a full `.env` file.
Environment variables are available to the agent during task execution. Only
provide secrets you're comfortable sharing with the agent. Never put secret
values inside Setup scripts — reference them as variables instead.
## Snapshots
Environment Snapshots are currently available to select Enterprise customers.
[Contact us](https://cal.com/team/capy/enterprise) to request access for your
organization.
Snapshots cache a prepared VM so later runs can avoid repeating Initialize.
Enabling Snapshots requires a saved Setup.
A snapshot build:
1. Starts a clean VM at the configured size.
2. Injects shared project environment variables and GitHub credentials.
3. Clones each configured repository at its base branch.
4. Runs Initialize for each repository.
5. Removes platform-managed environment files, credentials, session tokens, and
transient runtime state before capturing the VM.
Capy removes platform-managed secret files before capture, but it cannot know
every path your scripts write. If Initialize writes a secret into another
file, that file can persist in the snapshot. Keep credentials in environment
variables and avoid writing secret values to disk.
When a run restores that snapshot, Capy injects current credentials and
environment variables, checks out the requested code, runs Update after checkout
only where the captured checkout no longer matches, and then runs Startup.
From the **Snapshots** section of the Dev environment page you can:
* **Enable Snapshots** — reuse a matching current snapshot, start the first
build immediately, or queue it behind a build already in progress.
* **Set the rebuild schedule** — snapshots refresh automatically every 1, 2, 4,
or 8 hours to keep dependencies current.
* **Trigger a build manually** — rebuild on demand after changing Setup.
* **Test a snapshot** — run the full capture, restore, and warm-up lifecycle
without promoting the result.
* **Inspect build history** — every build has logs and status (ready, building, stale, or failed).
Snapshot builds are triggered by enabling Snapshots, a manual rebuild, a
snapshot test, or the configured 1, 2, 4, or 8 hour refresh schedule. Saving
Setup does not block on a snapshot build; rebuild after a Setup change when you
want new runs to use the updated cached state.
| Status | Meaning |
| ------------ | -------------------------------------------------------------- |
| **Building** | A new snapshot is being prepared |
| **Ready** | A current snapshot is available for new runs |
| **Stale** | The cached artifact no longer matches the required environment |
| **Failed** | The latest build failed; inspect its step logs |
Snapshots are an optimization, never a requirement: Setup stays the source of truth, and if no current snapshot is available a run falls back to fresh provisioning with the same Setup.
## Troubleshooting
### Initialize fails
Inspect the failing repository and phase in the VM status menu, then open that
repository's Setup to inspect the configured command. For snapshot builds,
inspect the build logs. Common causes are missing package-manager authentication,
an interactive installer, an unavailable system package, or a timeout.
### Update after checkout fails
Run the command against the checked-out branch and current lockfile. Maintenance
must be safe to repeat after a failed attempt. Prefer incremental dependency
repair over deleting and rebuilding the entire environment.
### Startup times out
The Startup script must return. Background long-running processes, add a bounded
readiness check, and fail clearly when the service never becomes healthy. Also
make Startup idempotent so a resumed VM does not accumulate duplicate servers.
### A snapshot build fails
Open the build from **Settings → Project → Dev environment → Build history** and
inspect the first failed step. Fix Setup, use **Test snapshot** to exercise the
capture and restore lifecycle without promotion, then rebuild.
### Iterate with Captain
Click **Improve with Captain** or ask Captain to inspect the failure. Captain can
read Setup, the repositories, and build state, save a correction, and start a
fresh validation run.
## Migrating from `.capy/settings.json`
Repository hooks in `.capy/settings.json` are deprecated. Once any Setup exists
for the project, those hooks are ignored. Carry over any setup commands and tool
hooks you still need before saving; Captain detects and migrates them when it
configures the project.
The Dev environment page shows whether Setup, deprecated repository hooks, or
default behavior is currently authoritative.
## Manage via API
Everything on this page is also scriptable: read and save Setup with [`GET /setup`](/api-reference/setup/get-setup) and [`PATCH /setup`](/api-reference/setup/update-setup), and control snapshot state through the [Snapshots API](/api-reference/snapshots/overview). See the [Setup API overview](/api-reference/setup/overview) for the full object shape.
# Agent instructions
Source: https://docs.capy.ai/configs/instructions
Use AGENTS.md and markdown instruction files to teach Capy's Build, Captain, and Review agents your codebase conventions — what gets loaded, when, and what belongs where.
Agent instructions are markdown files committed to your repo that tell Capy how to work in your codebase: how to build and test, which conventions to follow, and what to avoid. Capy reads the same `AGENTS.md` files used by other coding agents, so if you already maintain them, Capy works with zero setup.
## How instructions are loaded
Capy loads instructions from four sources with different timing:
| Source | Files | When it's loaded |
| --------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Agent-specific instructions | `.capy/BUILD.md`, `.capy/CAPTAIN.md`, `.capy/REVIEW.md` | Session start |
| Root instructions | `AGENTS.md` or `CLAUDE.md` at the repo root | Session start |
| Nested instructions | `AGENTS.md` in any subdirectory | First time the agent touches a file in that directory's subtree |
| Glob rules | `.capy/rules/*.{md,mdc}`, `.cursor/rules/*.{md,mdc}` | Session start if `alwaysApply: true`, otherwise on first matching file touch |
### Agent-specific and root instructions
Each agent first looks for its own file:
* **Build** reads `.capy/BUILD.md`
* **Captain** reads `.capy/CAPTAIN.md`
* **Review** reads `.capy/REVIEW.md`
If the agent's `.capy/*.md` file is missing, it falls back to the repo root:
1. `AGENTS.md`
2. `CLAUDE.md`
The first file found wins, and the agent-specific file always takes precedence over the generic root file. Most repos only need a root `AGENTS.md`; add `.capy/*.md` files when one agent needs different guidance — for example, a `.capy/REVIEW.md` that tells Review which patterns not to flag.
### Nested AGENTS.md
Nested `AGENTS.md` discovery is rolling out now. If a nested file isn't being
picked up yet in your project, it will be shortly — root `AGENTS.md` behavior
is unaffected.
An `AGENTS.md` anywhere below the repo root is discovered automatically. It isn't loaded at session start — instead, it's injected into context the first time the agent reads, edits, searches, or lists a file inside that directory's subtree. A session that never enters `packages/api/` never pays the context cost of `packages/api/AGENTS.md`.
Behavior to know:
* **Lazy, then sticky.** Each nested file is injected at most once per session, on first contact with its subtree.
* **Deeper wins.** When instructions conflict, a more deeply nested `AGENTS.md` takes precedence over shallower ones (and nested files add to, not replace, the root file).
* **File tools only.** Injection is triggered by file-level operations — reading, editing, searching, and listing files. Shell commands do not trigger nested injection, so a repo-wide grep from the terminal won't pull in every nested file at once.
* **Plain markdown.** The whole file is treated as instructions. Frontmatter is not parsed — if you need globs or `alwaysApply`, use a [glob rule](#glob-rules) instead.
Limits:
* Up to 50 nested `AGENTS.md` files per repo (alphabetical by path beyond that)
* 32K characters per file; longer files are truncated with a visible marker
* Files under dot-directories (`.agents/`, `.cursor/`, `.github/`, ...) are excluded
### Glob rules
Capy reads Cursor-style rules from `.capy/rules/` and `.cursor/rules/` (`.md` or `.mdc` files). YAML frontmatter controls when each rule loads — a rule needs `alwaysApply: true` or at least one `globs` pattern to be injected:
```markdown theme={null}
---
description: SQL migration conventions
globs:
- "**/*.sql"
alwaysApply: false
---
- Every migration must be reversible
- Never drop columns without an explicit approval comment
```
* `alwaysApply: true` — loaded at session start
* `globs` — injected the first time the agent touches a matching file
* Rules are injected with their file path attached, and each rule is injected at most once per session
Use `.capy/rules/` for Capy-native rules; `.cursor/rules/` is read natively so existing Cursor setups work unchanged.
### Skills
For deep, on-demand workflows — deploy runbooks, codegen procedures, large reference material — use [skills](/configs/skills) instead of instruction files. Skills advertise only their name and description until an agent decides to load one, so they cost almost nothing when unused. Instruction files answer "how should you always behave here?"; skills answer "how do I do this specific thing?".
## What goes where
The failure mode to avoid is one giant root file that every session pays for. Match each piece of guidance to the narrowest mechanism that still reaches it:
| Guidance | Put it in | Why |
| -------------------------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
| Stack summary, build/test/format commands, PR conventions, hard rules | Root `AGENTS.md` | Every session needs it |
| Per-package architecture, domain rules, local commands | Nested `AGENTS.md` in that package | Only loaded when working there |
| File-type conventions that cut across directories (`**/*.sql`, `**/*.tsx`) | Glob rule | Directory-scoped files can't express "all SQL files" |
| Multi-step workflows, long reference docs | [Skill](/configs/skills) | Loaded on demand, keeps always-on context lean |
**Root `AGENTS.md`** carries cross-cutting truths: what the project is, how to install/build/test/lint, commit and PR conventions, and non-negotiable rules ("always use pnpm", "never commit generated files"). Keep it lean — a bloated root file taxes every request in every session, and long instruction files dilute the agent's attention on the rules that matter.
**Nested `AGENTS.md`** carries what's true only inside a subtree. In a monorepo, keep the top-level file general and add a specific `AGENTS.md` per major subproject — `packages/api/AGENTS.md` for API conventions, `packages/web/AGENTS.md` for frontend rules. This is the same layout Amp and other agents recommend, so one set of files serves every tool.
**Glob rules** carry concerns that follow a file type rather than a directory: design-token rules for every `.tsx` file, migration rules for every `.sql` file. If the concern maps cleanly to one directory, prefer a nested `AGENTS.md` there instead.
### Anti-patterns
* **Duplicating a rule in multiple files.** State it once in the narrowest scope that covers it. Duplicates drift, and the agent has to reconcile conflicting copies.
* **Restating what the code already says.** Don't enumerate exports, list every directory, or paraphrase type signatures — the agent reads code. Document what it can't infer: intent, invariants, and commands.
* **Prompt-sized essays.** Ten sharp bullets outperform three pages of prose. "Use pnpm, not npm" beats "please make sure to use the correct package manager for this project".
* **Secrets or credentials.** Instruction files are committed to the repo and injected into model context. Never put tokens, passwords, or internal URLs that shouldn't leak into them.
* **Per-file trivia.** "This function retries three times because the upstream API flakes" belongs in a code comment next to the function, not in an instruction file.
## Examples
### A lean root AGENTS.md
```markdown theme={null}
# AGENTS.md
Acme is a TypeScript monorepo: `packages/api` (Fastify + Postgres),
`packages/web` (React + Vite), `packages/shared` (types and utils).
## Commands
- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test` (single package: `pnpm --filter @acme/api test`)
- Lint + format: `pnpm check` — run before finishing any task
## Rules
- Always use pnpm, never npm or yarn
- No `any` types; fix type errors instead of suppressing them
- New env vars must be added to `.env.example` and `packages/shared/src/env.ts`
- PR titles follow `type(scope): description` (e.g. `fix(api): handle null user`)
```
### A nested packages/api/AGENTS.md
```markdown theme={null}
# API package
Fastify server with route handlers in `src/routes/`, business logic in
`src/services/`, and data access in `src/db/`.
- Route handlers validate input with zod schemas from `src/schemas/` and
stay thin — logic lives in services
- All queries go through the repository layer in `src/db/`; never import
the client directly in a route or service
- Every table uses soft deletes (`deleted_at`); filter it in every query
- Integration tests live in `src/__tests__/` and run against the Docker
Postgres from `pnpm db:test`
```
### A glob rule
```markdown theme={null}
---
description: Design token rules for React components
globs:
- "**/*.tsx"
---
- Use tokens from `packages/web/src/styles/tokens.css` — never raw hex
colors or arbitrary Tailwind values
- Spacing comes from the `--space-*` scale; font sizes from `text-sm`
through `text-2xl` only
```
## Migrating from other tools
* **From Claude Code** — nothing required: Capy reads root `CLAUDE.md` as a fallback. To standardize on `AGENTS.md` while keeping Claude Code working: `mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md`
* **From Cursor** — keep `.cursor/rules/` where it is; Capy reads it natively, including `globs` and `alwaysApply` frontmatter
* **From other agents using AGENTS.md** (Amp, Codex, Devin, ...) — nothing required; root and nested `AGENTS.md` files work as-is
Changes to instruction files apply to the next agent session.
# VM sandbox
Source: https://docs.capy.ai/configs/runtime
What's inside Capy's task VMs — Ubuntu, preinstalled language runtimes and tools, and full Docker Engine and Compose support for containerized testing.
Each run executes in an isolated Ubuntu VM with Python, Node.js, TypeScript, Rust, Go, Java, Docker, and common developer tools preinstalled. The agent has full access: it edits files, runs commands, installs packages, and commits code without touching your machine.
How the VM is prepared — compute size, setup scripts, environment variables, and snapshots — is configured per project in [Dev environment](/configs/dev-environment).
## Docker in sandboxes
Capy VMs include Docker Engine and Docker Compose, so tasks can build images, run service dependencies, and test containerized apps directly inside the sandbox.
Use the standard Docker commands:
```bash theme={null}
docker info
docker run --rm hello-world
docker compose up -d
```
Nested containers support the networking patterns most app test flows need:
* Pulling images and reaching the public internet from containers
* User-defined bridge networks with container/service-name DNS
* Docker Compose default networks
* Published ports that are reachable from the Capy VM, such as `curl http://127.0.0.1:3000`
For example, a Compose stack can expose a web service to the VM and let another service reach it by name:
```yaml theme={null}
services:
web:
image: nginx:alpine
ports:
- "8080:80"
probe:
image: busybox:1.37
command: sh -lc "wget -qO- http://web && sleep 600"
```
```bash theme={null}
docker compose up -d
curl http://127.0.0.1:8080
```
Sandbox image changes apply to new VMs. If an existing task was created before a capability rolled out, start a new run to pick up the updated image.
# Skills Configuration
Source: https://docs.capy.ai/configs/skills
Create reusable skill packages that teach Capy agents specific workflows — store them in your repo and reference them from task prompts for consistent results.
Skills are reusable instruction packages that teach agents specific workflows.
Store them in your repo at:
* `.agents/skills/` (recommended)
* `.claude/skills/` (also supported)
Each skill is a directory with a required `SKILL.md`, plus optional supporting files:
* `SKILL.md`: required instructions
* `references/`, `scripts/`, `assets/`: optional
Agents get a list of available skills and selectively load relevant ones based on the task.
## Example skill
`SKILL.md`:
```markdown theme={null}
# Deploy skill
Deploy the application to staging or production.
## When to use
- User asks to deploy, release, or push to staging/production
## Steps
1. Run `scripts/deploy.sh `
2. Verify deployment at the environment URL
3. Report success or failure
## When not to use
- For local development or testing
```
You can create skills manually or ask Build to scaffold them.
# GitHub Integration
Source: https://docs.capy.ai/integrations/github
Install the Capy GitHub App to connect repositories, manage branches automatically, and create pull requests from AI-generated code changes.
## Connecting GitHub
Install the Capy GitHub App from the dashboard by clicking **Connect GitHub**, then choose which repositories to grant access to. You can update repo access anytime in your GitHub settings.
## Working with repos
Repositories are cloned automatically when a task starts. Capy creates a branch (`capy/-`) for each task - your main branch stays clean. When you're happy with the changes, click **Create PR** in the diff view and merge on GitHub.
You can set the default branch for each repo (e.g., `main`, `develop`) from the dashboard.
## Permissions
| Permission | Purpose |
| ------------- | ---------------- |
| Contents | Read/write code |
| Pull requests | Create PRs |
| Issues | Read for context |
| Metadata | Repo info |
## Troubleshooting
Check that the GitHub App is installed and you've selected the repo in your
GitHub settings. You may need to re-authorize if you recently changed org
permissions.
Make sure you're on a working branch (`capy/*`). Capy never pushes directly
to your default branch.
# Linear Integration
Source: https://docs.capy.ai/integrations/linear
Connect Linear to Capy to delegate issues, route work by team mappings, and run tasks with configurable default project and branch behavior.
## Overview
Connect Linear to Capy so your team can delegate issues directly from Linear and keep execution tied to the right project and repository defaults in Capy.
## Connecting Linear
Go to [Settings → Connections →
Linear](https://capy.ai/settings/org/connections/linear). You need to be an
org admin.
Click **Install** and authorize the Linear workspace. This connects one
Linear workspace to your Capy organization.
Choose a default project and configure branch defaults so Linear-origin
tasks run with consistent routing and base branches.
## Team and project mapping behavior
Use **Team mappings** in Linear settings to route work automatically:
1. Map a Linear team to a Capy project
2. Delegated issues from that team are created in the mapped project
3. If no team mapping exists, Capy falls back to your **Default project**
This keeps teams aligned to the right codebase without manual project selection on every issue.
## Default project and branch behavior
* **Default project**: used when a Linear team does not have an explicit mapping
* **Default branches**: set per repository for Linear-origin captain runs
* If no custom branch default is set for a repo, Capy uses the repository default branch
You can update these values anytime in [Settings → Connections → Linear](https://capy.ai/settings/org/connections/linear).
## What agents can do via Linear
When work is delegated from Linear, Capy can:
* Create and run tasks with Linear issue context
* Apply team-to-project mappings automatically
* Use configured default branches for repository work
* Use your Linear integration behavior settings (auto start, auto-create PR)
* Continue task execution from the same Linear workflow
## Permissions and scope notes
* Linear is connected at the organization level in Capy
* Installation and reconnect actions require org admin access
* Team mappings, defaults, and behavior settings are shared org configuration
* Capy uses the authorized Linear workspace for delegation and context
## Troubleshooting
Make sure an org admin completed the install flow in Settings → Connections
→ Linear. If credentials changed, reinstall the connection.
Check Team mappings first. If a team has no mapping, Capy uses the default
project.
Review Default branches in Linear settings. If a repo-specific branch isn't
set, Capy falls back to that repository's default branch.
Only org admins can install, reinstall, or disconnect the org-level Linear
workspace connection.
# MCP servers
Source: https://docs.capy.ai/integrations/mcp
Connect Capy to external tools and data through remote HTTP or local stdio Model Context Protocol servers.
## Overview
Model Context Protocol (MCP) servers give Capy access to tools provided by
external services and local processes. Once a server is connected, Captain,
Build, and Review agents can discover and use its tools while working.
Configure MCP servers from **Settings → MCP servers** in a project.
## Add an MCP server
Select a server from the marketplace, or click **New MCP server** to add a
custom server.
Save the server as personal, project, or org-wide. This controls who can see
and use the server configuration.
For a remote server, enter its full HTTP endpoint. For a local server, enter
the stdio command, arguments, working directory, and environment variables.
If an HTTP server requires OAuth, open the saved server and click
**Connect**. Servers that do not require authentication are ready after Capy
discovers their tools.
Each person can disable a configured server without removing it for everyone
else.
## Availability
| Availability | Who can use it |
| ------------ | ------------------------------------------------- |
| **Personal** | Only you, in the current project |
| **Project** | Everyone with access to the current project |
| **Org-wide** | Everyone in the organization, across all projects |
Project and org-wide servers can have either personal or shared OAuth
connections:
* **Personal connection** — credentials belong to one Capy user. When both
personal and shared connections exist, Capy uses the current user’s personal
connection.
* **Shared connection** — credentials are available to everyone who can use the
server. Only org admins can connect or disconnect shared credentials.
## Remote HTTP servers
Choose **HTTP** and enter the server’s full MCP endpoint. Capy attempts
Streamable HTTP first and falls back to the legacy SSE transport when the server
does not support Streamable HTTP.
For servers that use a static token or API key, add the required HTTP header.
Store sensitive values in project environment variables and reference the
variable from the header instead of entering a secret directly in the server
configuration.
```text theme={null}
Server key: internal-tools
URL: https://tools.example.com/mcp
Header: Authorization
Value: $INTERNAL_TOOLS_TOKEN
```
## Local stdio servers
Choose **Stdio** for an MCP server that runs as a process inside the agent VM.
Configure its command, arguments, working directory, and environment variables.
```text theme={null}
Server key: local-docs
Command: npx
Arguments: -y, @example/docs-mcp
```
The command and its dependencies must be available in the project’s VM. Add
installation steps to the project’s [Dev environment](/configs/dev-environment)
when needed.
Stdio servers do not use the browser OAuth flow. Provide any required
credentials through environment variables.
## Transport and OAuth support
| Capability | Support |
| ---------------------------------- | ------------------------------------------------ |
| Streamable HTTP | Supported and preferred for remote servers |
| SSE | Supported as a fallback for older remote servers |
| Stdio | Supported inside the agent VM |
| MCP OAuth 2025-06-18 | Supported |
| PKCE | Supported with `S256` |
| Dynamic Client Registration | Supported |
| OAuth Client ID Metadata Documents | Supported when advertised |
For protected HTTP servers, Capy supports the MCP OAuth authorization flow from
the 2025-06-18 specification, including:
* OAuth 2.1 authorization code flow with PKCE
* OAuth Protected Resource Metadata and Authorization Server Metadata discovery
* OAuth resource indicators in authorization and token requests
* Dynamic Client Registration
* Public clients with `token_endpoint_auth_method: none`
* Access-token refresh when the server issues a refresh token
Capy can also use OAuth Client ID Metadata Documents when an authorization
server advertises support.
## OAuth redirect URIs
Authorization servers that enforce a redirect URI allowlist must register the
following callback URI:
```text theme={null}
https://capy.ai/api/mcp/oauth/callback
```
## How agents use MCP tools
Before calling a tool, Capy:
1. Connects to the configured server and lists its available tools.
2. Reads the selected tool’s input schema.
3. Calls the tool with schema-valid arguments.
If a server reports that authentication is required, Capy pauses the affected
action and asks you to connect or reconnect the server.
Connect only servers you trust, and keep API keys or static tokens in project
environment variables rather than source control.
# Slack Integration
Source: https://docs.capy.ai/integrations/slack
Connect Slack to Capy to create coding tasks directly from messages, sync conversation threads, and give agents full context from your workspace.
## Overview
Connect Slack to create tasks directly from messages, sync conversation threads, and let agents read and search your Slack workspace for context.
## Installing the Slack app
Go to [Settings → Connections →
Slack](https://capy.ai/settings/org/connections/slack). You need to be an
org admin.
Click **Install** and authorize Capy in your Slack workspace. This connects
the workspace for your entire organization.
Choose a default project for Slack-originated tasks. This is used for DMs
and channels without an explicit mapping.
## Creating tasks from Slack
Mention **@Capy** in any channel where the app is installed. Capy creates a task from your message and responds in a thread. You can continue the conversation in that thread - messages are synced to the task.
You can also share images and files in the message. Capy will pick them up as context for the task.
## Thread controls
Use thread controls to manage what Capy sees and when it responds inside a Slack thread.
### Aside messages
Prefix a message with `aside` to exclude it from Capy's processing entirely.
* Capy won't see the message
* Capy won't respond to it
* It won't appear in the agent's context when Capy reads thread history
This works with `aside ...` and `@Capy aside ...`. The check is case-insensitive, and `aside` must be at the start of the message.
Use `aside` when you want to talk with teammates in a Capy thread without the
agent picking those messages up.
### Mute and unmute
Mute a thread to stop Capy from responding to regular thread replies.
* Type `mute` or `@Capy mute` in the thread to mute it
* Type `unmute` or `@Capy unmute` to turn replies back on
* When muted, Capy ignores regular thread replies
* Direct `@Capy` mentions still go through
* DMs still work
Capy confirms the change with an ephemeral message visible only to you:
* `Thread muted - Capy will ignore messages here unless directly mentioned with @Capy.`
* `Thread unmuted - Capy will respond to messages in this thread again.`
If the thread is already in the requested state, Capy does nothing. Mute state is stored per thread.
### Archive
Archive a thread to stop Capy and close the session.
* Type `archive` or `@Capy archive` in the thread
* Capy stops any running work and archives the session
* Later messages and direct mentions in the archived Slack thread are ignored and do not unarchive it
* Type `unarchive` or `@Capy unarchive` to explicitly reopen the session
* To keep the archived session closed, start a new `@Capy` mention outside the old thread
Capy confirms with: `Thread archived - Capy has stopped and this session is closed.`
When explicitly reopened, Capy confirms with: `Thread unarchived - Capy will respond to messages here again.`
### Stop
Stop the current run without archiving the thread.
* Type `stop` or `@Capy stop` in the thread
* Capy stops the current run and keeps the thread active
* Send another message in the thread when you want Capy to start again
Capy confirms with `Capy stopped the current run.` If no run is active, it replies with `Capy is not currently running.`
## Channel mappings
Map specific Slack channels to Capy projects so tasks created from those channels are automatically assigned to the right project.
1. Go to [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack)
2. Scroll to **Channel mappings**
3. Select a channel and a project, then click **Save**
Channels without a mapping fall back to the default project. DMs also use the default project.
## Default branch
Set a **default branch** in the Slack settings to control which branch Capy uses as the base for tasks started from Slack. If not set, the project's default branch is used.
## Message verbosity
Control how many messages Capy posts in Slack threads.
* **All messages** (default) — Capy posts every response as it works
* **Final message only** — Capy only posts the final response when the task completes
Set this in [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack) under **Message verbosity**. Individual threads can override this with the `verbose` flag.
## Message flags
Control task behavior by adding flags to your `@Capy` message. Flags are stripped from the prompt before processing.
### Bang flags
Prefix a flag with `!` to toggle a behavior. Bang flags can appear anywhere in the message.
| Flag | Description |
| ------- | ------------------------------------------------------ |
| `!fast` | Use fast model variants for quicker, cheaper responses |
Reasoning levels should be configured with `reasoning=...`. The shorthand bang flags `!off`, `!low`, `!medium`, `!high`, and `!xhigh` are still supported for backcompat and quick use.
```text theme={null}
@Capy !fast fix the typo in README.md
@Capy reasoning=high refactor the auth middleware to use dependency injection
@Capy !xhigh audit the query planner changes
```
### Directives
Use `key=value` pairs to configure task settings. Directives can appear anywhere in the message.
| Flag | Values | Description |
| ----------- | --------------------------------------- | ------------------------------------------------------- |
| `project` | project name or ID | Start the thread in a specific Capy project |
| `verbose` | `true` / `false` | Override the org-wide verbosity setting for this thread |
| `model` | model name | Use a specific model (e.g. `opus`, `sonnet`, `haiku`) |
| `reasoning` | `off`, `low`, `medium`, `high`, `xhigh` | Set reasoning effort |
| `channel` | `#channel` / name | Start the Capy thread in another Slack channel |
```text theme={null}
@Capy project="Payments platform" fix the deploy script
@Capy model=opus reasoning=xhigh investigate the production incident
@Capy channel=at-capy investigate this bug report
```
`project` and `channel` only apply to new Slack starts. Project names are matched case-insensitively, with a safe fuzzy match when there is one clear result. If the match is uncertain, Capy asks you to choose from the projects you can access. Capy posts a new thread in the target channel with source attribution when `channel` is present.
Repository and branch instructions are ordinary task context, not routing flags. Write them naturally in the request—for example, `use the backend repository on branch=staging`—and the agent will handle them inside the selected project.
#### Verbosity
The `verbose` flag controls how many messages Capy posts in the Slack thread:
* `verbose=true` (or `on`, `yes`, `all`) — post every assistant message (default)
* `verbose=false` (or `off`, `no`) — only post the final response
You can set the default for your entire workspace in [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack) under **Message verbosity**. The per-message `verbose` flag overrides the org-wide setting.
#### Model aliases
The `model` flag accepts short aliases:
| Alias | Model |
| --------- | ----------------- |
| `opus` | Claude Opus 4.8 |
| `sonnet` | Claude Sonnet 4.6 |
| `haiku` | Claude Haiku 4.5 |
| `gpt` | GPT 5.5 |
| `gpt-5.6` | GPT-5.6 Sol |
| `sol` | GPT-5.6 Sol |
| `terra` | GPT-5.6 Terra |
| `luna` | GPT-5.6 Luna |
| `codex` | GPT 5.3 Codex |
| `gemini` | Gemini 3.1 Pro |
| `grok` | Grok 4.1 Fast |
| `kimi` | Kimi K2.7 Code |
| `qwen` | Qwen3 Coder |
| `glm` | GLM 5.2 |
`model=gpt-5.6` and `model=sol` select GPT-5.6 Sol. Full model IDs also work, including `model=gpt-5.6-terra` and `model=gpt-5.6-luna`.
### Combining flags
Flags can be mixed freely:
```text theme={null}
@Capy !fast fix the auth redirect loop
@Capy project="Payments platform" model=opus reasoning=high refactor the middleware
@Capy !fast verbose=false run a quick code review on branch=staging
@Capy project=payments reasoning=xhigh use the API repository and add rate limiting to the /users endpoint
```
## Personal connection
Each team member can link their own Slack account for richer functionality. This lets Capy:
* Search messages on your behalf
* Read private channels you're a member of
* Read your DMs (if you grant permission)
To link your account:
1. Go to [Settings → Connections → Slack](https://capy.ai/settings/org/connections/slack)
2. Under **Personal connection**, click **Link account**
3. Authorize Capy with your Slack user token
### Permission levels
| Permission | What it enables | Default |
| ------------------------ | ---------------------------------------------------- | --------- |
| Search & public channels | Read and search messages in public channels | Always on |
| Private channels | Read messages in private channels you're a member of | Off |
| Direct messages | Read your DMs and group DMs | Off |
You can toggle these permissions anytime. Changes require reconnecting to Slack.
If an agent needs a permission you haven't granted, it will post a prompt in the Slack thread asking you to upgrade. You can disable these prompts in the settings.
## What agents can do with Slack
When a task is started from Slack, agents have access to these capabilities:
* **Read messages** from any channel or thread (respects your permission level)
* **Search messages** across the workspace
* **Send messages** to channels or threads, with optional file attachments
* **React to messages** with emoji
* **List channels** to find the right conversation
Agents always respond in the Slack thread that started the task. They can also send messages to other channels when needed.
## Permissions
| Permission | Purpose |
| ------------------------------- | ---------------------------- |
| Chat:write | Post messages and replies |
| Channels:read | List and read channels |
| Reactions:read, Reactions:write | Sync and add emoji reactions |
| Files:write | Upload file attachments |
| Users:read | Resolve display names |
## Troubleshooting
Make sure the Capy app is installed in the channel. Type `/invite @Capy` to
add it. Also verify the Slack workspace is connected in Settings →
Connections → Slack.
Check your channel mappings. If the channel isn't mapped, tasks use the
default project. Set one in Settings → Connections → Slack.
The thread may be muted. Type `unmute` or `@Capy unmute` in the thread to
re-enable normal replies. Direct `@Capy` mentions still work while a thread
is muted.
That's expected. Messages starting with `aside` are excluded from Capy's
processing and do not appear in the thread context the agent reads later.
The user who started the task needs to link their personal Slack account and
enable private channel access. Go to Settings → Connections → Slack →
Personal connection.
Disable them in Settings → Connections → Slack → Permissions → Upgrade
notifications.
# Vercel Preview Deployments
Source: https://docs.capy.ai/integrations/vercel
Capy detects Vercel preview deployments from PR comments and surfaces live previews in the dashboard alongside code diffs — no webhooks or API keys needed.
## Overview
Capy detects Vercel preview deployments automatically from PR comments and surfaces them in the dashboard. Review code diffs and live previews side by side, no webhooks or API keys needed.
## How it works
When Vercel deploys a preview from a PR branch, it posts a comment with the preview URL. Capy scans PR comments for URLs with `preview` in the hostname and surfaces the first match in the PR toolbar.
Link your Vercel project to GitHub. When Vercel deploys previews on PRs,
Capy detects them automatically.
An agent works on your task and opens a PR. Vercel triggers a preview
deployment from the branch.
Capy detects the preview URL from the PR discussion. Click **Open preview
link** in the PR view to see the live deployment.
No configuration is required. If Vercel is connected to your GitHub repo, it just works.
## In-VM previews
For previewing during a task *before* a PR exists, start your service in the VM.
Capy discovers listening HTTP services automatically and exposes them from the
Desktop services menu.
## Full workflow
1. Start an in-VM service so the agent validates changes while coding
2. Agent opens a PR when done
3. Vercel deploys a preview from the branch
4. You review code and the live deployment from Capy's PR view
## Limitations
* Only the first matching preview URL per PR is surfaced
* Capy does not trigger Vercel deployments — your existing Vercel setup handles the deploy pipeline
* Preview detection relies on Vercel's PR comments; if comments are disabled, previews won't appear
## FAQ
No. If Vercel is connected to your GitHub repo, Capy detects preview URLs
from PR comments automatically. There's nothing to install or configure.
No. Capy reads preview URLs from PR comments but doesn't trigger
deployments. Your existing Vercel setup handles the deploy pipeline.
Currently, Capy surfaces the first matching preview URL from PR comments.
The Desktop services menu discovers multiple in-VM HTTP services
automatically.
# Pricing, Plans, and Usage
Source: https://docs.capy.ai/pricing
Capy Pro tiers from $20 to $2,000 per month, yearly discount, overage, auto-reload, and how billing works.
## Plans
Every plan gives you monthly credits to spend on Capy work. Pick a tier that matches your team's monthly usage, and pay yearly for a flat 20% off.
| Plan | Monthly | Yearly (per month) | Credits per month |
| -------------------- | ------- | ------------------ | ----------------- |
| **Capy Pro** | \$20 | \$16 | \$20 |
| **Capy Pro \$100** | \$100 | \$80 | \$105 |
| **Capy Pro \$500** | \$500 | \$400 | \$550 |
| **Capy Pro \$2,000** | \$2,000 | \$1,600 | \$2,300 |
| **Enterprise** | Custom | Custom | Custom |
Higher tiers come with bonus credits (up to 15%). Yearly billing applies a flat 20% discount on any tier.
## Credits
Credits are the unit of work in Capy. You spend them on:
* AI usage (input and output tokens for the model running your task)
* VM runtime (the isolated Ubuntu VM where Build does its work)
* Auxiliary services like the Review Agent
Credits are **org-level**. Whatever tier your org is on, every member draws from the same shared balance, and the org card covers any overage.
## Overage
If you push past your monthly credits, top-ups buy more credits at **\$1 = \$1 of credits**.
* **Auto-reload** keeps long-running tasks alive when your balance hits zero by buying more credits automatically.
* **Monthly spend cap** is an org-wide hard ceiling. Capy pauses before it would cross the limit you set, even with auto-reload on.
* You can disable overage entirely. Capy will simply stop when the monthly credits run out.
## Usage costs
Capy charges based on actual usage, billed in credits.
### What you pay for
**AI Usage (LLM)**
* Input tokens: text sent to the model (prompts, file contents, context)
* Output tokens: text the model generates (responses, code)
* More capable models cost more per token
* Pricing is based on the provider's API rates
**VM Runtime**
Each task run executes in an isolated Ubuntu VM. You're charged based on the VM size and how long it runs.
| Size | CPU | RAM | Cost/Hour |
| ------ | -------- | ----- | --------- |
| Small | 2 cores | 4 GB | \$0.30 |
| Medium | 4 cores | 8 GB | \$0.60 |
| Large | 8 cores | 16 GB | \$1.20 |
| Ultra | 16 cores | 32 GB | \$2.40 |
| Hyper | 16 cores | 64 GB | \$3.00 |
### Typical usage
| Task | Approximate Cost |
| ---------------------- | ---------------- |
| Quick code edit | \$0.05–\$0.20 |
| Feature implementation | \$0.50–\$2.00 |
| Large refactor | \$2.00–\$10.00 |
Actual costs depend on model choice, task complexity, and codebase size.
## Enterprise
For teams that need more than \$2,000/month in credits, custom contracts, or extra controls:
* Custom credit quota
* Unlimited concurrent sessions
* BYOK keys
* SSO and audit logging
* Dedicated support and 99.9% uptime SLA
[Contact us →](https://cal.com/team/capy/enterprise)
## FAQ
Active tasks pause. You can add more credits manually, turn on auto-reload, or wait for your monthly refresh.
Yes, any credits you manually add roll over. Monthly subscription credits
refresh each month.
Yes. Upgrade or downgrade any time from the billing page in your settings.
Changes apply at the start of the next billing cycle.
Yearly plans bill upfront for 12 months at a flat 20% discount. Credits still
refresh monthly.
Claude Haiku and Gemini Flash are the most economical. Use them for simpler tasks.
# Quickstart
Source: https://docs.capy.ai/quickstart
Get started with Capy in 5 minutes — create an account, connect a GitHub repository, start your first AI coding task, and review the generated code.
Go to [capy.ai](https://capy.ai), sign up, and choose the Capy Pro tier that matches your expected usage.
From the dashboard, click **Connect GitHub** and install the Capy GitHub App. Choose which repositories to grant access to.
Open **Settings → Project → Dev environment** and click **Set up with Captain**. Captain inspects your repos and writes the install scripts, commands, and VM size every run will use — see [Dev environment](/configs/dev-environment).
Click **Start task**, pick your repo, and choose a model. Claude Sonnet is a good default.
Describe what you want. Be specific - reference files, mention patterns, explain the expected behavior. Here are some real examples:
*"Add a `/health` endpoint to the Express server in `src/server.ts` that returns `{ status: 'ok', uptime: process.uptime() }`."*
*"The login form at `src/components/LoginForm.tsx` doesn't show validation errors. Add inline error messages for empty email and invalid password format."*
*"Refactor the user service in `src/services/user.ts` to use the repository pattern like we do in `src/services/order.ts`."*
Check the diff view to see what changed. When you're happy with it, click **Create PR** and merge on GitHub.
For complex work, start with Captain instead - it'll read your codebase and plan the approach before coding starts.
# PR reviews
Source: https://docs.capy.ai/review
Capy's Review agent reads pull request diffs, analyzes changes, and posts structured findings as inline GitHub comments — categorized by type and severity.
## Overview
Capy analyzes pull request diffs in two complementary ways: a **PR summary** and **review findings**. The summary explains what changed at a functional level, grouped by capability rather than by file. Findings identify specific issues, categorize them, assign severity, and attach them to code locations.
You can trigger reviews from Captain or directly from the PR page. When Captain is managing the task, it handles the full triage-and-fix loop after the review completes.
## Triggering a review
You can start a review in three ways:
1. **From Captain**
After Captain creates a PR for a completed task, it automatically triggers a review when permissions allow. Captain passes context about what the task was meant to accomplish, so the Review agent evaluates the diff against intended behavior, not just raw code changes.
You can also ask Captain to review any PR at any time, for example `review PR #42` or `run the review agent on SCO-005`.
2. **From the PR page**
Open any pull request in the Capy dashboard and click **Review** to run a manual review.
3. **Automatic on PR events**
Enable **Auto-review PRs** in your project settings to automatically review every PR when it's opened or updated. This applies to PRs not managed by Captain - draft PRs are skipped, and PRs associated with Capy tasks are skipped because Captain handles those reviews separately. No user-level permission is needed; the setting is project-wide.
## Review permissions
By default, Capy asks for permission before running a review. When Captain wants to review a PR, you get a permission card with four options:
* **Deny** - skip the review
* **Allow this time** - one-time approval (expires after about 5 minutes)
* **Allow for this run** - approve for the current Captain session
* **Always allow** - enable auto-review permanently
**Always allow** is the same setting as the **PR reviews** toggle in **Settings → Preferences**. When you enable it, Capy reviews PRs automatically without prompting, and any PR where you are the author gets reviewed.
You only need to grant permanent permission once. After auto-review is enabled, future reviews run without interruption.
## What a review produces
PR summaries and reviews are separate processes run by different agents.
**PR summary**
A separate Summary agent reads the full diff and groups changes by functional capability, not by file. This gives you a fast, high-level view of what the PR accomplishes. The summary updates automatically whenever the PR changes (for example, when new commits are pushed), and it runs independently of reviews.
**Findings**
When you run a review, the Review agent analyzes the diff for issues and emits structured findings. Each finding includes a title and rationale, category, severity, and code location (file path plus line number).
## Finding categories
| Category | What it covers |
| ------------------- | -------------------------------------------------------- |
| **Bug** | Logic errors, incorrect behavior, crashes |
| **Risk** | Security issues, race conditions, data loss potential |
| **Maintainability** | Code clarity, naming, documentation gaps |
| **Refactor** | Structural improvements, duplication, pattern violations |
## Severity levels
| Severity | Meaning |
| ------------ | --------------------------------------------------------- |
| **Critical** | Must fix before merging - security holes, data corruption |
| **High** | Likely to cause problems in production |
| **Medium** | Should address - maintainability or correctness concerns |
| **Low** | Style, minor improvements, nice-to-haves |
## GitHub comments
Findings with **medium severity or higher** are posted as inline review comments on GitHub, attached to the relevant lines in the PR.
Low severity findings stay in Capy's dashboard only, so GitHub threads stay focused on higher-impact issues.
Re-reviews do not flag the same issue twice. If a finding was already reported, Capy skips it.
When a finding is marked **resolved** or **irrelevant**, Capy automatically resolves the corresponding GitHub review thread.
## Triage and resolution
Each finding has a triage status.
| Status | Meaning |
| -------------- | --------------------------------- |
| **Open** | Active issue that needs attention |
| **Resolved** | The issue has been fixed |
| **Irrelevant** | False positive or not applicable |
When Captain is managing the task, it triages automatically after review, marking false positives as **irrelevant**, confirming already-fixed issues as **resolved**, and sending real issues to the Build agent for fixing.
You can override any triage decision. If Captain marks a finding as irrelevant but you disagree, you can reopen it.
You can also triage findings manually from the Capy dashboard without Captain.
## Re-reviews
Re-reviews are incremental. Previously **irrelevant** findings are skipped. **Resolved** findings are re-checked and only re-flagged if the issue persists. **Open** findings are re-flagged only when the referenced code changed, and new issues in new or modified code are flagged normally.
## Custom review instructions
Create a `.capy/REVIEW.md` file in your repository to customize how reviews work. This is the Review agent's equivalent of `BUILD.md` - it only reads this file.
```markdown theme={null}
# Review Instructions
## Do not flag
- Snapshot ID changes are normal workflow
- Intentional fallback patterns are backward compat
- Defensive defaults are project convention
## Severity
- Only flag medium+ for user-facing bugs
- Style/preference issues should be low priority
## Focus areas
- Always check for SQL injection in new queries
- Flag any direct database access outside the repository layer
```
Changes to `REVIEW.md` take effect on the next review. If `.capy/REVIEW.md` is not found, the Review agent falls back to `AGENTS.md` (or `CLAUDE.md`) at the repository root.
# Support
Source: https://docs.capy.ai/support
Contact the Capy support team through the app or by email.
For the fastest response, open your user menu in [Capy](https://capy.ai) and select **Contact us** to start a chat with our support team.
If you cannot access the app or prefer email, contact [support@capy.ai](mailto:support@capy.ai).
# Capy 101
Source: https://docs.capy.ai/using-capy
Learn how Capy works — create coding tasks, use Captain for planning and Build for execution, choose AI models, and review diffs before merging.
## Tasks
A task is a coding session. You describe what you want, an agent builds it in a VM, and you review the diff and create a PR.
Each task gets its own branch (`capy/-`). Your main branch stays clean. You can run the same task with different models to compare approaches - each run has its own conversation history and VM.
Tasks move through four states: **backlog** (planned, editable), **in progress** (agent working), **needs review** (work complete), and **archived** (done).
The task interface has a chat panel for talking to the agent, a file browser for navigating changes, a diff view for reviewing code, terminal output for command results, and a todo list showing the agent's progress.
## Captain vs Build
**Captain** is for planning. It reads your codebase, creates detailed task specs, and delegates to Build agents. Use it for complex features, multi-step projects, or when you're not sure how to approach something. Captain can read code, browse the web, view PRs and issues, and create tasks - but it doesn't edit files or run commands. That's by design.
**Build** is for coding. It has full VM access - edits files, runs commands, installs packages, browses the web, commits code. It works in an isolated Ubuntu VM with Python, Node.js, TypeScript, Rust, Go, Java, Docker, and common tools pre-installed. How that VM is prepared - setup scripts, commands, size - is configured per project in the [Dev environment](/configs/dev-environment). Use Build when you know exactly what needs to be done.
Start with Captain if you're not sure. It'll read your code and figure out the plan. If you already know exactly what you want, go straight to Build.
## Prompting tips
The biggest factor in getting good results is how you describe the task. Vague prompts get vague results. Specific prompts get working code.
**Be explicit.** "Add error handling to the payment flow in `src/payments/checkout.ts` for network failures and invalid card responses" beats "improve the payment flow."
**Reference files and patterns.** If your codebase already does something well, point to it: "Follow the pattern in `src/services/order.ts`." The agent will read that file and mirror the approach.
**Break big things up.** One task per feature or fix. "Implement auth, add the dashboard, and set up email notifications" is three tasks. Let Captain break it down, or do it yourself.
**Give feedback directly.** If the agent gets something wrong, tell it specifically what to change. "Move the validation to a middleware" is better than "this doesn't look right."
Here are some strong prompts:
*"The `useAuth` hook in `src/hooks/useAuth.ts` doesn't handle token refresh. Add automatic refresh when the token expires, following the error handling pattern in `src/hooks/useApi.ts`."* - Specific file, specific problem, reference to a pattern.
*"Add pagination to the `/api/posts` endpoint. Use cursor-based pagination like we do in `/api/comments`. Return 20 items per page with `nextCursor` in the response."* - Clear requirement, points to existing implementation, specifies the interface.
*"The user profile page at `src/pages/Profile.tsx` crashes when `user.avatar` is null. Add a fallback avatar and handle the null case in the `UserHeader` component."* - Describes the bug, names the file, explains the fix.
## Context compaction
For long tasks, Capy's harness can compact context before the next model request when a run approaches the model limit. Compaction preserves the latest user ask, key facts, constraints, evidence IDs, and next actions, then continues the same task from that compacted boundary.
| Model | API ID | Compact threshold |
| ----------------------- | ------------------------ | ----------------- |
| **Claude Fable 5** | `claude-fable-5` | 600K |
| **Claude Sonnet 5** | `claude-sonnet-5` | 400K |
| **Claude Opus 4.8** | `claude-opus-4-8` | 400K |
| **Claude Opus 4.7** | `claude-opus-4-7` | 400K |
| **Claude Opus 4.6** | `claude-opus-4-6` | 400K |
| **Claude Opus 4.5** | `claude-opus-4-5` | 160K |
| **Claude Sonnet 4.6** | `claude-sonnet-4-6` | 400K |
| **Claude Haiku 4.5** | `claude-haiku-4-5` | 160K |
| **GPT-5.6 Sol** | `gpt-5.6-sol` | 400K |
| **GPT-5.6 Terra** | `gpt-5.6-terra` | 400K |
| **GPT-5.6 Luna** | `gpt-5.6-luna` | 200K |
| **GPT-5.5** | `gpt-5.5` | 400K |
| **GPT-5.5 Pro** | `gpt-5.5-pro` | 400K |
| **GPT-5.4** | `gpt-5.4` | 400K |
| **GPT-5.4 Mini** | `gpt-5.4-mini` | 200K |
| **GPT-5.3-Codex** | `gpt-5.3-codex` | 200K |
| **GPT-5.3-Codex-Spark** | `gpt-5.3-codex-spark` | 100K |
| **Gemini 3.1 Pro** | `gemini-3.1-pro-preview` | 200K |
| **Gemini 3 Flash** | `gemini-3-flash-preview` | 200K |
| **Grok 4.1 Fast** | `grok-4-1-fast` | 200K |
| **Grok 4.5** | `grok-4-5` | 400K |
| **Composer 2.5 Fast** | `composer-2.5-fast` | 160K |
| **GLM 5.2** | `glm-5.2` | 400K |
| **GLM 5.1** | `glm-5.1` | 160K |
| **GLM 5V Turbo** | `glm-5v-turbo` | 160K |
| **DeepSeek V4 Pro** | `deepseek-v4-pro` | 400K |
| **GLM 5 Turbo** | `glm-5-turbo` | 160K |
| **GLM 4.7** | `glm-4.7` | 100K |
| **Kimi K3** | `kimi-k3` | 400K |
| **Kimi K2.7 Code** | `kimi-k2.7-code` | 200K |
| **Kimi K2.6** | `kimi-k2.6` | 200K |
| **Qwen 3 Coder** | `qwen3-coder` | 160K |
## Models
Capy supports models from Anthropic, OpenAI, Google, xAI, and more. You can switch models mid-task or run the same task with different models to compare their implementations.
### Route models through an external subscription
You can connect an existing provider subscription and run compatible models through your own account instead of Capy's inference account. Go to [Settings → Models](https://capy.ai/settings/models), then connect a provider under **External subscriptions**:
* **Codex** routes compatible OpenAI models through your ChatGPT subscription.
* **GitHub Copilot** routes compatible Claude, GPT, and Gemini models through your Copilot subscription.
* **xAI Grok** routes compatible Grok and Composer models through your xAI subscription.
Available models depend on your provider and plan. After connecting, use the provider selector under **Available models** to choose whether each compatible model runs through Capy or your external provider.
When your external credits are exhausted, the connection is unavailable, or the provider is rate limited, you can choose whether Capy uses Capy credits or ends the run with an error. Model usage routed through the external provider uses that subscription, while Capy platform costs still apply.
### Available models
Prices below show provider API rates.
| Model | API ID | Provider | Context | Input (per 1M, API) | Output (per 1M, API) |
| ----------------------- | ------------------------ | ------------- | ------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| **Claude Fable 5** | `claude-fable-5` | Anthropic | 1M | \$10.00 (cached read \$1.00) | \$50.00 (cache write \$12.50) |
| **Claude Sonnet 5** | `claude-sonnet-5` | Anthropic | 1M | \$2.00 (cached read \$0.2) | \$10.00 (cache write \$2.50) |
| **Claude Opus 4.8** | `claude-opus-4-8` | Anthropic | 1M | \$5.00 (cached read \$0.5) | \$25.00 (cache write \$6.25) |
| **Claude Opus 4.7** | `claude-opus-4-7` | Anthropic | 1M | \$5.00 (cached read \$0.5) | \$25.00 (cache write \$6.25) |
| **Claude Opus 4.6** | `claude-opus-4-6` | Anthropic | 1M | \$5.00 (cached read \$0.5) | \$25.00 (cache write \$6.25) |
| **Claude Opus 4.5** | `claude-opus-4-5` | Anthropic | 200K | \$5.00 (cached read \$0.5) | \$25.00 (cache write \$6.25) |
| **Claude Sonnet 4.6** | `claude-sonnet-4-6` | Anthropic | 1M | \$3.00 (cached read \$0.3) | \$15.00 (cache write \$3.75) |
| **Claude Haiku 4.5** | `claude-haiku-4-5` | Anthropic | 200K | \$1.00 (cached read \$0.1) | \$5.00 (cache write \$1.25) |
| **GPT-5.6 Sol** | `gpt-5.6-sol` | OpenAI | 1M | ≤272K: \$5.00 (cached read \$0.5)
>272K: \$10.00 (cached read \$1.00) | ≤272K: \$30.00 (cache write \$6.25)
>272K: \$45.00 (cache write \$12.50) |
| **GPT-5.6 Terra** | `gpt-5.6-terra` | OpenAI | 1M | ≤272K: \$2.50 (cached read \$0.25)
>272K: \$5.00 (cached read \$0.5) | ≤272K: \$15.00 (cache write \$3.13)
>272K: \$22.50 (cache write \$6.25) |
| **GPT-5.6 Luna** | `gpt-5.6-luna` | OpenAI | 400K | ≤272K: \$1.00 (cached read \$0.1)
>272K: \$2.00 (cached read \$0.2) | ≤272K: \$6.00 (cache write \$1.25)
>272K: \$9.00 (cache write \$2.50) |
| **GPT-5.5** | `gpt-5.5` | OpenAI | 1M | ≤272K: \$5.00 (cached read \$0.5)
>272K: \$10.00 (cached read \$1.00) | ≤272K: \$30.00
>272K: \$45.00 |
| **GPT-5.5 Pro** | `gpt-5.5-pro` | OpenAI | 1M | ≤272K: \$30.00
>272K: \$60.00 | ≤272K: \$180.00
>272K: \$270.00 |
| **GPT-5.4** | `gpt-5.4` | OpenAI | 1M | ≤272K: \$2.50 (cached read \$0.25)
>272K: \$5.00 (cached read \$0.5) | ≤272K: \$15.00
>272K: \$22.50 |
| **GPT-5.4 Mini** | `gpt-5.4-mini` | OpenAI | 400K | \$0.75 (cached read \$0.075) | \$4.50 |
| **GPT-5.3-Codex** | `gpt-5.3-codex` | OpenAI | 400K | \$1.75 (cached read \$0.175) | \$14.00 |
| **GPT-5.3-Codex-Spark** | `gpt-5.3-codex-spark` | OpenAI | 128K | \$0 (cached read \$0) | \$0 |
| **Gemini 3.1 Pro** | `gemini-3.1-pro-preview` | Google | 1M | ≤200K: \$2.00 (cached read \$0.2)
>200K: \$4.00 (cached read \$0.4) | ≤200K: \$12.00
>200K: \$18.00 |
| **Gemini 3 Flash** | `gemini-3-flash-preview` | Google | 1M | \$0.5 (cached read \$0.05) | \$3.00 |
| **Grok 4.1 Fast** | `grok-4-1-fast` | xAI | 2M | ≤128K: \$0.2 (cached read \$0.05)
>128K: \$0.4 (cached read \$0.05) | ≤128K: \$0.5
>128K: \$1.00 |
| **Grok 4.5** | `grok-4-5` | xAI | 500K | \$2.00 (cached read \$0.5) | \$6.00 |
| **Composer 2.5 Fast** | `composer-2.5-fast` | xAI | 200K | \$0 (cached read \$0) | \$0 |
| **GLM 5.2** | `glm-5.2` | Fireworks | 1M | \$1.40 (cached read \$0.26) | \$4.40 |
| **GLM 5.1** | `glm-5.1` | Fireworks | 203K | \$1.40 (cached read \$0.26) | \$4.40 |
| **GLM 5V Turbo** | `glm-5v-turbo` | Z.AI | 203K | \$1.20 (cached read \$0.24) | \$4.00 |
| **DeepSeek V4 Pro** | `deepseek-v4-pro` | Fireworks | 1M | \$1.74 (cached read \$0.145) | \$3.48 |
| **GLM 5 Turbo** | `glm-5-turbo` | Z.AI | 203K | \$0.96 (cached read \$0.192) | \$3.20 |
| **GLM 4.7** | `glm-4.7` | Google Vertex | 131K | \$0.6 | \$2.20 |
| **Kimi K3** | `kimi-k3` | Moonshot AI | 1M | \$3.00 (cached read \$0.3) | \$15.00 |
| **Kimi K2.7 Code** | `kimi-k2.7-code` | Fireworks | 262K | \$0.95 (cached read \$0.19) | \$4.00 |
| **Kimi K2.6** | `kimi-k2.6` | Fireworks | 262K | \$0.95 (cached read \$0.16) | \$4.00 |
| **Qwen 3 Coder** | `qwen3-coder` | Google Vertex | 262K | \$0.22 (cached read \$0.022) | \$1.80 |
### Fast mode for GPT-5.6
All GPT-5.6 models support Fast mode through OpenAI Priority processing for prompts up to 272K tokens. Priority rates per 1M tokens are:
* **GPT-5.6 Sol:** \$10.00 input, \$1.00 cached read, \$12.50 cache write, \$60.00 output
* **GPT-5.6 Terra:** \$5.00 input, \$0.50 cached read, \$6.25 cache write, \$30.00 output
* **GPT-5.6 Luna:** \$2.00 input, \$0.20 cached read, \$2.50 cache write, \$12.00 output
Fast mode is unavailable when the prompt exceeds 272K tokens.
### Quick recommendations
* **Quick edits:** Haiku 4.5, Gemini 3 Flash, Qwen 3 Coder - fast and cheap for simple changes
* **Standard work:** Sonnet 4.6, GPT-5.4, GPT-5.3-Codex - good balance of speed and capability
* **Complex tasks:** Opus 4.8, GPT-5.5, GPT-5.5 Pro - best reasoning for architectural decisions
* **Large codebases:** Sonnet 4.6, Gemini 3.1 Pro, Grok 4.1 Fast - 1M+ context windows
### Extended thinking
Some models support extended thinking (also called reasoning). This makes the model "think longer" before responding - it uses more tokens but produces better results for complex tasks. You can toggle it in the model selector.
Models with adaptive thinking adjust reasoning effort automatically. Models with level-based thinking let you set the effort explicitly (minimal, low, medium, high).
### Model preferences
Manage your model settings at [Settings → Models](https://capy.ai/settings/models):
* **Default model** - set which model new tasks use by default
* **Visible models** - hide models you don't use from the model selector
* **Reasoning level** - configure the default thinking effort
# Welcome to Capy
Source: https://docs.capy.ai/welcome
Capy runs coding tasks for you. Describe what you want and an agent builds it in its own VM. Review the diff, create a PR, and move on.
Capy runs coding tasks for you. Describe what you want - fix a bug, build a feature, refactor a module - and an agent builds it in its own VM. You review the diff, create a PR, and move on.
There are two modes. **Captain** reads your codebase and writes detailed specs so Build agents get it right the first time. **Build** does the actual coding - it edits files, runs commands, installs packages, and commits code.
Get up and running in 5 minutes
Tasks, agents, prompting tips, and models
Dev environment, agent instructions, and skills
Plans and usage costs