# AGENTS.md: deploying this repository to Ghaym Cloud

Add this to the AGENTS.md at the root of your repository (or create one), fill in the bracketed
values, and delete what doesn't apply to your project. It tells a coding agent (Claude Code,
Codex, Cursor or a similar tool) how this project reaches production. Each rule links the page of
the Ghaym Cloud docs that explains it; read that page before acting on the rule.

Canonical version: https://ghaym.me/agents.md

## This project

- Production branch: `[main]`
- Service name in Ghaym: `[web]`
- Environment: `[production]`

## Before you start

- **Sign-up needs a person.** Deploying opens once Ghaym approves the account. If there is no account, say
  so and stop.
  [Set up a coding agent](https://ghaym.me/en/docs/agents)
- **Use the CLI, not hand-written API calls.**
  [Install the CLI and sign in](https://ghaym.me/en/docs/install-the-cli)
- **Sign in through the person.** The CLI uses the login of whoever runs it. If `ghaym whoami`
  fails, ask them to run `ghaym login` in their own terminal; never ask them to paste a key into
  the chat. [Set up a coding agent](https://ghaym.me/en/docs/agents)
- **Learn every command and flag** in one call with `ghaym help all --json`.
  [CLI reference](https://ghaym.me/en/docs/cli)

## Deploying

- **A push deploys.** A push to the branch a service tracks builds and deploys it, in every
  environment that tracks that branch. [Deploy from GitHub](https://ghaym.me/en/docs/deploy-from-github)
- **A deploy has worked only when its build log says so.** A successful push only means Git
  accepted the commit. Read the log with `ghaym cloud deployments logs <id>`.
  [Builds and deploys](https://ghaym.me/en/docs/builds)
- **Listen on every address, on the port Ghaym sets.** Bind to `0.0.0.0`, not to localhost, and
  read the port from `PORT`. An app bound to localhost fails the readiness check, and its deploy
  fails.
  [Builds and deploys](https://ghaym.me/en/docs/builds)
- **Set the project up from this repository:** `ghaym cloud git install` prints the link that
  installs the Ghaym GitHub App, `ghaym cloud projects create --name <name>` creates the project,
  and `ghaym cloud services create --project <project> --type git --repo <owner/name> --size <size> --site <slug>`
  creates the service and starts its first deploy. `ghaym cloud regions list`
  names the sites.
  [Deploy your first service](https://ghaym.me/en/docs/getting-started)
- **Try a change away from production:**
  `ghaym cloud environments create --project <project> --name <name> --branch <branch>`, then
  push to that branch. [Deploy a branch to its own environment](https://ghaym.me/en/docs/branch-environments)
- **Undo a bad deploy:** `ghaym cloud deployments rollback <id>`. Ghaym puts that deploy's image
  live again without a build. [Roll back a deploy](https://ghaym.me/en/docs/rollback)

## Settings

- **Variables live in Ghaym**, set with `ghaym cloud vars set`, not in a committed config file.
  [Set variables and secrets](https://ghaym.me/en/docs/variables)
- **Every change is staged.** Variables, build settings, size, replicas, routing and access move
  only with `ghaym cloud changes apply`, or `--apply` on the same call. Applying a variable, a
  bucket connection, the branch or a build setting deploys the service.
  [Staged changes](https://ghaym.me/en/docs/staged-changes)
- **Try a change first.** Every command that changes something takes `--dry-run`, and then
  changes nothing. `services create`, `domains add` and `sessions rollback` return the plan
  with its estimated monthly price. [CLI reference](https://ghaym.me/en/docs/cli)

## When a command stops

- **Wait for a person to approve:** a command that needs approval exits with `6` and an approval
  id. Run `ghaym cloud approvals wait <id>` instead of retrying.
  [Supervise a coding agent](https://ghaym.me/en/docs/agent-approvals)
- **Branch on the exit code, not on the message.**
  [Exit codes](https://ghaym.me/en/docs/cli#exit-codes)
- **Follow the error's page.** Every error is a JSON document in RFC 9457 format, and its `docs`
  link points to the page for its `type`. [API errors](https://ghaym.me/en/docs/errors)
- **Check what happened:** `ghaym cloud audit list` and `ghaym cloud sessions list`, with
  `--json`. [See who changed what](https://ghaym.me/en/docs/activity)

## The HTTP API

A call to the API signs in with an access token traded for the key:

```sh
curl -sX POST https://auth.api.ghaym.me/v1/auth/token -H "Authorization: Bearer $GHAYM_TOKEN"
```

The access token is short-lived, and it can't be refreshed. A key can never do more than its
owner. [API keys and scopes](https://ghaym.me/en/docs/api-keys)

## Cost

- **Prices depend on the site.** Read them with `ghaym cloud regions sizes <region>`.
  [Limits and prices](https://ghaym.me/en/docs/limits-and-prices)
- **Polling keeps a service awake.** Services outside production sleep when idle, and
  compute is charged only while a service is awake. [Sleep and wake](https://ghaym.me/en/docs/sleep)
- **Outgoing traffic past the monthly allowance is charged.**
  [Limits and prices](https://ghaym.me/en/docs/limits-and-prices)

## Pages to read

- [API errors](https://ghaym.me/en/docs/errors): one page per API error type.
- [Get a repo ready with an agent](https://ghaym.me/en/docs/verified-prompts): prompts that get an
  existing repository ready to deploy.
- [Agent files](https://ghaym.me/en/docs/harness): this file, and its forms for Claude Code and
  Cursor.
- [llms.txt](https://ghaym.me/llms.txt): the site index in llms.txt format.
- Every page under https://ghaym.me/en/docs is also served as Markdown: drop `/en`, add `.md` to
  the path and `?lng=en`, for example https://ghaym.me/docs/agents.md?lng=en.
- Pages are in English under `/en`. A Markdown file without `?lng=en` is in Arabic.
