User Token

A USER_TOKEN is a durable, per-user bearer credential (prefixed out_) that authenticates agents and the CLI without a browser flow. Use it for cloud agents over MCP and for the CLI when it runs separately from Overlord Desktop.

Create a token

USER_TOKENs are managed in the web app and Overlord Desktop, or from the CLI.

  1. Open Settings → Tokens.
  2. Enter a label (for example Claude Cloud or Production) and create the token.
  3. Copy the token immediately — it is shown only once and starts with out_.

From the terminal, mint one with the CLI:

ovld user-token create --label ci --expires-in 90d
ovld user-token list
ovld user-token revoke <id>

Tokens expire only if you set an expiry (--expires-in, or --no-expiry for a durable token). Revoke a token from Settings → Tokens or with ovld user-token revoke; revocation takes effect immediately.

MCP

Use a USER_TOKEN for cloud or hosted agents over the MCP server when OAuth is not reliable in that runtime (for example Claude Code or other headless environments).

Set the environment variables

Add both variables to the agent runtime environment. Copy your MCP URL from Settings → Agents & MCP:

OVERLORD_USER_TOKEN=<paste out_ token>
OVERLORD_MCP_URL=<your Overlord MCP URL>

The workspace is derived from the token's membership. Mission-scoped operations infer the workspace from mission display ids such as 1:1263.

Whitelist domains in cloud environments

If your platform enforces an outbound domain allowlist, the agent runtime must be allowed to reach Overlord. Add both the apex domain and its subdomains:

ovld.ai
*.ovld.ai

Without the allowlist entry, the runtime can hold a valid token but still fail to connect because outbound requests to the MCP URL are blocked.

CLI

Use a USER_TOKEN when the CLI runs in a separate container or execution target from where Overlord Desktop is installed. In that case there is no shared Desktop session to reuse, so the CLI needs its own durable credential.

There are two ways to provide it.

Persist it with the CLI

Save the token once and the CLI uses it for every backend call — no env vars and no Desktop required:

npm install -g --no-fund overlord-cli
ovld auth login --token <out_ token>
ovld auth status

Provide it via environment variables

For ephemeral containers and CI runners, set the token (and backend URL) in the environment instead of persisting it. The token env vars are checked in the order OVERLORD_USER_TOKEN, OVLD_USER_TOKEN, USER_TOKEN and take precedence over stored credentials:

OVERLORD_USER_TOKEN=<out_ token>          # durable bearer token; best for headless/CI
OVERLORD_BACKEND_URL=<your Overlord URL>  # backend the CLI sends /api/* requests to

The same domain allowlisting applies: if the container restricts outbound traffic, allow ovld.ai and *.ovld.ai so the CLI can reach the backend API.