> For the complete documentation index, see [llms.txt](/llms.txt). > A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt). --- title: Operate serverless endpoints description: Validate, promote, inspect, disable, recover, rotate, and roll back immutable serverless deployments. last_verified: 2026-07-09 --- Use this guide after a provider has deployed your serverless endpoint. You will move an immutable provider version through validation and activation, keep dispatch recoverable, and diagnose the failures surfaced by the AGNT5 CLI. A **provider version** identifies immutable code at Cloudflare, Vercel, or another host. An **AGNT5 deployment** stores that version's endpoint, manifest, signing configuration, component routes, and durable execution state. ## Promote an immutable version Promote every provider version through the same sequence: 1. Validate the endpoint without changing AGNT5 state: ```bash agnt5 serverless validate https:// ``` 2. Import the provider version without changing active component routes: ```bash export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)" agnt5 serverless sync https:// \ --provider \ --env production \ --immutable-ref \ --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \ --activate=false ``` 3. Copy the AGNT5 deployment ID and gate promotion: ```bash agnt5 serverless status \ --deployment-id \ --verify ``` 4. Re-run sync with the same provider and immutable reference, changing only `--activate=true`. Repeated sync calls are idempotent for the same provider version. A different immutable reference creates a distinct AGNT5 deployment version. ## Interpret verification **`agnt5 serverless status --verify`** exits nonzero when a required check fails. | Check | Required state | What failure means | | --- | --- | --- | | `manifest_health` | Healthy | AGNT5 cannot fetch or accept the live manifest. | | `dispatch` | Enabled | New runs are blocked for this deployment. | | `signing` | Configured | AGNT5 has no signing-secret reference for invoke requests. | | `protocol` | `workerless.v1` | The endpoint exposes an unsupported protocol. | | `manifest_compatibility` | Match | The live manifest differs from the registered immutable deployment. | Use `--output json` when a CI job needs structured status and verification output: ```bash agnt5 serverless status \ --deployment-id \ --verify \ --output json ``` ## Resolve route-owner conflicts An environment can have one active owner for a component route such as `workflow:hello`. Sync returns a conflict when another deployment owns a matching route. Choose one response: - **Inspect only**: keep `--activate=false` and target the candidate directly with `--deployment-id` during testing. - **Rename the component**: use a distinct component name when both deployments should remain active. - **Replace the owner**: add `--replace-route-owners` only when the candidate should take over every conflicting route in that sync request. Replacing route owners changes where future environment-routed runs execute. Runs already pinned to a deployment remain pinned to that deployment. ## Disable and recover dispatch Disable new dispatch without deleting the endpoint or its manifest: ```bash agnt5 serverless disable \ --deployment-id \ --reason "provider incident" ``` Inspect the disabled deployment while it remains recoverable: ```bash agnt5 serverless status --deployment-id ``` Validate the live endpoint and inspect status before re-enabling. A disabled deployment cannot pass full verification because the `dispatch` check is intentionally failed. ```bash agnt5 serverless validate https:// agnt5 serverless status --deployment-id agnt5 serverless enable \ --deployment-id agnt5 serverless status \ --deployment-id \ --verify ``` `enable` refuses an incompatible live manifest. `--allow-incompatible` bypasses that protection and should be reserved for a manually reviewed recovery. ## Rotate the signing secret Treat signing-secret rotation as a new provider release so AGNT5 and the provider never disagree about the active secret. 1. Disable the affected AGNT5 deployment if rotation responds to a suspected leak. 2. Generate a new secret in a private local file. 3. Replace the provider secret and deploy a new immutable provider version. 4. Validate the new endpoint. 5. Sync the new immutable reference with the new secret and `--activate=false`. 6. Require **`status --verify`**, then activate the new AGNT5 deployment. 7. Keep the old deployment disabled until its active runs have drained. Pass the value through `--signing-secret-env` or use `--signing-secret-ref secret:`. Avoid `--signing-secret ` in shared shell history or CI logs. ## Roll back a provider release Provider rollback and AGNT5 route rollback are separate controls. 1. Disable the failing AGNT5 deployment to stop new dispatch. 2. Roll the provider endpoint back to the previous immutable version with the provider CLI. 3. Validate the endpoint after provider rollback. 4. Sync the previous provider version and signing configuration with `--activate=false`. 5. Verify the recovered AGNT5 deployment. 6. Activate the recovered deployment. For Cloudflare Workers, use **`wrangler rollback`** or deploy a selected version with Wrangler. For other hosts, use the provider-native rollback command. AGNT5 does not wrap provider rollback. ## Diagnose common failures | Symptom | Check | Resolution | | --- | --- | --- | | No project context | `.agnt5/project-ref` | Run **`agnt5 link`** in the provider project. | | Manifest is unreachable | Endpoint and manifest path | Open `https:///.well-known/agnt5`, then check provider logs and access protection. | | Manifest returns `401` or `403` | Provider protection headers | Pass protected access with `--invoke-header-env name=ENV_VAR`. | | Unsupported protocol | `protocol_version` | Deploy an SDK that serves `workerless.v1`. | | Signing is not configured | Sync flags | Re-sync with `--signing-secret-env` or `--signing-secret-ref`. | | Manifest drift | Live and registered hashes | Deploy and sync a new immutable version; do not mutate registered code in place. | | Dispatch is disabled | Status reason | Fix the incident, verify compatibility, then run **`serverless enable`**. | | Route-owner conflict | Environment component owners | Import inactive, rename the component, or intentionally use `--replace-route-owners`. | | Invoke timeout | Provider duration and AGNT5 timeout | Keep `request_timeout_ms` below the provider cap and reserve time with `yield_before_timeout_ms`. | ## Next steps - [Deploy to Cloudflare Workers](/docs/integrations/cloudflare-workers.md): exercise the full lifecycle from a new project. - [Serverless CLI reference](/cli/serverless.md): inspect exact command flags and aliases. - [Environments](/docs/run/environments.md): understand environment pointers and promotion. - [Serverless endpoints](/docs/run/serverless-endpoints.md): review the host matrix and beta limits.