# Set up Infrapilot

You are a coding agent. The person you work with wants Infrapilot for this project. Follow this page from top to bottom. Every API response also names the next step.

Infrapilot is autonomous cloud infrastructure. Its agent, **Pilot**, runs the person's cloud account inside limits they set. Nothing is installed. You will:

1. give Pilot scoped access to the cloud account,
2. write `infrapilot.yaml`: what to run and what must stay true,
3. start Pilot.

## Done means

- `GET https://infrapilot.fly/api/v1/setup/status` returns `"ready": true`.
- `infrapilot.yaml` is at the repository root (commit it; it holds no secrets).
- You told the person what Pilot manages, the limits you set, where its requests go, and the dashboard link.

## Rules

1. **The setup token is a secret.** Keep it in a shell variable. Send it only to `https://infrapilot.fly`, as `Authorization: Bearer <token>`. Never write it, or any cloud credential, to a file, commit or log.
2. **Ask the person before** you create access in their cloud, settle cost ceilings and bounds, or start Pilot. Show exactly what you will do.
3. **Don't invent limits.** Whatever you write is enforced. Propose values from what you find and confirm them.
4. **Grant only what the provider page lists.** Pilot never needs administrator access.
5. **If a step fails, read the error.** It says what is wrong. Fix it and repeat the step; don't skip ahead.

```bash
export INFRAPILOT_TOKEN='ipsetup_...'
export INFRAPILOT_URL='https://infrapilot.fly'
```

## 0. Read the workspace

```bash
curl -s -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup
```

| Field | Meaning |
| --- | --- |
| `workspace.provider` | `aws`, `azure` or `gcp` |
| `workspace.mode` | `existing`: adopt what already runs. `new`: build from nothing. A fleet can do both. |
| `next` | the step to do now: `connect_cloud`, `write_manifest`, `contacts`, `start` or `done` |
| `next_doc` | the page for that step |
| `connection.kinds` | ways to connect this cloud, best first |
| `connection.trust` | what you need from Infrapilot to grant access (for example the AWS principal and external id) |

A `401` means the token is wrong, expired (14 days) or replaced. Ask the person for a new prompt from the dashboard.

## 1. Connect the cloud account

Follow the provider's page:

- AWS: `https://infrapilot.fly/docs/aws.md`
- Azure: `https://infrapilot.fly/docs/azure.md`
- Google Cloud: `https://infrapilot.fly/docs/gcp.md`

**Ask the person how much Pilot may do, before creating any access.** There are three levels (`https://infrapilot.fly/docs/manifest.md`, `level`):

- **Observe**: Pilot reads the account and delivers a review: what runs, what it costs, what is at risk, what it would change. It changes nothing. Create the provider's **read-only** access and submit the connection with `"access": "observe"`. This is the right start for anyone unsure about giving an agent write access to production.
- **Propose**: Pilot prepares each change and a person approves it with one click. Create the normal access; set `level: propose` on the intents.
- **Autonomous** (the default): Pilot acts within the bounds in the spec and asks at the limits. Create the normal access.

Moving from observe to the other two later means creating the normal access and submitting the connection again.

Each provider page ends with `POST /api/v1/setup/cloud`. Infrapilot checks the connection from inside the workspace's sandbox. Success:

```json
{"ok": true, "account": "921008910388", "checks": [{"check": "credentials", "ok": true, "detail": "..."}], "next": "write_manifest"}
```

A `422` lists failed checks. Fix the access and resubmit. New roles can take a minute to work: if the first check fails with an access error, wait 15 seconds and resubmit once.

## 2. Decide what Pilot runs

Look at the repository and, with the provider's CLI, at the account. Answer three questions:

- **What exists that Pilot should run?** (mode `existing`) Find this project's production resources. Tag each one with the fleet name and a short logical name (labels on Google Cloud). Tagging changes nothing. Don't tag other projects' resources.
- **What should exist but doesn't?** (mode `new`) List workloads in plain terms: an HTTP service from this image, a queue, a private bucket. Pilot builds them.
- **What must stay true?** Write objectives: a metric that must stay under a number, such as API latency, queue backlog or throttled writes. Use an existing SLO, or propose a value from the last two weeks of data and confirm it.

What Pilot understands on each cloud:

```bash
curl -s $INFRAPILOT_URL/api/types/aws      # or azure, gcp
```

## 3. Write the fleet spec

Read `https://infrapilot.fly/docs/manifest.md`, then write `infrapilot.yaml` at the repository root:

```yaml
version: 1
fleet: shop                      # lowercase, digits and dashes
provider: aws
region: us-east-1
adopt:
  - tag: {"infrapilot:fleet": "shop"}
intents:
  - name: checkout API stays fast
    description: The checkout API answers within 400 ms at p99 and never throttles.
    objectives:
      - {resource: api, metric: Duration, stat: p99, below: 400}
      - {resource: api, metric: Throttles, below: 1}
    max_monthly_cost_usd: 150
    bounds:
      api.MemorySize: [128, 2048]
boundaries:
  manage: profiled
  create_types: []               # Pilot may not create anything
  protected: [orders-db]         # Pilot may never change these
```

Show the person the intents, cost ceilings, bounds and protected list. Get a yes, then submit:

```bash
curl -s -X PUT $INFRAPILOT_URL/api/v1/setup/manifest \
  -H "Authorization: Bearer $INFRAPILOT_TOKEN" -H "Content-Type: application/yaml" \
  --data-binary @infrapilot.yaml
```

A `422` returns `errors`, each naming a field. Fix them all and resubmit. `provider`, `region` and `scope` can be left out; they come from the connection.

Preview what the spec would adopt. This changes nothing:

```bash
curl -s -X POST -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup/discover
```

- `resources`: what `adopt` matches, with the logical `name` for each. Objectives and bounds must use these names.
- `owned_by_controllers`: values a provider autoscaler owns. Pilot tunes the autoscaler instead. Expected.
- `missing`: resources an intent names that weren't found. Add the tag, use the discovered name, or wait a minute for the tag index and run discover again.
- `to_build`: workloads Pilot will create.

Don't continue while `missing` is not empty. Show the person what will be adopted.

## 4. Say who decides

Pilot asks a person when it hits a limit. The owner's email is already a contact. Add others if the person wants:

```bash
curl -s -X POST $INFRAPILOT_URL/api/v1/setup/contacts \
  -H "Authorization: Bearer $INFRAPILOT_TOKEN" -H "Content-Type: application/json" \
  -d '{"email": ["team@example.com"]}'
```

Slack, Teams and phone: `https://infrapilot.fly/docs/requests.md`. This step is optional.

## 5. Start Pilot

Confirm with the person, then:

```bash
curl -s -X POST -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup/start
```

Poll until ready (usually under two minutes; longer when building):

```bash
curl -s -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup/status
```

```json
{"ready": true, "agent": {"state": "running"}, "resources": 7,
 "objectives": [{"objective": "api Duration p99 < 400", "status": "ok", "value": 212.0}],
 "first_review": "All three objectives are met. ...", "open_requests": [], "dashboard": "https://infrapilot.fly/app#/ws_..."}
```

If `agent.error` is set, the sandbox couldn't start; usually the step 1 access changed. If `ready` stays false for five minutes with no error, give the person the dashboard link and stop polling.

## 6. Confirm and hand over

Tell the person, briefly:

1. What Pilot manages now, and what you tagged.
2. Each intent: objectives, cost ceiling, bounds, and what is protected.
3. Pilot's `first_review`, and any `open_requests`.
4. Where requests go. Approving takes the link in the email and one button.
5. The `dashboard` link. The ledger there shows every change and why.
6. To change the spec later, edit `infrapilot.yaml` and submit it with an API token (`https://infrapilot.fly/docs/api.md`), or edit it in the dashboard.

Commit `infrapilot.yaml`, then `unset INFRAPILOT_TOKEN`.

## If something fails

| You see | Do |
| --- | --- |
| `401` on any call | Token invalid, expired or replaced. Ask for a new prompt. |
| `422` from `/cloud` | Each failed check in `checks` names the permission it needs. Fix and resubmit. |
| `422` from `/manifest` | Fix every item in `errors`. |
| `409` from `/start` | `next` names the step that isn't done. |
| `missing` in discover | Tag the resource, use the discovered name, or wait a minute. |
| `agent.error` in status | Cloud access changed. Redo step 1 (submitting the connection again stops the failing agent), then start again. Once Pilot has completed a first review the setup token is read-only: reconnect from the dashboard instead. |

Nothing changes in the cloud until Pilot starts. After that, every change is in the ledger with a reason and an undo. To stop Pilot: the dashboard's Settings page, or delete the role from step 1.
