@cursor/july 0.1.111 → 0.1.113

package/docs/deployment.md

@@ -1,76 +1,31 @@
 ---
 title: "Deployment"
-description: "Deploy the Agent SDK with Cursor-managed hosting or on infrastructure you control."
+description: "Deploy an Agent SDK project from Git with Cursor-managed hosting, or run one secure process on your own infrastructure."
 ---
 
 # Deploy the Agent SDK
 
-Both options run the same agent project and HTTP API. Channel delivery
-paths differ. Cursor-managed hosting is preferred for most agents.
+Deployment turns a pushed Agent SDK project into a stable service.
+Cursor-managed hosting builds the selected Git ref and operates the
+runtime; self-hosting gives you control of the network, process, and
+filesystem.
+
+## Choose managed hosting or self-hosting
 
 | 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 as a team member, or use a team service-account API key with agent access.
-- 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.
+| Cursor-managed hosting | You want the shortest path from Git to a running agent | Source, declared egress, secrets, and agent behavior |
+| Self-hosting | You need your own network, proxy, filesystem, or process controls | The Node process, TLS, auth, secrets, state, monitoring, and upgrades |
 
-The base policy already covers the hosts the platform itself uses: the
-Cursor API (`api.cursor.com` and `api2.cursor.sh`), GitHub and GitLab,
-the npm and Yarn registries, Slack, and Cursor's own artifact storage.
-Declare a domain only for a host your own code reaches.
+The rest of this guide starts with managed hosting. The
+[self-host recipe](#self-host-securely) uses the same project and HTTP
+API.
 
-`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.
+## Deploy from Git
 
-For `defineConnection({ url, oauth: true })`, declare
-`MCP_OAUTH_<CONNECTION>_*` in `secretNames`. Finish Connect for the
-current process. Run `agent-sdk mcp oauth <connection> --store` and
-redeploy so the next pod sees the secrets.
-See [Host MCP OAuth](./guides/mcp-oauth.md).
-
-Run `agent-sdk 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:
+Commit and push the exact ref you want to run, then sign in, validate,
+and deploy. The command waits until the engine is running and prints
+the stable deployment URL.
 
 ```bash
 cd my-agent
@@ -80,9 +35,9 @@ agent-sdk validate
 agent-sdk 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:
+`deploy` reads from Git; it does not upload your working tree. Inside a
+checkout, it infers the HTTPS origin, current ref, agent path, and slug.
+Pass them explicitly when the checkout is not the source you want:
 
 ```bash
 agent-sdk deploy \
@@ -92,362 +47,161 @@ agent-sdk deploy \
   --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.
+The source repository must be available through the team's repository
+integration, and a nested `--path` must contain an installable Agent SDK
+project.
 
-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.
+## Add egress and secrets
 
-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.
+Declare the external hosts and secret names the agent needs. After the
+deployment exists, set each value at the hidden prompt and follow the
+CLI or dashboard instruction to redeploy.
 
-`--all` creates a separate deployment for each child. Self-host when the
-agents must share one multi-agent process. Cloud-runtime peers on that
-host need `--public-url` and `--bearer-token`. Walkthrough:
-[Agent-to-agent](./guides/agent-to-agent.md#how-do-i-wire-two-agents).
-
-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:
+```ts
+// agent/agent.ts
+import { defineAgent } from "@cursor/july";
 
-```bash
-agent-sdk deployments
-agent-sdk deployment weather-agent
-agent-sdk logs --prod --slug weather-agent
+export default defineAgent({
+  hosting: {
+    egressDomains: ["api.weather.example.com"],
+    secretNames: ["WEATHER_API_KEY"],
+  },
+});
 ```
 
-### Set deployment secrets
-
-A deployment must exist before you can set its secrets. Pass names only.
-Enter values at the hidden prompt, or pipe one line per name:
-
 ```bash
 agent-sdk secrets set weather-agent WEATHER_API_KEY
 agent-sdk secrets list weather-agent
 agent-sdk deploy --dir . --slug weather-agent
 ```
 
-`secrets list` returns names and creation times, never values. The
-engine reads secret changes on its next deploy.
-
-Do not pass `NAME=VALUE` on the command line. That form lands in shell
-history and in agent-captured terminals. The CLI refuses it unless you
-add `--from-argv`. For non-interactive input without argv, redirect a
-file or pipe stdin.
-
-### Credential output in terminals
+Commit secret names, never values. `secrets set` accepts names and reads
+values without echoing them; `secrets list` returns names and creation
+times only. Do not pass `NAME=VALUE`, print a secret to verify it, or
+put names beginning with reserved `CURSOR_` in `secretNames`.
 
-Treat any command that prints a secret as a credential event. Keep it
-out of agent-captured terminals when you can.
+Enter egress hosts without schemes, ports, or paths. The
+[Host MCP OAuth guide](./guides/mcp-oauth.md) owns the extra secret and
+egress steps for OAuth-backed MCP servers.
 
-| Command | What prints |
-| --- | --- |
-| `secrets set` / `secrets list` | Names only. Values never print. |
-| First `deploy` / `rotate-token` | Full alias token once. Save it outside the agent transcript; it cannot be retrieved later. |
-| `deployment --json` | May include short-lived `engineAccess.headers`. Treat JSON as a credential. |
+## Use the hosted agent
 
-Do not verify secrets with `echo "$SECRET"`, `printenv`, or by pasting
-values into chat. Use `secrets list` for names, then redeploy and exercise
-the feature that needs the secret.
-
-### Choose durable storage
-
-Hosted filesystem state can reset during a deploy or runtime
-replacement. Prefer
-`cursorHostedStorage` so records survive replace.
-Do not put platform storage or deployment-identity names in
-`hosting.secretNames`. Self-host with your own `defineStorage` backend or
-a persistent `--state-root` when the complete filesystem must survive.
-
-### Use the hosted agent
-
-The CLI handles authentication for `--prod` commands. External HTTP
-clients that hit the stable alias URL must send `X-Agent-Alias-Token` on
-every request. Authored channel auth still runs after that gate.
-
-Use `publicEndpoint()` on a custom channel that verifies its own provider
-signature. Cursor then serves that channel path without the alias token.
-The built-in session API still requires the token.
-
-Use a relay or self-host when the channel cannot authenticate requests
-itself.
-
-Use `--prod` with the normal client commands:
+The `--prod` commands authenticate through your Cursor credential and
+connect to the deployment directly. Open the playground, run a turn,
+then inspect the same session in logs.
 
 ```bash
 agent-sdk playground --prod --slug weather-agent
-agent-sdk chat --prod --slug weather-agent
-agent-sdk run --prod --slug weather-agent --message "Forecast for Paris"
-agent-sdk sessions --prod --slug weather-agent
+agent-sdk run --prod --slug weather-agent \
+  --message "Forecast for Paris"
 agent-sdk logs --prod --slug weather-agent
+agent-sdk deployment 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 `agent-sdk 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:
+External HTTP clients use the stable alias URL and 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:
+The first deploy prints this token once. Store it outside terminal
+transcripts; it cannot be retrieved later. If it is lost or exposed,
+`agent-sdk rotate-token weather-agent` replaces it and invalidates the
+old value.
 
-```bash
-agent-sdk rotate-token weather-agent
-```
+`deployment --json` can include short-lived access headers, so treat
+that output as a credential too.
 
-### Connect GitHub
+For a custom webhook whose provider cannot send the alias token, use
+`publicEndpoint()` only when the channel verifies the provider
+signature. That opens the custom channel path, not the built-in session
+or tool APIs. See [Webhooks](./guides/webhooks.md).
 
-Let the hosted engine pull Cursor SCM events. Repeat
-`--cursor-events-repo` for each repository whose events should wake the
-agent:
+## Update the deployment
 
-```bash
-agent-sdk 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 uses a dedicated Socket Mode app:
-
-```ts
-import { slackChannel } from "@cursor/july/channels/slack";
-
-export default slackChannel({ envPrefix: "PR_APPROVER" });
-```
-
-Provision the dedicated app from the dashboard. Open the deployment
-under **Deployed Agents** at
-[cursor.com/dashboard](https://cursor.com/dashboard), switch to
-**Details**, and expand **Slack** under **Integrations**. **Add to
-Slack** connects the workspace with a one-time authorization, and
-**Create Slack app** creates and installs the app, then stores its
-tokens as deployment secrets automatically. Redeploy when prompted so
-the running agent picks them up. See
-[Provision from the dashboard](./guides/slack.md#provision-from-the-dashboard)
-for the walkthrough, including workspace-admin approval.
-
-If you created the Slack app by hand instead, set its tokens as
-deployment secrets yourself. The prefix selects the secret names:
-
-```bash
-agent-sdk secrets set pr-approver \
-  PR_APPROVER_SLACK_BOT_TOKEN \
-  PR_APPROVER_SLACK_APP_TOKEN
-agent-sdk 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, stop, or delete a deployment
-
-Redeploy the same slug after pushing a new Git ref. The stable alias
-continues to point at the latest deploy. Follow the same source rules
-from [Deploy from Git](#deploy-from-git).
+Push the new ref and deploy the same slug. The stable URL remains while
+the new generation replaces the previous one.
 
 ```bash
-agent-sdk deploy --dir /path/to/my-agent --slug weather-agent
-agent-sdk stop weather-agent
-agent-sdk delete weather-agent
+agent-sdk deploy --dir . --slug weather-agent
 ```
 
-`stop` waits for the deployment to stop unless you pass `--no-wait`.
-`delete` removes the deployment and waits until it is gone.
-See the [CLI reference](./reference/cli.md#deploy) for the full command
-reference.
-
-## Self-host the Agent SDK
-
-The Agent SDK runs as a Node HTTP server on Node 22.13 or newer. You can host
-it on a VM or container platform.
+A redeploy replaces its source, Cursor-event repository list, and any
+egress domains supplied through CLI flags. Repass
+`--cursor-events-repo` and other CLI-only settings each time. Keep
+source-controlled egress in the `hosting` block when possible.
 
-### The security model in one minute
+Use `agent-sdk deployment weather-agent` and
+`agent-sdk logs --prod --slug weather-agent` to inspect a rollout.
+The [CLI reference](./reference/cli.md#deploy) owns `--no-wait`,
+multi-agent deployment, stop, and delete behavior.
 
-`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 |
-| --- | --- | --- |
-| Cursor API key | model turns, cloud runtime, Cursor account MCP connections | `agent-sdk login` (stores a revocable key), `CURSOR_API_KEY`, `CURSOR_SERVICE_ACCOUNT_KEY`, or `--api-key` / `serve({ apiKey })` |
-| Slack tokens | Slack channels | `<PREFIX>_SLACK_BOT_TOKEN` + `<PREFIX>_SLACK_APP_TOKEN` per agent |
-| GitHub webhook secret | delivery signature verification | `GITHUB_WEBHOOK_SECRET`, same value on server and signer |
-| 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 | env vars your `mcp-connections/*.ts` read, or host OAuth secrets from hosted Connect / `agent-sdk mcp oauth <name> --store` (`MCP_OAUTH_*`; see [Host MCP OAuth](./guides/mcp-oauth.md)) |
+## Keep state across replacements
 
-Use a dedicated Cursor key per host. `agent-sdk 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.
+Managed hosting persists framework-owned session, KV, and file state
+across normal runtime replacements. Files written elsewhere on the
+engine's local filesystem are disposable; use `ctx.host.kv` or
+`ctx.host.files` for durable application state.
 
-### State
+Parked approvals and in-memory reminder handlers do not survive a
+restart. Run the turn again or recreate the reminder after a
+replacement.
 
-Place `--state-root` on a persistent volume outside the agent
-repository, and back it up. Sessions survive restarts only when their
-state does. See [Sessions](./reference/sessions.md) for persistence
-and layout details.
+## Self-host securely
 
-### A single box
-
-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:
+Run Agent SDK under Node 22.13 or newer, never Bun. One supervised
+process can serve every agent under a directory while a persistent
+state root keeps sessions across restarts.
 
 ```bash
 export CURSOR_API_KEY="<cursor-api-key>"
 export AGENT_SDK_BEARER_TOKEN="$(openssl rand -hex 32)"
 
-# the server: all agents under one port
-agent-sdk serve --dir /srv/agents --port 3000 --host 127.0.0.1 \
+agent-sdk serve \
+  --dir /srv/agents \
+  --host 127.0.0.1 \
+  --port 3000 \
   --state-root /var/lib/agent-sdk \
   --bearer-token "$AGENT_SDK_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.
+Before exposing the host:
 
-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.
+- Put TLS or an authenticating proxy in front of the loopback server.
 
-```bash
-export GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
-agent-sdk github doctor --install
-gh auth login
+- Keep `--bearer-token` on shared hosts. Use `--allow-anonymous` only
+  behind a proxy that authenticates every caller.
 
-# GitHub agents only: ONE forwarder relaying live deliveries to loopback
-GITHUB_TOKEN= GH_TOKEN= \
-  agent-sdk github forward --dir /srv/agents --repo owner/repo
-```
+- Mount `--state-root` on a persistent volume outside the agent
+  repository and back it up.
 
-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.
+- Inject credentials at startup instead of baking them into an image.
 
-Health checks: `GET /v1/health` at the host level, and each agent also
-serves `/<slug>/v1/health`.
+- Run the process under a supervisor and enable schedules on exactly
+  one serving process per project.
 
-### Containers
+Containers use the same command with `--host 0.0.0.0`, a mounted state
+volume, and an authenticating network boundary. The
+[Channels reference](./reference/channels.md#auth-policies) covers
+per-caller and channel-specific auth.
 
-Build the image with Node 22.13 or newer, the agent source, and its
-package dependencies. Run `agent-sdk serve` as a non-root user:
+## Observability
 
-```bash
-agent-sdk serve --dir /srv/agents --mode multi \
-  --host 0.0.0.0 --port 3000 \
-  --state-root /var/lib/agent-sdk \
-  --bearer-token "$AGENT_SDK_BEARER_TOKEN"
-```
-
-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
-
-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
-credential:
-
-```bash
-agent-sdk serve --dir /srv/agents
-# index at /, each agent at /<slug>/v1/*, /<slug>/playground
-```
-
-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 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
-
-Use these settings in production:
-
-| Flag | In production |
-| --- | --- |
-| `--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` | 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 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
-
-Use [`agent-sdk logs`](./reference/cli.md#logs) for runtime output,
-[OpenTelemetry](./guides/opentelemetry.md) for OTLP traces and metrics,
-[hooks](./reference/hooks.md) for in-process subscribers, and
+Use `agent-sdk logs --prod` for runtime output,
+[OpenTelemetry](./guides/opentelemetry.md) for traces and metrics, 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
-- [Channels](./reference/channels.md#auth-policies): the auth policies
-  in detail
-- [GitHub guide](./guides/github.md): delivery paths without a public URL
-- [Troubleshooting](./troubleshooting.md): the symptom table for when a
-  deploy misbehaves
+for one conversation.
+
+## Related
+
+- [CLI reference](./reference/cli.md#deploy): inspect, update, stop,
+  delete, and rotate deployments
+- [GitHub](./guides/github.md): Cursor-event repositories and direct
+  webhook delivery
+- [Slack](./guides/slack.md): provision a dedicated hosted Slack app
+- [Host MCP OAuth](./guides/mcp-oauth.md): persist OAuth credentials
+  across hosted replacements
+- [Troubleshooting](./troubleshooting.md): diagnose failed or stale
+  deployments