Configuration - Agent

Deploy and configure the CLI auth server environment variables for production and local development.

4 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Overview

The CLI auth server (agent/server) implements OAuth2 device flow so the OpenQuok CLI can obtain tokens without embedding OAuth client secrets in the CLI.

While short-lived state lives in Postgres, token exchange is proxied to the OpenQuok API.

In OpenQuok production, the flow is split across two Vercel projects in the same monorepo:

Role	Package	Host	Examples
API (CLI polling, token exchange)	agent/server	cli-auth.openquok.com	POST /device/code, POST /device/token
Browser (OAuth callback)	web	www.openquok.com	GET /cli/device/verify, GET /cli/device/callback

The auth server sets BROWSER_ORIGIN so verification_uri and the OAuth redirect_uri point at the web app. Then, the web app proxies to the auth server using CLI_AUTH_SERVER_URL (see Configuration - Web).

For local development, copy the development template to agent/server/.env.development.local.

For production deploys and Vercel env sync, copy the production template to agent/server/.env.production.local.

NODE_ENV=development
SERVER_URL=http://localhost:3111
DATABASE_URL=postgresql://openquok:openquok@localhost:5432/openquok_cli_auth

Warning

SERVER_URL is the API origin the CLI calls (OPENQUOK_AUTH_SERVER defaults to this in production). Use the correct scheme (http vs https), host, and no trailing slash.

Warning

The OAuth app redirect / callback URL must match where the browser lands after approval — not necessarily the same host as SERVER_URL:

OpenQuok production — register https://www.openquok.com/cli/device/callback. Set BROWSER_ORIGIN=https://www.openquok.com on the auth server and CLI_AUTH_SERVER_URL=https://cli-auth.openquok.com on the web app.
Local (auth server only) — leave BROWSER_ORIGIN unset so browser steps stay on http://localhost:3111/device/verify and http://localhost:3111/device/callback.
Self-hosted — set BROWSER_ORIGIN to your web origin and register BROWSER_ORIGIN/cli/device/callback on the OAuth app, or use a single host (omit BROWSER_ORIGIN) and register SERVER_URL/device/callback.

Note

This page is for who want to host own CLI Auth server. Start by configuring agent/server and (for production) deploy web with matching env. CLI users — install, openquok auth:login, programmatic tokens — see CLI and CLI authentication.

Request paths, polling, and the device_requests table are explained in Auth server architecture.

Environment variables

When running locally, values are loaded from agent/server/.env.development.local or agent/server/.env.production.local as described above.

Templates: agent/server/.env.development.example, agent/server/.env.production.example.

Required

DATABASE_URL — Postgres connection string.
OPENQUOK_OAUTH_CLIENT_ID — Platform CLI OAuth app client ID (prefix oqc_...).
OPENQUOK_OAUTH_CLIENT_SECRET — That app’s client secret (prefix oqs_...). Held only by the auth server for token exchange.

Note

Each CLI user still gets their own opo_… token scoped to the workspace they approve; plan limits apply to that workspace. See Auth server architecture → OAuth client credentials vs user access tokens.

SERVER_URL (API origin)

SERVER_URL — Public origin of the auth server API (no trailing slash). The CLI uses this as OPENQUOK_AUTH_SERVER.

OpenQuok production (reference):

SERVER_URL=https://cli-auth.openquok.com

Local development:

SERVER_URL=http://localhost:3111

BROWSER_ORIGIN (browser steps)

BROWSER_ORIGIN — Public origin where users open device login in the browser (no trailing slash). When set and different from SERVER_URL, the auth server returns verification_uri under /cli/device/verify on this host and uses /cli/device/callback for OAuth redirect_uri.

OpenQuok production:

BROWSER_ORIGIN=https://www.openquok.com
OAuth app callback: https://www.openquok.com/cli/device/callback
Deploy web with CLI_AUTH_SERVER_URL=https://cli-auth.openquok.com — see web/.env.production.example.

Local (single host): omit BROWSER_ORIGIN (defaults to SERVER_URL). Register http://localhost:3111/device/callback on the OAuth app.

Warning

If you deploy your own stack, set SERVER_URL, BROWSER_ORIGIN, and the OAuth callback to your domains — do not copy OpenQuok production URLs unless those hosts are literally yours.

See Installation → Vercel → CLI auth server on Vercel.

Optional

PORT — Local listen port (default 3111).
OPENQUOK_FRONTEND_URL — Web app hosting the OAuth approval UI.
OPENQUOK_API_URL — API base URL; token exchange uses /api/v1/oauth/token.
OPENQUOK_AUTHORIZE_PATH — Frontend path for the approve UI (default /oauth/authorize).

Note

For local development, run pnpm dev from agent/server and hit http://localhost:3111/health once env vars are set.

Note

For local Postgres, run docker compose -f infra/docker-compose.yml up -d postgres.

Common setup steps

Start with the example env file

Copy agent/server/.env.development.example or agent/server/.env.production.example to the matching *.local file. Set DATABASE_URL, OAuth client ID and secret, and SERVER_URL. For production on OpenQuok, also set BROWSER_ORIGIN and configure web/.env.production.local with CLI_AUTH_SERVER_URL. Restart after changes.

Register the OAuth callback

In your OAuth app, set the callback URL:

OpenQuok production: https://www.openquok.com/cli/device/callback
Local (auth server only): http://localhost:3111/device/callback
Self-hosted (split web + API): BROWSER_ORIGIN/cli/device/callback
Self-hosted (single host): SERVER_URL/device/callback

Deploy

Auth server — separate Vercel project, Root Directory agent/server:

pnpm vercel:env:sync:agent-server:prod
pnpm vercel:deploy:agent-server:prod

Web app (production browser routes) — deploy the web project and sync CLI_AUTH_SERVER_URL:

pnpm vercel:env:sync:web:prod
pnpm vercel:deploy:web:prod

Or both from the repo root:

pnpm vercel:deploy:cli-device-flow:prod

See Installation → Vercel → CLI auth server on Vercel.

Tip

To run the CLI before @openquok/auto-cli is installed from npm (pnpm --filter ./agent build, node agent/dist/index.js …), see Development environment → Running the CLI from the monorepo (unpublished).