Skip to content

configuration.md

Latest commit

 

History

History
336 lines (261 loc) · 19.6 KB

configuration.md

File metadata and controls

336 lines (261 loc) · 19.6 KB

Configuration Reference

Environment Variables

Server

Variable Default Description
OVERSIGHT_PORT 7878 HTTP server listen port
OVERSIGHT_HOST 127.0.0.1 Bind address (0.0.0.0 for all interfaces)
OVERSIGHT_DATA_DIR .oversight Data directory for database files and local storage
OVERSIGHT_STORAGE sqlite Storage backend selector: sqlite, pg / postgres, or fs / filesystem
OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE (disabled) Required for server startup with any non-SQLite backend (pg, postgres, fs, filesystem)
OVERSIGHT_MASTER_KEY (none) Base64-encoded encryption key (generate with oversight-server genkey)
OVERSIGHT_API_TOKEN (none) Bearer token for API and remote worker authentication; also required when binding the server to a non-loopback host
OVERSIGHT_STATIC_DIR web/dist Path to the built frontend assets
OVERSIGHT_WORKER_MODE embedded Worker mode: embedded (in-process) or remote
OVERSIGHT_LOG_FORMAT pretty Log format: pretty or json
OVERSIGHT_ALLOWED_ORIGINS (auto) Comma-separated CORS origins
OVERSIGHT_PUBLIC_URL (auto) Public base URL used to derive OAuth callback URLs

Worker

Variable Default Description
OVERSIGHT_WORKER_PORT 7879 Worker listen port
OVERSIGHT_WORKER_NODE_ID auto-generated UUID Unique worker identifier
OVERSIGHT_SERVER_URL http://localhost:7878 Server to connect to
OVERSIGHT_WORKER_ADDR http://127.0.0.1:7879 Worker URL advertised to server
OVERSIGHT_API_TOKEN (none) Token used for registration and server->worker auth
OVERSIGHT_REPO_DIR . Git repository root
OVERSIGHT_WORKTREE_DIR .worktrees Base directory for worktrees
OVERSIGHT_CACHE_DIR .cache/oversight-worker Config bundle cache directory

CLI profiles and command overrides

Variable Default Description
OVERSIGHT_CONFIG_HOME platform config dir Override where config.toml is stored
OVERSIGHT_SERVER_URL active profile server (http://localhost:7878 by default) Override the server URL for CLI invocations
OVERSIGHT_API_TOKEN (none) Token sent as X-API-Key by oversight init, oversight run, and oversight worker when talking to protected MCP/API routes
OVERSIGHT_AGENT_ID developer Agent identity for init / run MCP auth
OVERSIGHT_GIT_AUTHOR (derived from agent type) Git author name for oversight run commits
OVERSIGHT_GIT_EMAIL (derived from agent type) Git author email for oversight run commits

Generic CRUD commands such as projects, tasks, workflows, and docs still use the bearer token stored in the active CLI profile. Verified precedence is:

  1. explicit flags such as --server
  2. OVERSIGHT_SERVER_URL
  3. the active profile in config.toml
  4. the built-in default profile server (http://localhost:7878)

OVERSIGHT_CONFIG_HOME changes the config root entirely, so the CLI reads and writes $OVERSIGHT_CONFIG_HOME/config.toml instead of the platform default.

Authentication and OAuth

Variable Default Description
OVERSIGHT_GITHUB_CLIENT_ID (none) Enable the built-in GitHub OAuth provider
OVERSIGHT_GITHUB_CLIENT_SECRET (none) GitHub OAuth client secret
OVERSIGHT_GITHUB_CALLBACK_URL (derived) Explicit GitHub callback URL override
OVERSIGHT_GITHUB_PROVIDER_ID github Provider ID used in /api/auth/providers/:id/*
OVERSIGHT_GITHUB_LABEL GitHub Label shown in the login UI
OVERSIGHT_GITHUB_SCOPES read:user,user:email Comma-separated GitHub scopes
OVERSIGHT_GITHUB_ALLOW_SIGNUP false Auto-create a local user on first GitHub sign-in
OVERSIGHT_GITHUB_DEFAULT_ROLE member Default role for OAuth signups
OVERSIGHT_FEISHU_APP_ID (none) Enable the built-in Feishu / Lark OAuth provider
OVERSIGHT_FEISHU_APP_SECRET (none) Feishu / Lark App Secret
OVERSIGHT_FEISHU_REGION cn cn (Feishu mainland) or intl (Lark)
OVERSIGHT_FEISHU_CALLBACK_URL (derived) Explicit Feishu callback URL override
OVERSIGHT_FEISHU_PROVIDER_ID feishu Provider ID used in /api/auth/providers/:id/*
OVERSIGHT_FEISHU_LABEL 飞书 / Lark Label shown in the login UI
OVERSIGHT_FEISHU_SCOPES contact:user.base:readonly,contact:user.email:readonly Comma-separated Feishu scopes
OVERSIGHT_FEISHU_ALLOW_SIGNUP false Auto-create a local user on first Feishu sign-in
OVERSIGHT_FEISHU_DEFAULT_ROLE member Default role for Feishu signups
OVERSIGHT_AUTH_PROVIDERS (none) JSON array for additional OAuth/OIDC providers

For GitHub Enterprise or custom endpoints, the built-in provider also accepts OVERSIGHT_GITHUB_AUTHORIZE_URL, OVERSIGHT_GITHUB_TOKEN_URL, OVERSIGHT_GITHUB_USER_URL, OVERSIGHT_GITHUB_EMAILS_URL, and the alias OVERSIGHT_GITHUB_REDIRECT_URL.

The Feishu provider similarly accepts OVERSIGHT_FEISHU_AUTHORIZE_URL, OVERSIGHT_FEISHU_TOKEN_URL, OVERSIGHT_FEISHU_USER_URL, and the alias OVERSIGHT_FEISHU_REDIRECT_URL. Region defaults point to passport.feishu.cn / open.feishu.cn for cn and accounts.larksuite.com / open.larksuite.com for intl.

Storage-Specific

Variable Default Description
POSTGRES_URL (none) Preferred PostgreSQL connection string
OVERSIGHT_FS_ROOT <OVERSIGHT_DATA_DIR>/fs Filesystem backend root directory
OVERSIGHT_FS_PROJECT_ID current Virtual project id exposed by the FS backend
OVERSIGHT_GIT_PROVIDER (inferred) Git hosting: github, gitlab
OVERSIGHT_GITHUB_REPO (none) GitHub repository identifier
OVERSIGHT_GITLAB_PROJECT_PATH (none) GitLab project path
OVERSIGHT_GITLAB_TOKEN (none) GitLab authentication token

Storage Backend Setup

SQLite is the default production server backend. The pg and fs backends have dedicated repo/startup/concurrency coverage, but current server startup still requires OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE=1 because thread/mailbox data and a few runtime/auth flows continue to keep local state under OVERSIGHT_DATA_DIR.

When you bind the server to a non-loopback host such as 0.0.0.0, startup now fails fast unless OVERSIGHT_API_TOKEN is configured.

SQLite (default)

No additional configuration needed. The database file is created automatically at <OVERSIGHT_DATA_DIR>/oversight.db.

export OVERSIGHT_STORAGE=sqlite
export OVERSIGHT_DATA_DIR=.oversight
./oversight-server

PostgreSQL

Requires a running PostgreSQL instance. Set the connection string:

export OVERSIGHT_STORAGE=pg
export OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE=1
export POSTGRES_URL="postgres://user:password@localhost:5432/oversight"
export OVERSIGHT_DATA_DIR=.oversight
./oversight-server

The server runs migrations automatically on startup. POSTGRES_URL is the preferred connection string; alternatively set PGHOST, PGPORT, PGUSER, PGPASSWORD, and PGDATABASE. DATABASE_URL is not read by the current server code.

Filesystem

Stores user-facing docs as Markdown under OVERSIGHT_FS_ROOT/docs and app metadata under OVERSIGHT_FS_ROOT/.oversight. This mode is useful for backend-porting tests or version-controlled document stores:

export OVERSIGHT_STORAGE=fs
export OVERSIGHT_EXPERIMENTAL_MIXED_STORAGE=1
export OVERSIGHT_FS_ROOT=.oversight/fs
export OVERSIGHT_DATA_DIR=.oversight
./oversight-server

The filesystem backend acquires an exclusive lock at <OVERSIGHT_FS_ROOT>/.oversight/lock, exposes a single virtual project (OVERSIGHT_FS_PROJECT_ID, default current), and still leaves some runtime-side repos unported. Use it deliberately, not as the default production deployment path.

OAuth and SSO

Oversight exposes login providers at /api/auth/providers and callback endpoints at /api/auth/providers/:provider_id/callback.

Built-in GitHub provider

export OVERSIGHT_PUBLIC_URL=https://your-host.example
export OVERSIGHT_GITHUB_CLIENT_ID=github-client-id
export OVERSIGHT_GITHUB_CLIENT_SECRET=github-client-secret
export OVERSIGHT_GITHUB_ALLOW_SIGNUP=true

Configure the GitHub OAuth App callback to:

https://your-host.example/api/auth/providers/github/callback

The built-in GitHub provider defaults to id=github, label=GitHub, and scopes read:user,user:email. Override the callback explicitly with OVERSIGHT_GITHUB_CALLBACK_URL when the public URL cannot be derived from forwarded headers or OVERSIGHT_PUBLIC_URL.

Built-in Feishu / Lark provider

export OVERSIGHT_PUBLIC_URL=https://your-host.example
export OVERSIGHT_FEISHU_APP_ID=cli_xxxxxxxxxxxxxxxx
export OVERSIGHT_FEISHU_APP_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export OVERSIGHT_FEISHU_REGION=cn            # or "intl" for Lark
export OVERSIGHT_FEISHU_ALLOW_SIGNUP=true

Configure the Feishu web-app redirect URL to:

https://your-host.example/api/auth/providers/feishu/callback

App setup steps (Feishu Developer Console / Lark Developer Portal):

  1. Create a "Web App" (网页应用) and enable the authen/v2 OAuth flow.
  2. Add the callback URL above under Security Settings → Redirect URLs (安全设置 → 重定向 URL). Multiple URLs are allowed if you run several environments (dev / staging / prod) — list each one explicitly.
  3. Add the permissions / scopes listed in the Required permissions table below under Permissions & Scopes (权限管理 → 权限).
  4. Submit the app for tenant admin approval (审核发布). Non-admin users cannot sign in until the tenant admin approves the requested permissions.
  5. Copy the App ID and App Secret from Credentials & Basic Info (凭证与基础信息) into OVERSIGHT_FEISHU_APP_ID / OVERSIGHT_FEISHU_APP_SECRET.
Required permissions

The Oversight login flow calls POST /open-apis/authen/v2/oauth/token followed by GET /open-apis/authen/v1/user_info. The following scopes must be declared on the app and approved by the tenant admin:

Scope (English ID) 中文名称 Required? Unlocks fields in user_info Used for in Oversight
contact:user.base:readonly 获取用户基本信息 Required union_id, open_id, user_id, name, en_name, avatar_url, tenant_key Stable identity (union_id), display name, avatar
contact:user.email:readonly 获取用户邮箱信息 Recommended email, enterprise_email Mapped to the local user's email; falls back gracefully if absent
contact:user.employee_id:readonly 获取用户工号 Optional employee_no Not used today; reserved for future HR-style joins

Notes:

  • contact:user.base:readonly is mandatory — without it, union_id is missing and the callback fails with "missing 'union_id' in feishu user_info — ensure the 'contact:user.base:readonly' scope is granted".
  • If contact:user.email:readonly is not granted, sign-in still works; the resulting local user simply has no email recorded (email_verified=false).
  • Oversight does not request contact:user.phone:readonly, calendar, drive, IM, or any tenant-wide read scopes. The OAuth user_info endpoint does not require any other scope.
  • Stable identity is derived from union_id (unchanged across all Feishu apps within the same tenant). The login prefers enterprise_email over the personal email and falls back to name / en_name for display.
Tenant whitelisting

If your Feishu / Lark tenant restricts which users may use third-party apps (e.g. via 应用可用范围 / "Application visibility"), explicitly add the user groups or departments that should be allowed to sign in to Oversight. Users outside the visible scope will get a Feishu-side error before reaching the Oversight callback.

Multiple providers

Set OVERSIGHT_AUTH_PROVIDERS to a JSON array when you need multiple login providers. Supported type values are github, oidc, generic_oauth_profile, and feishu.

export OVERSIGHT_AUTH_PROVIDERS='[
  {
    "id": "github-enterprise",
    "type": "github",
    "label": "GitHub Enterprise",
    "client_id_env": "GHE_CLIENT_ID",
    "client_secret_env": "GHE_CLIENT_SECRET",
    "authorize_url": "https://ghe.example.com/login/oauth/authorize",
    "token_url": "https://ghe.example.com/login/oauth/access_token",
    "user_url": "https://ghe.example.com/api/v3/user",
    "emails_url": "https://ghe.example.com/api/v3/user/emails",
    "allow_signup": true,
    "default_role": "member"
  },
  {
    "id": "corp",
    "type": "oidc",
    "label": "Company SSO",
    "client_id_env": "OIDC_CLIENT_ID",
    "client_secret_env": "OIDC_CLIENT_SECRET",
    "issuer_url": "https://login.example.com/realms/main",
    "scopes": ["openid", "email", "profile"]
  },
  {
    "id": "feishu-cn",
    "type": "feishu",
    "label": "飞书",
    "region": "cn",
    "client_id_env": "FEISHU_CN_APP_ID",
    "client_secret_env": "FEISHU_CN_APP_SECRET",
    "allow_signup": true,
    "default_role": "member"
  },
  {
    "id": "lark",
    "type": "feishu",
    "label": "Lark",
    "region": "intl",
    "client_id_env": "LARK_APP_ID",
    "client_secret_env": "LARK_APP_SECRET"
  }
]'

Each provider needs a stable id, a client_id or client_id_env, an optional client_secret or client_secret_env, and either redirect_url / callback_url or OVERSIGHT_PUBLIC_URL. For generic_oauth_profile, also provide authorize_url, token_url, profile_url, and any field mappings you need, such as subject_path, email_path, email_verified_path, display_name_path, and avatar_url_path. For feishu, set region to cn or intl (default cn) — endpoints are auto-configured but can still be overridden individually.

Worker Configuration for Distributed Mode

For parallel agent execution across multiple machines, run Oversight in distributed mode.

On the server:

export OVERSIGHT_WORKER_MODE=remote
export OVERSIGHT_API_TOKEN=your-token
./oversight-server

On each worker node:

export OVERSIGHT_SERVER_URL=http://<server-host>:7878
export OVERSIGHT_WORKER_ADDR=http://<worker-host>:7879
export OVERSIGHT_WORKER_PORT=7879
export OVERSIGHT_API_TOKEN=your-token
./oversight-worker

Or with the CLI:

OVERSIGHT_API_TOKEN=your-token \
oversight worker --server http://<server-host>:7878 --addr http://<worker-host>:7879 --port 7879

Worker nodes automatically:

  • Register with the server.
  • Detect available CLI agents (Claude Code, Codex, OpenClaw) on the host.
  • Accept dispatched tasks and create isolated worktrees.
  • Report results back to the server.
  • Require OVERSIGHT_API_TOKEN for protected /a2a/* and /ws/session endpoints when a token is configured.

This was re-smoked with the env-driven oversight worker command path: OVERSIGHT_SERVER_URL, OVERSIGHT_WORKER_ADDR, and OVERSIGHT_WORKER_PORT are sufficient to register a worker against a reachable server.

Set OVERSIGHT_WORKER_ADDR or --addr to the URL that the server can reach directly. The default http://127.0.0.1:<port> only works when the server runs on the same host as the worker.

Additional worker flags:

Flag Env Variable Default Description
--port OVERSIGHT_WORKER_PORT 7879 Worker listen port
--server OVERSIGHT_SERVER_URL http://localhost:7878 Server to connect to
--addr OVERSIGHT_WORKER_ADDR http://127.0.0.1:7879 Worker URL advertised to server
--node-id OVERSIGHT_WORKER_NODE_ID auto-generated UUID Unique worker identifier
--repo-dir OVERSIGHT_REPO_DIR . Git repository root
--worktree-dir OVERSIGHT_WORKTREE_DIR .worktrees Base directory for worktrees
--cache-dir OVERSIGHT_CACHE_DIR .cache/oversight-worker Config bundle cache directory

Agent Model Overrides

Variable Default Description
OVERSIGHT_CLAUDE_MODEL (from agent definition) Override model for Claude CLI agents
OVERSIGHT_CODEX_MODEL gpt-5-codex Override model for Codex CLI agents
OVERSIGHT_HERMES_MODEL (from agent definition) Override model for Hermes/OpenClaw
OVERSIGHT_MODEL deepseek-chat Default model for local LLM agents

Embedding and Search

Variable Default Description
EMBEDDING_API_BASE https://api.openai.com/v1 Embedding service base URL
EMBEDDING_API_KEY (falls back to OPENAI_API_KEY) Embedding API key
EMBEDDING_MODEL text-embedding-3-small Embedding model name

Timeouts

Variable Default Description
OVERSIGHT_ACP_SETUP_TIMEOUT_SECS 120 Agent setup timeout (seconds)
OVERSIGHT_ACP_PROMPT_TIMEOUT_SECS 900 Agent prompt timeout (seconds)