InfrapilotAlpha

Get started

This page is written for your coding agent. Paste the setup prompt from your workspace and the agent follows it; read along to see exactly what it will do.

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.
Terminal
export INFRAPILOT_TOKEN='ipsetup_...'
export INFRAPILOT_URL='https://infrapilot.fly'

0. Read the workspace

Terminal
curl -s -H "Authorization: Bearer $INFRAPILOT_TOKEN" $INFRAPILOT_URL/api/v1/setup
FieldMeaning
workspace.provideraws, azure or gcp
workspace.modeexisting: adopt what already runs. new: build from nothing. A fleet can do both.
nextthe step to do now: connect_cloud, write_manifest, contacts, start or done
next_docthe page for that step
connection.kindsways to connect this cloud, best first
connection.trustwhat 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:

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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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:

Terminal
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):

Terminal
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 seeDo
401 on any callToken invalid, expired or replaced. Ask for a new prompt.
422 from /cloudEach failed check in checks names the permission it needs. Fix and resubmit.
422 from /manifestFix every item in errors.
409 from /startnext names the step that isn't done.
missing in discoverTag the resource, use the discovered name, or wait a minute.
agent.error in statusCloud 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.

    Type to search every page.