# Shipyard

> Deploy for AI agents and the people who run them, on hardware Interhost owns in Israel
> (il-tlv) and the Netherlands (nl-ams). Push a repository (Node, Next.js, a Dockerfile or
> docker compose), get a URL, roll back in one call. Billed in EUR by the minute for the CPU
> and memory your apps actually use.

## Facts an agent should not guess

- Regions: il-tlv (Tel Aviv) and nl-ams (Amsterdam). A project's region is set when it is
  created and never changes (error region_immutable). The control plane runs in il-tlv for
  both regions. Backups stay in the project's region. Read where a project's data lives from
  GET /v1/orgs/{orgId}/projects/{projectId}/residency.
- Auth: send `Authorization: Bearer <api key>`. Keys are made by a person at https://panel.apps.shipyard1.com/api-keys.
- Give an agent a project-bound key: it reaches one project, other projects answer 404 and
  organisation routes answer 403 key_project_bound. A key may carry a spend limit in EUR.
- A key can never mint keys, delete the organisation or change its owner (session_required).
- All routes are under https://panel.apps.shipyard1.com/api/v1/orgs/{orgId}/...; GET /v1/whoami returns the orgId,
  the scopes and the bound project.
- Errors: `{ "error": { "code", "message", "request_id", "hint"?, "next"? } }`. When
  `next` is present it is the call that fixes the problem.

## What an agent can do

Every capability is in the API. The CLI and the MCP server cover the common ones.

| Capability | API | CLI | MCP tool | Note |
| --- | --- | --- | --- | --- |
| Check the credential | `GET /v1/whoami` | `shipyard whoami` | `whoami` | Shows the organisation, the scopes and, for a bound key, the one project it may touch. |
| List projects | `GET /v1/orgs/{orgId}/projects` | - | `projects_list` | A project-bound key sees only its own project. |
| Create a project | `POST /v1/orgs/{orgId}/projects` | `shipyard init [slug] --region TLV|AMS` | `create_project` | Needs an org-wide key. The region (TLV or AMS) is fixed at creation. |
| Read a project | `GET /v1/orgs/{orgId}/projects/{projectId}` | - | `project_link` |  |
| Deploy | `POST /v1/orgs/{orgId}/projects/{projectId}/deployments` | `shipyard deploy [--image <ref>]` | `deploy` | Builds the pushed ref by default. `image` deploys an artefact already in the project's registry repository instead, resolved to a digest, with nothing built here. |
| List deployments | `GET /v1/orgs/{orgId}/projects/{projectId}/deployments` | `shipyard ps` | `deployment_status` | Newest first. The MCP tool reads the latest one when no id is given. |
| Deployment status | `GET /v1/orgs/{orgId}/projects/{projectId}/deployments/{deploymentId}` | - | `deployment_status` |  |
| Read logs | `GET /v1/orgs/{orgId}/projects/{projectId}/deployments/{deploymentId}/logs` | `shipyard logs <id> [-f] [--since <cursor>]` | `get_logs` | Server-sent events; every event carries an id. Pass the last one as since (or Last-Event-ID) to get only what came after. |
| Roll back | `POST /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}/rollback` | `shipyard rollback [<deployment-id>] [--env <id>]` | `rollback` | No body = back one, to the newest retained release behind the one serving. Never rebuilds; runs while new builds are blocked. no_release when nothing retained is behind it. |
| List releases a rollback can return to | `GET /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}/releases` | - | - | Newest first; each says whether it is serving, rollbackable, and why not. `retained` is how many the plan keeps. |
| List built versions | `GET /v1/orgs/{orgId}/projects/{projectId}/versions` | `shipyard versions` | `versions` |  |
| Promote to another environment | `POST /v1/orgs/{orgId}/projects/{projectId}/deployments/{deploymentId}/promote` | `shipyard promote --to <env>` | `promote` |  |
| List environment variables | `GET /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}/env` | `shipyard env list` | `env_list` | Per environment. Values come back masked. |
| Reveal one environment variable | `POST /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}/env/{key}/reveal` | `shipyard env get KEY` | - | Returns the value in clear, and the read is audited. |
| Set environment variables | `PUT /v1/orgs/{orgId}/projects/{projectId}/environments/{environmentId}/env` | `shipyard env set K=V` | `env_set` | Needs the env:write scope. |
| Security report | `GET /v1/orgs/{orgId}/projects/{projectId}/deployments/{deploymentId}/scan` | - | `security_report_get` |  |
| List security scans | `GET /v1/orgs/{orgId}/projects/{projectId}/scans` | - | `security_report_get` |  |
| List domains | `GET /v1/orgs/{orgId}/projects/{projectId}/domains` | `shipyard domains list` | `domains_list` |  |
| Add a domain | `POST /v1/orgs/{orgId}/projects/{projectId}/domains` | `shipyard domains add <host>` | - | Answers with the DNS record to create; verify once it is in place. |
| Verify a domain | `POST /v1/orgs/{orgId}/projects/{projectId}/domains/{domainId}/verify` | `shipyard domains verify <host>` | - |  |
| Resource metrics | `GET /v1/orgs/{orgId}/projects/{projectId}/metrics` | `shipyard metrics` | `get_metrics` |  |
| Where the data lives | `GET /v1/orgs/{orgId}/projects/{projectId}/residency` | - | - | Region, control plane and backup location, in public region names. |
| Usage this month | `GET /v1/orgs/{orgId}/usage` | `shipyard usage` | `get_usage` | Org-level: a project-bound key gets key_project_bound. |
| Billing position | `GET /v1/orgs/{orgId}/billing` | `shipyard billing` | `billing_show` | Plan, price list, the period rated so far, trial credit left, the spend limits and whether the organisation is stopped. No payment method or invoice exists yet. |
| Set spend limits | `PUT /v1/orgs/{orgId}/billing/limits` | `shipyard billing limits --alert <eur> --hard <eur>` | `billing_set_limits` | Org admin only. At the hard limit every environment of the organisation sleeps until it is raised; nothing is deleted. The MCP tool always needs confirm: true, and the CLI needs --yes when the figure would stop it immediately. |
| Mint an API key | `POST /v1/orgs/{orgId}/keys` | `shipyard keys create` | - | People only. A key cannot mint keys, whatever its scopes: the CLI command opens the panel form pre-filled with the project and spend limit, and a signed-in person creates it. |

## Error codes

| Code | Status | What to do |
| --- | --- | --- |
| `unauthenticated` | 401 | No credential, or one that is expired or revoked. Send Authorization: Bearer <key>. |
| `insufficient_scope` | 403 | The key lacks the scope this route needs. Ask a person for a key with that scope. |
| `key_project_bound` | 403 | The key is bound to one project and this route is organisation-wide. Use the route in next. |
| `session_required` | 403 | Only a signed-in person can do this (minting keys, deleting the organisation). Do not retry. |
| `spend_limit_reached` | 402 | The key reached its spend limit for this billing period. Running work keeps running; reads still work. A person raises the limit at next. |
| `not_found` | 404 | The resource does not exist or this credential may not see it. The two look the same on purpose. |
| `region_immutable` | 409 | A project cannot change region. Create a new project in the other region and deploy there. |
| `slug_taken` | 409 | Another project already uses this slug. Pick another. |
| `rate_limited` | 429 | Too many requests. Wait and retry with backoff. |

## Pricing (EUR, per organisation, no seats)

- Trial: €5 credit, once, no monthly fee
- Starter: €5 / month per organisation, includes €5 of usage
- Team: €20 / month per organisation, includes €20 of usage
- Sovereign: contract, talk to shipyard@interhost.net
- Usage: €20 per vCPU-month and €10 per GB-month of memory, metered by the minute.
- Not billed: members, keys, deploys, build minutes, security scans.
- Details: https://shipyard1.com/pricing

## Docs

- [Quickstart](https://shipyard1.com/docs/quickstart): from a repository to a URL
- [MCP server](https://shipyard1.com/docs/agents/mcp): connect Claude Code, Cursor or any MCP client
- [CLI reference](https://shipyard1.com/docs/cli)
- [API reference](https://shipyard1.com/docs/api), machine-readable at https://panel.apps.shipyard1.com/api/openapi.json
- [shipyard.yaml](https://shipyard1.com/docs/configuration)
- [Regions](https://shipyard1.com/docs/regions)
- [Where your data lives](https://shipyard1.com/residency): the residency commitment
- [Security model](https://shipyard1.com/docs/security)
- [Billing and limits](https://shipyard1.com/docs/billing): what is metered, how the month is priced, the limits an organisation sets
- [Pricing](https://shipyard1.com/pricing)