# Building on Korve as an agent

Korve is a paid-only cloud for agent-built applications: deploy a repository to a stable
`https://<slug>.korve.app` URL and provision only the managed resources the app declares.
Every surface -- API, dashboard, CLI, MCP, manifest -- exposes the same typed operation spec,
so anything you discover in one surface works in all of them.

## Connect

Pick one or several. They share the same typed operation contract, while the CLI and MCP
authorize through separate, scoped credential grants:

- **CLI** (native binary, machine-readable output, stable exit codes):

  ```bash
  curl -fsSL https://korve.dev/install.sh | sh
  korve login   # browser OAuth: organization, role, exact scopes
  ```

- **MCP** (two Code Mode tools -- `search` discovers operations, `execute` runs JavaScript
  against a bounded `korve.request({ method, path, query, body })` client; there is no
  method-per-operation client inside the sandbox):

  ```bash
  korve mcp install   # Codex, Claude Code, Cursor, and Windsurf
  korve mcp status
  ```

  These commands configure Korve's remote MCP endpoint at
  `https://mcp.korve.dev/mcp`.

- **Skills** (six working procedures for Claude Code and compatible agents: quickstart
  deploy, ship loop, CLI setup, MCP setup, platform operations, infrastructure as code):

  ```bash
  curl -fsSL https://korve.dev/skills.sh | sh
  ```

## The core loop

```bash
korve init                                # writes korve.toml, prints plan + pricing, deploys on approval
korve deploy --project <slug>             # queues, then polls to ready/failed
curl -s https://<slug>.korve.app          # verify the live URL yourself
korve logs --project <slug> --limit 50    # structured logs
korve deploys diagnose <deploy-id>        # failed deploy? get a diagnosis and a proposed fix
```

## Rules that keep sessions unstuck

- **Billing gates provisioning.** Korve has no free tier. A `402` response or CLI exit code `5`
  means the organization needs active billing -- send the human to the dashboard; do not retry.
- **Exit codes are the contract.** `0` success, `3` unauthenticated (`korve login`), `5` billing.
  Branch on them instead of parsing prose.
- **Slugs are addresses.** Org and project path parameters accept slugs everywhere; never fetch a
  list just to map a slug to an id.
- **Credentials are shown once.** A database connection string cannot be fetched again -- store it
  immediately as a server-side environment variable (`korve env set`), then deploy.
- **Budgets gate deploys, and only with a hard stop.** A project budget alerts at its threshold by
  default. When its hard stop is on and month-to-date spend has reached the cap, new deploys --
  including the ones a Git push triggers -- are refused, while already-running workloads keep
  serving. Provisioning a database, bucket, or cache is not budget-gated. Surface the limit to the
  human; do not try to work around it.
- **Plan before apply.** Manifest changes print a reviewable infrastructure plan with pricing.
  Show it to the human when the change is destructive or adds paid resources.

## Reference

- Quickstart: https://docs.korve.dev/quickstart
- CLI: https://docs.korve.dev/cli/overview and https://docs.korve.dev/cli/commands
- Agent OAuth: https://docs.korve.dev/agents/oauth
- MCP setup: https://docs.korve.dev/agents/mcp-setup
- Skills: https://docs.korve.dev/agents/skills
- Safe automation: https://docs.korve.dev/agents/safe-automation
- API reference: https://docs.korve.dev/api-reference/overview
- Machine-readable site map: https://korve.dev/llms.txt