# Agent kit

The agent kit is a small set of instruction files for the assistant that writes your code. Drop them into a project and the assistant knows which frameworks HostEdge supports, how static and server deploys differ, how to use databases and environment variables, how to deploy, wait for the build, read logs and roll back, and which rules to follow (never commit secrets, redeploy after changing variables).

It is generated from the same code as the dashboard, so the framework list and plan limits never go stale.

## Add it to a project

From the project folder:

```sh
npx hostedge init --ai      # links the folder to a project and writes the kit
npx hostedge ai-kit         # only the kit; needs no account
```

Or download the files with `curl`:

```sh
curl -fsSL https://hostedge.app/agent-kit/AGENTS.md -o AGENTS.md
curl -fsSL https://hostedge.app/agent-kit/CLAUDE.md -o CLAUDE.md
mkdir -p .cursor/rules .claude/skills/hostedge
curl -fsSL https://hostedge.app/agent-kit/hostedge.mdc -o .cursor/rules/hostedge.mdc
curl -fsSL https://hostedge.app/agent-kit/SKILL.md -o .claude/skills/hostedge/SKILL.md
```

You can also copy each file from **Settings › API tokens › Copy instructions for your assistant**.

| File                               | Read by                                                    |
| ---------------------------------- | ---------------------------------------------------------- |
| `AGENTS.md`                        | Claude Code, Codex, Cursor, Windsurf and most other agents |
| `CLAUDE.md`                        | Claude Code. It only imports `AGENTS.md`                   |
| `.cursor/rules/hostedge.mdc`       | Cursor, as a rule the agent applies when it is relevant    |
| `.claude/skills/hostedge/SKILL.md` | Claude Code, as a skill it loads on demand                 |

The CLI never overwrites a file whose content differs unless you pass `--force`; it prints what it wrote (`+` created, `~` overwritten, `=` unchanged, `!` kept) and running it twice changes nothing. If you already have an `AGENTS.md`, keep it and paste the HostEdge section into it. `.cursor` and `.claude` folders are never deployed.

## Give the assistant access

The kit tells the assistant how to work; it still needs permission to deploy. Pick one:

- **MCP server.** Add `https://hostedge.app/api/mcp` to the assistant. See [AI assistants](https://hostedge.app/docs/ai-assistants).
- **CLI with a token.** Create a token in **Settings › API tokens** and set it as `HOSTEDGE_TOKEN` in the assistant's environment.

## A CLI made for agents

Every `hostedge` command works without a person at the keyboard.

- `--json` puts machine-readable output on stdout and every human line (progress, build log, tips) on stderr. The two never mix. `hostedge logs --json` writes one JSON object per line (NDJSON).
- `--yes`, `CI=1` or a missing terminal turn off every prompt. Commands never wait for input; when something is required they fail with a message that says what to pass.
- `--quiet` hides progress. `hostedge deploy --quiet` prints only the URL.
- `--api-url <url>` (or `HOSTEDGE_API_URL`) points at another HostEdge. `NO_COLOR` and `--no-color` turn colors off.
- Tokens are never printed. `HOSTEDGE_TOKEN` is used as is and not written to disk; `hostedge login --with-token` reads a token from stdin and saves it (`--token <t>` also works but shows in the process list).

```sh
# Who am I? { "user": …, "workspace": …, "scopes": […], "apiUrl": …, "tokenSource": "env" }
npx hostedge whoami --json

# Deploy and wait. Exit code 0 when live, 5 when the build fails.
npx hostedge deploy --wait --json --yes
# { "deploymentId": "dep_…", "status": "ready", "url": "https://….hostedge.app",
#   "projectId": "prj_…", "environment": "production", "failureReason": null }

# Errors from the last hour, one JSON object per line.
npx hostedge logs --json --level error --since 1h
# { "id": "…", "timestamp": "2026-10-22T09:15:02.000Z", "level": "error", "type": "…", "message": "…" }
```

When a build fails, `deploy --wait --json` still prints the same object with `"status": "failed"` and the reason in `failureReason`, and exits with 5. With `--json`, any other failure prints `{ "error": { "code": "auth", "message": "…", "exitCode": 3 } }` on stdout and the message on stderr.

`hostedge logs` accepts `--since` as minutes, hours or days up to 7 days (`30m`, `6h`, `7d`) and `--level` as `debug`, `info`, `warn` or `error`.

### Exit codes

| Code | Name            | Meaning                                                            |
| ---- | --------------- | ------------------------------------------------------------------ |
| 0    | `ok`            | Success.                                                           |
| 1    | `failure`       | Generic failure (network error, bad input, unexpected).            |
| 2    | `usage`         | Usage error: unknown flag or command, missing input.               |
| 3    | `auth`          | Not signed in, token invalid, expired, revoked or missing a scope. |
| 4    | `not_found`     | Project, deployment or linked folder not found.                    |
| 5    | `deploy_failed` | The deployment failed or was canceled.                             |
| 6    | `limit`         | A plan limit was reached (projects, size, storage …).              |

The same table is in `hostedge --help`. See [CLI](https://hostedge.app/docs/cli) for every command.

## What the kit teaches

- **Static or server.** Which output each [framework](https://hostedge.app/docs/frameworks) produces and what runs on a Worker.
- **Bindings.** `env.DB` (SQL), `env.KV` and `env.FILES` (files), created in **Storage** or with `create_database`, and a redeploy to connect them.
- **Environment variables.** `set_env_vars`, build time versus runtime, and redeploying after a change.
- **Deploy, wait, debug, roll back.** With the CLI (`--json`) or the MCP tools, polling `get_deployment` until the status is `ready` or `failed`.
- **Limits.** The plan table from [Limits](https://hostedge.app/docs/limits), and what to do at exit code 6.
- **Rules.** Never commit secrets, never print the token, do not invent features.