@cursor/july 0.1.5 → 0.1.6

package/docs/deployment.md

@@ -1,54 +1,277 @@
 ---
 title: "Deployment"
-description: "Run agentkit on a real host: the auth model, credentials, durable state, single-box and Docker setups, and the production flags."
+description: "Deploy agentkit with Cursor-managed hosting or on infrastructure you control."
 ---
 
-# Deployment
-
-agentkit is a plain Node HTTP server. It runs anywhere Node
-22.13+ runs: a VM, a container platform, ECS. This page covers the parts
-that matter beyond local development: who can reach the server, where
-credentials and state live, and the flags that change meaning in
-production.
-
-## The security model in one minute
-
-Everything defaults to loopback-only. Until you change something, no
-route is reachable from another machine. `serve` binds `127.0.0.1`
-unless you pass `--host`. Every route runs an auth-policy chain whose
-default, `localDevStrict()`, admits direct loopback callers only, rejects
-requests carrying proxy-forwarding headers (`X-Forwarded-For`,
-`X-Real-IP`, `Forwarded`, `X-Forwarded-Host`), and requires a loopback
-`Host` header. A same-host reverse proxy, a tunnel, or a DNS-rebinding
-page can't silently re-expose the API.
-
-Three ways to open it up, in order of preference:
-
-1. **`--bearer-token <secret>`** replaces the default with
-   `bearerAuth(secret)` on every channel that doesn't author its own
-   auth. Clients send `Authorization: Bearer <secret>`; the playground
-   has a token field. Use this for anything shared.
-2. **Authored auth.** Channels declare their own `auth` chains:
-   `bearerAuth`, signature verification, custom policies. Authored
-   chains always win over serve-level flags. The GitHub channel is the
-   model: `allowAll()` at the route plus HMAC verification in the
-   channel.
-3. **`--allow-anonymous`** replaces the default with `allowAll()`, and
-   every caller shares one `anonymous` principal. Only behind a trusted
-   network boundary. The server refuses to start when
-   `--allow-anonymous` is combined with Cursor account MCP connections,
-   because any admitted caller could drive the signed-in account's
-   connectors. Mutually exclusive with `--bearer-token`.
-
-Session routes also bind to the principal that created the session
-(other principals get `403`). A single static bearer token maps every
-holder to one shared principal. So it isolates the host, not the users
-on it. For per-user isolation, pass a verifier function to `bearerAuth`
-that returns a distinct principal per presented token.
-
-## Credentials
-
-A host reads at most five kinds of credentials.
+# Deploy agentkit
+
+Both options run the same agent project and HTTP API. Channel delivery
+paths differ. Cursor-managed hosting is preferred for most agents.
+
+| Option | Use it when | You manage |
+| --- | --- | --- |
+| Cursor-managed hosting (preferred) | You want the shortest path from a Git repo to a running agent | Agent code, external storage, declared egress, and deployment secrets |
+| Self-hosting | You need your own network, proxy, persistent filesystem, or process controls | Agent code, Node process, TLS, auth, secrets, durable state, monitoring, and upgrades |
+
+## Cursor-managed hosting
+
+Cursor builds the selected Git ref into a deployment. The deployment
+exposes a stable URL while Cursor manages its runtime lifecycle.
+
+### Before you deploy
+
+- Confirm managed hosting is enabled for the account and team.
+- Sign in with an account holding team-admin deployment permission.
+- Add `@cursor/july` to the agent project.
+
+For a GitHub source, install the Cursor GitHub App on the repository
+owner and grant it access to the repository. Cursor builds through its
+repository integration, not your local Git credentials. Commit and push
+the Git ref before deploying it.
+
+### Declare hosting needs
+
+If the agent needs extra egress or deployment secrets, add a `hosting`
+block to `agent/agent.ts`:
+
+```ts
+import { defineAgent } from "@cursor/july";
+
+export default defineAgent({
+  hosting: {
+    egressDomains: ["api.weather.example.com"],
+    secretNames: ["WEATHER_API_KEY"],
+  },
+});
+```
+
+`egressDomains` lists outbound hosts beyond the platform's base policy.
+Enter hostnames without schemes, ports, or paths. One leading `*.`
+wildcard is allowed. Declared domains allow HTTPS and TLS traffic, not
+arbitrary TCP ports.
+
+`secretNames` lists the environment variables the agent expects. Names
+use `UPPER_SNAKE_CASE`. Commit names only; set their values after
+creating the deployment. Names beginning with `CURSOR_` are reserved.
+
+Run `agentkit validate` before deploying. It reports invalid domains and
+secret names as warnings, so fix them even when validation exits zero.
+
+### Deploy from Git
+
+Sign in, validate the project, and deploy it:
+
+```bash
+cd my-agent
+agentkit login
+agentkit whoami
+agentkit validate
+agentkit deploy
+```
+
+Inside a Git checkout, `deploy` infers the HTTPS `origin` URL, current
+branch or detached commit, agent path, and deployment slug. Explicit
+flags override each value:
+
+```bash
+agentkit deploy \
+  --repo https://github.com/acme/agents \
+  --ref main \
+  --path agents/weather \
+  --slug weather-agent
+```
+
+> [!IMPORTANT]
+> `--slug` doesn't retain source or Cursor-event settings. Run every
+> repo-backed deploy from the pushed checkout, or pass `--repo`, `--ref`,
+> `--path`, and any `--cursor-events-repo` flags again.
+
+Deploy reads the agent from Git; it doesn't upload local files. Keep the
+local `hosting` block in sync with the selected ref. A nested `--path`
+must contain `package.json` and be installable from its own directory.
+
+For a directory containing several agent projects, choose one from the
+TTY prompt, pass `--slug <name>`, or deploy each child with `--all`.
+Pass `--team <id>` when the signed-in account has no default team or you
+want another team.
+
+`--all` creates a separate deployment for each child. Self-host when the
+agents must share one multi-agent process.
+
+The command waits up to ten minutes for a running engine. Use
+`--no-wait` to return after Cursor accepts the deployment, then inspect
+it separately:
+
+```bash
+agentkit deployments
+agentkit deployment weather-agent
+agentkit logs --prod --slug weather-agent
+```
+
+### Set deployment secrets
+
+A deployment must exist before you can set its secrets. Omit values from
+the command line to enter them through the hidden prompt:
+
+```bash
+agentkit secrets set weather-agent WEATHER_API_KEY
+agentkit secrets list weather-agent
+agentkit deploy --dir . --slug weather-agent
+```
+
+The engine reads secret changes on its next deploy. `secrets list`
+returns names and creation times, never values. To set several values
+from automation, pipe one line per name instead of putting values in
+shell arguments.
+
+### Choose durable storage
+
+Hosted filesystem state can reset during a deploy or runtime
+replacement. Use [`defineStorage`](./storage.md) to preserve supported
+records across deployments. Self-host with a persistent `--state-root`
+when the complete filesystem must survive.
+
+### Use the hosted agent
+
+The CLI handles authentication for `--prod` commands. External clients
+and managed HTTP channels send `X-Agent-Alias-Token`; authored channel
+auth still applies. Use a Cursor relay, Socket Mode, a
+signature-validating intermediary, or self-host when a webhook provider
+can't add this header.
+
+Use `--prod` with the normal client commands:
+
+```bash
+agentkit playground --prod --slug weather-agent
+agentkit chat --prod --slug weather-agent
+agentkit run --prod --slug weather-agent --message "Forecast for Paris"
+agentkit sessions --prod --slug weather-agent
+agentkit logs --prod --slug weather-agent
+```
+
+Keep `playground --prod` running while the playground is open. Press
+Ctrl-C to stop it.
+
+The first deployment prints a reusable alias token once. Store it
+immediately. Run `agentkit deployment weather-agent` to retrieve the
+stable alias URL later. The token remains valid until rotation and can't
+be retrieved.
+
+External HTTP clients send the alias token on every request:
+
+```bash
+curl "$AGENT_ALIAS_URL/v1/health" \
+  -H "X-Agent-Alias-Token: $AGENT_ALIAS_TOKEN"
+```
+
+`--prod` commands don't use the alias token. If it is lost or exposed,
+rotate it. The old token stops working immediately:
+
+```bash
+agentkit rotate-token weather-agent
+```
+
+### Connect GitHub
+
+Let the hosted engine pull Cursor SCM events. Repeat
+`--cursor-events-repo` for each repository whose events should wake the
+agent:
+
+```bash
+agentkit deploy --dir . \
+  --slug pr-approver \
+  --cursor-events-repo acme/checkout \
+  --cursor-events-repo acme/payments
+```
+
+The agent still needs a `githubChannel()` declaration for the events it
+handles. This delivery path needs no public GitHub webhook URL. The
+flag requires Cursor SCM-event access for the deployment credential.
+
+For outbound GitHub calls, use `githubChannel({ cursorAccount: true })`
+and grant the team's Cursor GitHub App access to each repository.
+Alternatively, add dedicated GitHub credentials as deployment secrets.
+See the [GitHub guide](./guides/github.md).
+
+### Connect Slack
+
+Hosted Slack supports the team's Cursor Slack app or a dedicated Socket
+Mode app.
+
+Use the Cursor Slack app when mentions and direct messages are enough:
+
+```ts
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel({
+  cursorAccount: true,
+  agentName: "PrApprover",
+});
+```
+
+The team must have the Cursor Slack app installed and Slack event relay
+access enabled. This mode needs no Slack token secrets. It doesn't
+support channel-post watches, tool approvals, or interactivity.
+
+Use a dedicated Socket Mode app for those features or a separate bot
+identity:
+
+```ts
+import { slackChannel } from "@cursor/july/channels/slack";
+
+export default slackChannel({ envPrefix: "PR_APPROVER" });
+```
+
+The prefix selects the deployment secret names:
+
+```bash
+agentkit secrets set pr-approver \
+  PR_APPROVER_SLACK_BOT_TOKEN \
+  PR_APPROVER_SLACK_APP_TOKEN
+agentkit deploy --dir . --slug pr-approver
+```
+
+Without `envPrefix`, a dedicated app reads `SLACK_BOT_TOKEN` and
+`SLACK_APP_TOKEN`. Socket Mode needs no inbound URL. See the
+[Slack guide](./guides/slack.md).
+
+### Update or stop a deployment
+
+Redeploy the same slug after pushing a new Git ref. The stable alias
+continues to point at the active generation. Follow the same source rules
+from [Deploy from Git](#deploy-from-git).
+
+```bash
+agentkit deploy --dir /path/to/my-agent --slug weather-agent
+agentkit stop weather-agent
+```
+
+`stop` waits for the deployment to stop unless you pass `--no-wait`.
+See the [CLI reference](./reference/cli.md#deploy) for the full command
+reference.
+
+## Self-host agentkit
+
+agentkit runs as a Node HTTP server on Node 22.13 or newer. You can host
+it on a VM, container platform, or ECS.
+
+### The security model in one minute
+
+`serve` binds to loopback and admits direct local callers by default.
+Choose one of these options before exposing it:
+
+1. Pass `--bearer-token <secret>` for a shared host.
+2. Define channel-specific auth for routes with their own credentials or
+   signatures.
+3. Use `--allow-anonymous` only behind an authenticating proxy.
+
+A static bearer token maps every holder to one principal. Use authored
+auth when callers need separate identities. See
+[Channels](./reference/channels.md#auth-policies) for policy details.
+
+### Credentials
+
+A self-hosted server can read these credentials.
 
 | Credential | Used for | Provide it as |
 | --- | --- | --- |
@@ -58,95 +281,82 @@ A host reads at most five kinds of credentials.
 | GitHub API | outbound API calls | a GitHub App (`GITHUB_APP_ID` + `GITHUB_APP_PRIVATE_KEY` + installation id) or `GITHUB_TOKEN` / `gh auth login` |
 | MCP connection tokens | authored MCP connections | whatever env vars your `mcp-connections/*.ts` read |
 
-The Cursor credential resolves in one order everywhere: an explicit
-`apiKey` option or `--api-key`, then `CURSOR_API_KEY`, then the key
-stored by `agentkit login`. `agentkit whoami` shows which
-one is active and why. `logout` removes the stored key, and revoking it
-in the Cursor dashboard invalidates it immediately. Mint a dedicated key
-per host. `login` names it after the hostname, so you can revoke each one
-independently.
+Use a dedicated Cursor key per host. `agentkit whoami` shows the active
+credential. `logout` removes the stored key from the host; revoke the key
+in the Cursor dashboard to invalidate it. See
+[CLI authentication](./reference/cli.md#login--logout--whoami) for
+credential resolution.
 
-## State
+### State
 
-Durable state lives under `--state-root` (default
-`<project>/.agentkit`): sessions, event streams, session
-workspaces, the SDK conversation store, channel buffers, cursor-events
-offsets.
+Place `--state-root` on a persistent volume outside the agent
+repository, and back it up. Sessions survive restarts only when their
+state does. See [Storage](./storage.md) and
+[Sessions](./reference/sessions.md) for persistence and layout details.
 
-Put it on a persistent volume. Sessions survive restarts and streams
-replay only if the directory does. Put it outside any repository, to keep
-ambient `AGENTS.md` or `.cursor` rules out of session workspaces.
-`/var/lib/agentkit` is a good home. Back it up like the
-conversation history it is. Deleting a session directory removes that
-session from the server. The SDK conversation store under `runner/` keeps
-its own copy until you delete it too.
+### A single box
 
-## A single box
-
-The minimum production host is two processes and a private network:
+A single-host deployment needs one supervised `serve` process on a
+private network. Export the Cursor key and a generated bearer token in
+the supervisor environment:
 
 ```bash
+export CURSOR_API_KEY="<cursor-api-key>"
+export AGENTKIT_BEARER_TOKEN="$(openssl rand -hex 32)"
+
 # the server: all agents under one port
-CURSOR_API_KEY=… GITHUB_WEBHOOK_SECRET=… \
-  agentkit serve --dir /srv/agents --port 3000 --host 127.0.0.1 \
-  --state-root /var/lib/agentkit --bearer-token "$CURSOR_AGENT_KIT_TOKEN"
+agentkit serve --dir /srv/agents --port 3000 --host 127.0.0.1 \
+  --state-root /var/lib/agent-serve \
+  --bearer-token "$AGENTKIT_BEARER_TOKEN"
+```
+
+Slack Socket Mode needs no inbound network. For GitHub, prefer
+`--cursor-events --repo owner/repo` on `serve` so the host pulls events
+through Cursor without a public webhook URL.
+
+Webhook forwarding is the fallback. It needs one additional process.
+Before starting or restarting `serve`, export the same strong
+`GITHUB_WEBHOOK_SECRET` in both supervisor environments. Then install
+the extension, authenticate `gh`, and start the forwarder. Repository
+forwarding requires repo-admin access; organization forwarding with
+`--org` requires org-owner access.
+
+```bash
+export GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
+agentkit github doctor --install
+gh auth login
 
 # GitHub agents only: ONE forwarder relaying live deliveries to loopback
-GITHUB_TOKEN= GH_TOKEN= GITHUB_WEBHOOK_SECRET=… \
+GITHUB_TOKEN= GH_TOKEN= \
   agentkit github forward --dir /srv/agents --repo owner/repo
 ```
 
-Run both under a supervisor. systemd is the durable choice. tmux
-survives SSH disconnects but not reboots. On a TTY, `serve` restarts on
-Enter (it reloads agent code). Under a supervisor, restart the process.
-Sessions and streams are durable either way.
-
-Inbound network requirements are small. Slack needs none at all: Socket
-Mode dials out. Prefer GitHub via `--cursor-events` so the host pulls
-events with no inbound network (see
-[Pull events from Cursor](./guides/github.md#pull-events-from-cursor)).
-A public HTTPS webhook endpoint with the secret on both ends, or the
-forwarder above, is the fallback when you terminate GitHub deliveries
-yourself. Humans reach the playground through your private network or a
-tunnel.
-Keep `--bearer-token` on, because tunneled requests arrive from loopback
-and IP-based policies can't tell them apart.
+Run long-lived processes under a supervisor. systemd survives reboots;
+tmux survives only SSH disconnects. On a TTY, press Enter to reload
+agent code. Humans reach the playground through a private network or
+tunnel. Keep `--bearer-token` on because tunneled requests arrive from
+loopback and IP-based policies can't tell them apart.
 
 Health checks: `GET /v1/health` at the host level (made for ALB and ECS
 checks), and each agent also serves `/<slug>/v1/health`.
 
-## Docker
+### Containers
 
-The repository includes a [`Dockerfile`](../Dockerfile) used for an
-internal deployment. It builds the workspace deps and the playground
-bundle and runs multi-agent serve as a non-root user. But its `CMD`
-passes `--allow-anonymous`, because that deployment sits behind an
-authenticating proxy. Don't copy that flag without one. That image also
-enables `--cursor-events` to pull GitHub events (see the
-[GitHub guide](./guides/github.md#pull-events-from-cursor)).
+Build the image with Node 22.13 or newer, the agent source, and its
+package dependencies. Run `agentkit serve` as a non-root user:
 
-Until the package rename ships, the real image paths are still
-`dist/bin/agent-serve.js` and `/var/lib/agent-serve` (see the
-[rename table](./README.md#run-the-cli)). The baseline shape to copy,
-shown with post-rename names:
-
-```dockerfile
-# build: pnpm install + pnpm --filter @cursor/july run build
-# run (today: agent-serve.js and /var/lib/agent-serve):
-CMD ["node", "--import", "tsx", "dist/bin/agentkit.js", "serve", \
-     "--dir", "examples", "--mode", "multi", \
-     "--host", "0.0.0.0", "--port", "3000", \
-     "--state-root", "/var/lib/agentkit"]
+```bash
+agentkit serve --dir /srv/agents --mode multi \
+  --host 0.0.0.0 --port 3000 \
+  --state-root /var/lib/agent-serve \
+  --bearer-token "$AGENTKIT_BEARER_TOKEN"
 ```
 
-Inside a container, `--host 0.0.0.0` is required. Pair it with real auth
-(`--bearer-token`, or authored auth per channel), or keep the container
-on a private network. Mount the state root as a volume, install `git` and
-`gh` in the image when channels do host-side GitHub work (the shipped
-Dockerfile does), and inject secrets as env vars at start. Nothing secret
-belongs in the image.
+Mount the state root as a persistent volume and inject secrets at
+startup. Install `git` and `gh` when channels need host-side GitHub work.
+Don't put secrets in the image.
 
-## Serve many agents from one process
+### Serve many agents from one process
 
 Point `serve` at a folder of agent projects and every child mounts under
 its directory name on one port. One process, one state root, one
@@ -157,62 +367,55 @@ agentkit serve --dir /srv/agents
 # index at /, each agent at /<slug>/v1/*, /<slug>/playground
 ```
 
-`GET /` is a web index of every agent and `GET /v1/agents` is the JSON
-equivalent. Sessions are isolated per agent under `<stateRoot>/<slug>/`.
-Each agent needs its own Slack app and token pair. Agents without tokens
-mount with their Slack channel idle.
-
 Only mount what you mean to run. Every mounted agent's channels are live,
 and webhook-driven agents spend model budget on every wake. `--mode
-single` serves exactly one agent at the unslugged `/v1/*` when that agent
-is the whole host.
+single` serves exactly one agent at the unslugged `/v1/*` when the agent
+is the whole host. See the [HTTP API](./reference/http-api.md) for route
+layout and the [Slack guide](./guides/slack.md) for multi-agent token
+setup.
 
-## The production flags
+### The production flags
 
-These flags change meaning between a laptop and production.
+Use these settings in production:
 
 | Flag | In production |
 | --- | --- |
-| `--dev` | Off. Dev mode admits unsigned loopback GitHub deliveries, widens playground session listing on loopback, and never auto-fires schedules. |
-| `--bearer-token` | On for anything shared. Rotate it like any secret. |
-| `--allow-anonymous` | Only behind a trusted network boundary (e.g. an SSO-authenticating load balancer). Also widens playground session listing/streaming so Slack and webhook sessions appear. Never with account-level connectors. |
-| `--state-root` | A persistent volume, outside any repo. |
+| `--dev` | Leave off. Dev mode admits unsigned loopback GitHub deliveries, widens playground session listing on loopback, and never auto-fires schedules. |
+| `--bearer-token` | Set on shared hosts unless an authenticating proxy is the trust boundary and you use `--allow-anonymous` instead. |
+| `--allow-anonymous` | Use only behind an authenticating network boundary. It also widens playground session access so Slack and webhook sessions appear. |
+| `--state-root` | Place on a persistent volume outside any repo. |
 | `--public-url` | Set when cloud-runtime turns must call back into peers on this host. |
-| `--no-playground` | Optional hardening when no human needs the UI. Also removes the `/` and `/v1/agents` index routes. |
-| `--no-docs` | Removes the documentation site at `/docs`. |
-| `--no-schedules` | Disable cron firing on secondary hosts so schedules run exactly once. |
+| `--no-playground` | Set when no human needs the UI. |
+| `--no-docs` | Set to remove the documentation site at `/docs`. |
+| `--no-schedules` | Set on secondary hosts so schedules run exactly once. |
 
 Schedules fire on their cron cadence (UTC) in production mode. They have
 no cross-host coordination, so enable them on exactly one serving process
 per project.
 
-## Restarts and upgrades
+### Restarts and upgrades
 
-Restarts are safe by design: sessions, event streams, and the SDK
-conversation store are durable under the state root. Two caveats. Parked
-tool approvals don't survive a restart. They resolve as interrupted, and
-you re-run the turn. And reminders created with in-memory `run` handlers
-are disarmed after a restart (`handler_lost_on_restart`). Re-arm them
-from the code path that created them, or use prompt-form reminders.
+Restarts preserve sessions, event streams, and SDK conversation state
+under the state root. Parked approvals and in-memory reminders don't
+survive a restart; re-run or recreate them afterward.
 
-## Observability
+### Observability
 
-`GET /v1/logs` (per agent) exposes recent server log lines: the same ring
-buffer the playground's Logs tab polls. For structured export, author a
-[hook](./reference/hooks.md). Subscribe to `turn.completed`,
-`turn.failed`, and `action.result`, then forward to your metrics system.
-Hook errors are logged, never fatal. For any incident, the session
-streams under the state root are the source of truth:
-`agentkit trajectory --events <file>` summarizes one, and the
-playground renders it.
+Use [`agentkit logs`](./reference/cli.md#logs) for runtime output,
+[hooks](./reference/hooks.md) for metrics export, and
+[session traces](./reference/sessions.md#how-do-i-inspect-a-saved-event-stream)
+for incident review.
 
 ## What's next
 
 Continue with these pages:
 
+- [CLI reference](./reference/cli.md#deploy): deploy, inspect, stop, and
+  rotate hosted agents
+- [Storage](./storage.md): preserve supported records across engine
+  replacements
 - [Channels](./reference/channels.md#auth-policies): the auth policies
   in detail
-- [GitHub guide](./guides/github.md): delivery paths that don't need a
-  public URL
+- [GitHub guide](./guides/github.md): delivery paths without a public URL
 - [Troubleshooting](./troubleshooting.md): the symptom table for when a
   deploy misbehaves