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:

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:

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

# 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 for every command.

What the kit teaches#

Static or server. Which output each framework 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, and what to do at exit code 6.
Rules. Never commit secrets, never print the token, do not invent features.

View this page as Markdown All docs as one file