warpdotdev · warp-agent-staging · Sep 25, 2026
diff --git a/src/content/docs/platform/self-hosting/managed-direct.mdx b/src/content/docs/platform/self-hosting/managed-direct.mdx
@@ -41,18 +41,18 @@ The Direct backend does not provide per-task container isolation. Each task runs
 * **A worker host** with write access to `workspace_root` (defaults to `/var/lib/oz/workspaces`).
 * **The `oz-agent-worker` binary** installed on the worker host. The Direct backend runs the worker itself on the host rather than in a container, so install it via [Homebrew or a prebuilt binary](/platform/self-hosting/managed-docker/#install-and-run-the-worker).
 * **The {VARS.WARP_AGENT_CLI}** installed and available in `PATH` on the worker host (or specify `oz_path` in the config file). See [Installing the CLI](/reference/cli/#installing-the-cli).
-* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
+* **A self-hosted worker API key** - Create one in the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings</a> so the worker can authenticate as your team. See [creating a self-hosted worker API key](/reference/cli/api-keys/#creating-a-self-hosted-worker-api-key) for the full flow.
 
 ---
 
 ## Setup
 
 ### 1. Set your API key
 
-Export the API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
+Export the self-hosted worker API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
 
 ```bash
-export WARP_API_KEY="your_agent_api_key"
+export WARP_API_KEY="YOUR_API_KEY"
 ```
 
 ### 2. Start the worker with the Direct backend

diff --git a/src/content/docs/platform/self-hosting/managed-docker.mdx b/src/content/docs/platform/self-hosting/managed-docker.mdx
@@ -27,7 +27,7 @@ This page covers the [managed architecture](/platform/self-hosting/#managed-arch
 * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team.
 * **A machine to run the worker** — A VM, server, or local machine running Linux (recommended for production). For testing, macOS and Windows hosts running Docker Desktop work.
 * **Docker installed** — The worker uses Docker to spawn task containers. The Docker daemon must run Linux containers (Windows containers are not supported). Verify with `docker info`.
-* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
+* **A self-hosted worker API key** - Create one in the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings</a> so the worker can authenticate as your team. See [creating a self-hosted worker API key](/reference/cli/api-keys/#creating-a-self-hosted-worker-api-key) for the full flow.
 
 :::caution
 Task containers require a **linux/amd64** or **linux/arm64** Docker daemon. The worker host itself can be any OS — Docker Desktop on macOS and Windows runs a Linux VM that satisfies this requirement.
@@ -47,10 +47,10 @@ docker info
 
 ## Set your API key
 
-Export your agent API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
+Export your self-hosted worker API key so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}:
 
 ```bash
-export WARP_API_KEY="your_agent_api_key"
+export WARP_API_KEY="YOUR_API_KEY"
 ```
 
 ## Install and run the worker

diff --git a/src/content/docs/platform/self-hosting/managed-kubernetes.mdx b/src/content/docs/platform/self-hosting/managed-kubernetes.mdx
@@ -35,7 +35,7 @@ Deploy the `oz-agent-worker` daemon into a Kubernetes cluster with the included
   * Allow the task namespace to create Jobs with a **root init container**, unless you enable native image volumes with `kubernetesBackend.useImageVolumes=true`.
   * Grant the worker these namespace-scoped permissions: `create`, `get`, `list`, `watch`, `delete` on `jobs`; `get`, `list`, `watch` on `pods`; `get` on `pods/log`; `list` on `events`.
 * **[Helm](https://helm.sh/docs/intro/install/)** installed locally, plus `kubectl` authenticated against the target cluster.
-* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. Binding the key to a cloud agent doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/).
+* **A self-hosted worker API key** - Create one in the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings</a> so the worker can authenticate as your team. See [creating a self-hosted worker API key](/reference/cli/api-keys/#creating-a-self-hosted-worker-api-key) for the full flow.
 
 ---
 
@@ -56,7 +56,7 @@ The chart does not create CRDs or cluster-scoped RBAC resources.
 ### 1. Set your API key and namespace
 
 ```bash
-export WARP_API_KEY="your_agent_api_key"
+export WARP_API_KEY="YOUR_API_KEY"
 ```
 
 Create the namespace if it doesn't exist:

diff --git a/src/content/docs/platform/self-hosting/quickstart.mdx b/src/content/docs/platform/self-hosting/quickstart.mdx
@@ -20,7 +20,7 @@ This quickstart sets up the [managed architecture](/platform/self-hosting/#manag
 
 * **Enterprise plan with self-hosting enabled** — [Contact sales](https://www.warp.dev/contact-sales) if self-hosting is not yet enabled for your team.
 * **A Linux machine with Docker** — A VM, server, or local machine with the Docker daemon running Linux containers. Verify with `docker info`. Docker Desktop on macOS or Windows works for testing.
-* **An agent API key** — Create one in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> so the worker can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM}. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. See [API Keys](/reference/cli/api-keys/) for the full creation flow.
+* **A self-hosted worker API key** - In the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings</a>, click **Generate new token** and select **Self-hosted worker**. The key is tied to your team and does not require an agent selection. See [creating a self-hosted worker API key](/reference/cli/api-keys/#creating-a-self-hosted-worker-api-key) for the full flow.
 * **The {VARS.WARP_AGENT_CLI}** (for routing a test run) — See [Installing the CLI](/reference/cli/#installing-the-cli).
 
 ---
@@ -31,10 +31,10 @@ _~10 minutes_
 
 ### 1. Export your API key
 
-Export the agent API key so the worker container can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM} automatically:
+Export the self-hosted worker API key so the worker container can authenticate to the {VARS.WARP_AUTOMATION_PLATFORM} automatically:
 
 ```bash
-export WARP_API_KEY="your_agent_api_key"
+export WARP_API_KEY="YOUR_API_KEY"
 ```
 
 ### 2. Start the worker
@@ -71,20 +71,17 @@ Open the <a href={VARS.WEB_APP_URL}>{VARS.DASHBOARD}</a>, find the new task, and
 
 ## Next steps
 
-* [Unmanaged quickstart](/platform/self-hosting/unmanaged/#unmanaged-quickstart) — ~5-minute CLI-only path: run `oz agent run` in your CI, Kubernetes pod, or dev box with no worker daemon and no Docker requirement.
+* [Self-hosting overview](/platform/self-hosting/) — Compare managed and unmanaged architectures and choose a backend.
 * [Managed: Docker](/platform/self-hosting/managed-docker/) — Full Docker backend setup, including private registries, volume mounts, and runtime configuration.
-* [Environments](/platform/environments/) — Define a repository, Docker image, and setup commands so agents have a reproducible workspace for every run.
 * [Routing runs to self-hosted workers](/platform/self-hosting/#routing-runs-to-self-hosted-workers) — How to route tasks from schedules, integrations (Slack, Linear), the API, and the {VARS.WEB_APP}.
-* [Managed: Kubernetes](/platform/self-hosting/managed-kubernetes/) — Deploy workers into a Kubernetes cluster with Helm.
-* [Self-hosted worker reference](/platform/self-hosting/reference/) — All CLI flags and config file options.
 
 ## Troubleshooting
 
 **Worker won't start**\
 Verify Docker is running (`docker info`) and that the daemon platform is `linux/amd64` or `linux/arm64`. Musl-based (Alpine) worker hosts are not supported.
 
 **Worker won't connect**\
-Verify your API key has team scope. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details.
+Verify you created a **Self-hosted worker** key and that it has not expired. Ensure the machine has outbound internet access to `oz.warp.dev:443`. Increase log verbosity with `--log-level debug` to see connection details.
 
 **Task stays queued and never runs**\
 Confirm the `--host` value you passed to `oz agent run-cloud` matches your `--worker-id` exactly (case-sensitive). Check that the worker's team matches the team creating the task.

diff --git a/src/content/docs/platform/self-hosting/reference.mdx b/src/content/docs/platform/self-hosting/reference.mdx
@@ -16,7 +16,7 @@ The following flags are available when starting the worker.
 ### Required
 
 * `--worker-id` — A string identifying this worker. This is the value you pass to `--host` when routing tasks. Choose something meaningful for your team (e.g., `prod-runner-1` or `ci-worker`). Multiple workers can share the same ID for load balancing.
-* `--api-key` or `WARP_API_KEY` env var — Your agent API key for authentication. You can bind the key to any cloud agent — that choice doesn't restrict which agents can run on the worker. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable.
+* `--api-key` or `WARP_API_KEY` env var — Your [self-hosted worker API key](/reference/cli/api-keys/#creating-a-self-hosted-worker-api-key) for team authentication. When running via Docker, pass it as `-e WARP_API_KEY="..."`. When running the binary directly, use `--api-key` or the environment variable.
 
 ### Optional
 

diff --git a/src/content/docs/platform/self-hosting/troubleshooting.mdx b/src/content/docs/platform/self-hosting/troubleshooting.mdx
@@ -60,8 +60,8 @@ A successful preflight validates the configured pod shape, not task-specific ima
 
 **Fix:**
 
-1. Confirm your API key is correct, not expired, and has team scope.
-2. Regenerate the API key in **Settings** > **Cloud platform** > **API keys** if you suspect it's invalid.
+1. Confirm you created a **Self-hosted worker** API key and that it has not expired.
+2. If you suspect the key is invalid, open the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings page</a>, click **Generate new token**, and select **Self-hosted worker** to create a replacement.
 3. Ensure the host has outbound internet access to `oz.warp.dev:443`.
 4. Check that no firewall rules are blocking WebSocket connections to `wss://oz.warp.dev`.
 5. Increase log verbosity with `--log-level debug` to see connection details.

diff --git a/src/content/docs/reference/cli/api-keys.mdx b/src/content/docs/reference/cli/api-keys.mdx
@@ -1,7 +1,8 @@
 ---
 title: "API keys for the {{WARP_AGENT_CLI}}"
 description: >-
-  Create and manage API keys for authenticating the {{WARP_AGENT_CLI}} and cloud agents.
+  Create and manage API keys for authenticating the {{WARP_AGENT_CLI}}, cloud agents, and
+  self-hosted workers.
 sidebar:
   label: "API keys"
 ---
@@ -11,18 +12,33 @@ import { VARS } from '@data/vars';
 The {VARS.WARP_AGENT_CLI} (the `oz` binary) is being deprecated in favor of the {VARS.WARP_CLI} (the `warp` binary). `oz` commands remain supported through the end of September 2026. See the [Warp Agent CLI docs](/agents/cli/) for what is available today.
 :::
 
-API keys let the {VARS.WARP_AGENT_CLI} and cloud agents authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments.
+API keys let the {VARS.WARP_AGENT_CLI}, cloud agents, and self-hosted workers authenticate without human interaction. Use API keys for CI pipelines, headless servers, VMs, Codespaces, containers, and other automated environments.
 
 ## Personal vs. agent keys
 
-Every API key is either a **personal API key** or an **agent API key**.
+Choose a key type based on what needs to authenticate:
 
 * **Personal API keys** authenticate as you. Runs use your GitHub permissions, draw from your credit pool, and inherit your account's [skills](/agents/capabilities/skills/). Use a personal key when the run should act on your behalf — for example, developer-triggered API automation, or the [Enterprise Analytics API](/enterprise/enterprise-features/analytics-api/), which only accepts personal keys.
 * **Agent API keys** run as a [cloud agent](/platform/agents/) on your team. Use an agent key for scheduled jobs, integrations (Slack, Linear, GitHub Actions), SDK-triggered runs, and other automation that isn't tied to a specific user. Billing and GitHub permissions are scoped to the team rather than to you.
 
+## Self-hosted worker API keys
+
+Self-hosted worker API keys authenticate managed `oz-agent-worker` daemons as your team. Use this key type with the [Docker](/platform/self-hosting/managed-docker/), [Kubernetes](/platform/self-hosting/managed-kubernetes/), or [Direct](/platform/self-hosting/managed-direct/) backend. You don't need to select an agent when creating one.
+
 ## Creating an API key
 
-You can create an API key in either the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically.
+Create personal and agent keys in the <a href={`${VARS.WEB_APP_URL}/settings`}>{VARS.WEB_APP}</a> or the Warp app. Create self-hosted worker keys in the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP}</a>.
+
+### Creating a self-hosted worker API key
+
+1. Open the <a href={`${VARS.FACTORY_WEB_APP_URL}/settings`}>{VARS.FACTORY_WEB_APP} user settings page</a>.
+2. In the API keys section, click **Generate new token**.
+3. Under "Type," select **Self-hosted worker**. The key is tied to your team and does not require an agent selection.
+4. Enter a name for the key and choose when it expires.
+5. Click **Create key**.
+6. In the "Copy API key" dialog, copy the key and store it securely. The key is shown only once.
+
+**Expected outcome:** The key appears in the API keys list with a **Team** badge and the expiration you selected.
 
 ### From the web app (recommended)
 
@@ -45,6 +61,8 @@ You can create an API key in either the <a href={`${VARS.WEB_APP_URL}/settings`}
 6. Click **Create key**.
 7. Copy the raw API key and store it securely. **You won't be able to see it again after closing the dialog.**
 
+To create a self-hosted worker key, use the [{VARS.FACTORY_WEB_APP} flow](#creating-a-self-hosted-worker-api-key).
+
 <figure>
 ![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
 <figcaption>API key management interface in Warp settings.</figcaption>