diff --git a/src/content/docs/platform/self-hosting/managed-direct.mdx b/src/content/docs/platform/self-hosting/managed-direct.mdx index 555c668c..a124272c 100644 --- a/src/content/docs/platform/self-hosting/managed-direct.mdx +++ b/src/content/docs/platform/self-hosting/managed-direct.mdx @@ -41,7 +41,7 @@ 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 {VARS.WEB_APP} 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 {VARS.FACTORY_WEB_APP} user settings 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. --- @@ -49,10 +49,10 @@ The Direct backend does not provide per-task container isolation. Each task runs ### 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 index 2ee278a3..84e799cb 100644 --- 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 {VARS.WEB_APP} 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 {VARS.FACTORY_WEB_APP} user settings 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 index d76fa022..caef1529 100644 --- 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 {VARS.WEB_APP} 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 {VARS.FACTORY_WEB_APP} user settings 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 index 67deebce..fa9f01a5 100644 --- 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 {VARS.WEB_APP} 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 {VARS.FACTORY_WEB_APP} user settings, 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,12 +71,9 @@ Open the {VARS.DASHBOARD}, 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 @@ -84,7 +81,7 @@ Open the {VARS.DASHBOARD}, find the new task, and 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 index ea8258c7..db61dff1 100644 --- 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 index 5c640bad..7ceac7e3 100644 --- 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 {VARS.FACTORY_WEB_APP} user settings page, 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 index 6e386261..60efe47a 100644 --- 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 {VARS.WEB_APP} or the Warp app. Both surfaces produce keys that authenticate the CLI and SDK identically. +Create personal and agent keys in the {VARS.WEB_APP} or the Warp app. Create self-hosted worker keys in the {VARS.FACTORY_WEB_APP}. + +### Creating a self-hosted worker API key + +1. Open the {VARS.FACTORY_WEB_APP} user settings page. +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 ![API key management interface in Warp settings](../../../../assets/reference/api-key-management.png)
API key management interface in Warp settings.