Agent files

Copy a ready AGENTS.md, CLAUDE.md, Cursor rules file or Claude Code skill into your repository, or fetch it raw.

These files are in English in both languages, because a coding agent reads them, not a person.

AGENTS.md

The portable block, read by most harnesses, so start with this one. Fill in the bracketed values, such as the production branch, service name and environment, and delete what doesn't apply to your project. Its commands run on the CLI.

Terminal
curl -sL https://ghaym.me/agents.md >> AGENTS.md
# 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.

CLAUDE.md

The same guidance in the file Claude Code loads at the start of every session. Add it to your CLAUDE.md rather than replacing yours.

Terminal
curl -sL https://ghaym.me/integrations/ghaym.claude.md >> CLAUDE.md
# Deploying this repository to Ghaym Cloud

Add this to your project's `CLAUDE.md`, fill in the bracketed values, and delete what doesn't
apply. It is the same guidance as https://ghaym.me/agents.md, in the file Claude Code reads every
session. 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/integrations/ghaym.claude.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 me.** The CLI uses the login of whoever runs it. If `ghaym whoami` fails,
  ask me to run `ghaym login` in my own terminal; never ask me to paste a key into this 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 me 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)

## 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)

Every page under https://ghaym.me/en/docs is also served as Markdown: drop `/en`, add `.md` to the
path and `?lng=en`.

Cursor rules

A Cursor rule with frontmatter, applied to the whole project. Same content, trimmed to the shape Cursor reads.

Terminal
curl -sL --create-dirs https://ghaym.me/integrations/ghaym.cursor.mdc -o .cursor/rules/ghaym.mdc
---
description: How this repository deploys to Ghaym Cloud, with a link to the docs page for each rule.
globs:
alwaysApply: true
---

# Ghaym Cloud

Save as `.cursor/rules/ghaym.mdc`. Canonical version:
https://ghaym.me/integrations/ghaym.cursor.mdc

This repository deploys to Ghaym Cloud. Each rule links the page of the docs that explains it;
read that page before acting on the rule.

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

## Rules

- 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)
- 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 with `ghaym help all --json`.
  [CLI reference](https://ghaym.me/en/docs/cli)
- 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: `ghaym cloud deployments logs <id>`.
  [Builds and deploys](https://ghaym.me/en/docs/builds)
- Listen on `0.0.0.0`, on the port in `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 with `ghaym cloud git install`, then
  `ghaym cloud projects create --name <name>`, then
  `ghaym cloud services create --project <project> --type git --repo <owner/name> --size <size> --site <slug>`. `ghaym cloud regions list` names the sites. [Deploy your first service](https://ghaym.me/en/docs/getting-started)
- Try a change away from production with
  `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 with `ghaym cloud deployments rollback <id>`.
  [Roll back a deploy](https://ghaym.me/en/docs/rollback)
- 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 included, and moves 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 with `--dry-run` first: every command that changes something takes it and then
  changes nothing. [CLI reference](https://ghaym.me/en/docs/cli)
- 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)
- An API error's `docs` link points to the page for its `type`. Follow it before retrying.
  [API errors](https://ghaym.me/en/docs/errors)
- 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.
  [Sleep and wake](https://ghaym.me/en/docs/sleep)

The HTTP API: [API keys and scopes](https://ghaym.me/en/docs/api-keys).

Claude Code skill

A skill named deploy-to-ghaym: the deploy workflow, the four pre-flight checks, and how to read an API error. It loads only when the work is about deploying, so it can be longer.

Terminal
curl -sL --create-dirs https://ghaym.me/integrations/ghaym-skill.md -o .claude/skills/deploy-to-ghaym/SKILL.md
---
name: deploy-to-ghaym
description: Deploy a repository to Ghaym Cloud. Use when the user asks to deploy, ship or release this project to Ghaym, to set it up for Ghaym, to find out why a Ghaym deploy failed, or to read an error the Ghaym API returned. Covers the four checks before a deploy, the deploy itself, and how to read an API error, each with a link to the docs page behind it.
---

# Deploy to Ghaym Cloud

Save as `.claude/skills/deploy-to-ghaym/SKILL.md` in the repository, or under `~/.claude/skills/`
to have it everywhere. Canonical version: https://ghaym.me/integrations/ghaym-skill.md

Each step links the page of the Ghaym Cloud docs that explains it; read that page before acting
on the step. To learn every command and flag in one call:

```sh
ghaym help all --json
```

## Before you start

Sign-up needs a person, and deploying opens once Ghaym approves the account. If the user has 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. Never ask the user to paste a key into the conversation;
if `ghaym whoami` fails, ask them to run `ghaym login` in their own terminal.
[Set up a coding agent](https://ghaym.me/en/docs/agents)

## Check four things before deploying

1. **The app listens on every address, on the port Ghaym sets.** It binds to `0.0.0.0`, not to
   localhost, and reads the port from `PORT`. An app bound to localhost fails the readiness check.
   [Builds and deploys](https://ghaym.me/en/docs/builds)
2. **The repository builds.** Most languages are detected on their own; anything else needs a
   `Dockerfile`. [Builds and deploys](https://ghaym.me/en/docs/builds#how-the-image-is-built)
3. **No secret is in the repository.** No `.env` is committed and no key is about to be. Values
   belong in Ghaym, set with `ghaym cloud vars set`.
   [Set variables and secrets](https://ghaym.me/en/docs/variables)
4. **The branch you push is the one the service tracks.** Confirm it with the user; don't assume
   `main`. [Deploy from GitHub](https://ghaym.me/en/docs/deploy-from-github)

## Deploy

1. If the project doesn't exist yet, `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)
2. Push. A push to the branch a service tracks builds and deploys it, in every environment that
   tracks that branch.

   ```sh
   git push origin <branch>
   ```

   [Deploy from GitHub](https://ghaym.me/en/docs/deploy-from-github)

3. Read the build log with `ghaym cloud deployments logs <id>`. A successful push only means Git
   accepted the commit; the deploy has worked only when the build log says so.
   [Builds and deploys](https://ghaym.me/en/docs/builds)

To try a change away from production, run
`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)

To undo a bad deploy, run `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)

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. [CLI reference](https://ghaym.me/en/docs/cli)

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)

## Read an API error

Every error is a JSON document in RFC 9457 format. With `--json`, the CLI puts this document under
`error`. [API errors](https://ghaym.me/en/docs/errors)

- `type`: the error's name, such as `not-found`. Branch on it, not on the text.
- `title`: a short English title for the type.
- `status`: the HTTP status.
- `detail`: what went wrong with this call, for a person to read. Show it to the user.
- `docs`: the link to the type's page, with what causes the error and how to fix the call. Follow
  it before retrying.

A call to the API signs in with an access token traded for the key.
[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)