Configuration Reference

Single authoritative reference for all Shipwright configuration options, organized by scope: Plugin Config, Agent Config, and Policy Config.

Precedence

When the same option can be set multiple ways, resolution order is:

env var  >  built-in default

Env vars are the only configuration path. All Shipwright configuration is supplied via env vars — injected by the admin service for managed agents, or set in the local environment for direct plugin use.

Plugin Config

Configuration for the Shipwright Claude Code plugin (plugins/shipwright/). These options control workspace discovery, task-store backend, and GitHub CLI integration.

Env vars

Name	Type	Default	Description
`GH_CMD`	`string`	`gh`	Override the gh CLI executable. Useful in environments where gh is installed to a non-default path.
`AGENT_HOME`	`string`	`/data/agent-home`	Persistent storage root for workspace files, mise caches, and ~/.claude.
`WORKSPACE_PATH`	`string`	`—`	Direct workspace path override. Takes precedence over AGENT_HOME-based discovery when set.
`SHIPWRIGHT_TASK_STORE_URL`	`string`	`—`	Base URL of the Shipwright task-store service. Injected into the agent Deployment by the admin provisioner; agents use this to authenticate with the task-store API when claiming tasks or updating status.
`SHIPWRIGHT_TASK_STORE_TOKEN`	`string`	`—`	Bearer token for task-store API access. Minted per-agent by the admin provisioner; used by agents and plugin scripts to claim tasks, update status, and query the task queue. Env-var-only (secret).

Agent Config

Configuration for the Shipwright agent runtime (agent/ and admin/). All options are env vars — there is no file-based fallback for agent config. Secrets must be supplied as env vars and are never stored in config files.

Claude / Anthropic

Name	Type	Default	Description
`ANTHROPIC_MODEL`	`string`	`claude-sonnet-5-5`	Claude model used for each agent invocation.
`ANTHROPIC_FALLBACK_MODEL`	`string`	`—`	Fallback model if the primary is unavailable.
`ANTHROPIC_EFFORT_LEVEL`	`string`	`—`	Effort/thinking level passed to Claude (e.g. extended, auto, none).
`SHIPWRIGHT_CLAUDE_TIMEOUT_MS`	`number`	`3600000`	Hard ceiling timeout in milliseconds for a single claude -p session spawned by the agent runner — a backstop, not the primary timeout (see SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS). Fires only for a continuously-active-but-never-converging session. Falls back to the default when unset or not a positive integer. When raising this, raise SHIPWRIGHT_TASK_STORE_CLAIM_TTL_MS in step (keep the ~5 min buffer) or the stale-claim reaper re-dispatches a duplicate run.
`SHIPWRIGHT_CLAUDE_IDLE_TIMEOUT_MS`	`number`	`1500000`	Idle-reset timeout in milliseconds for a single claude -p session — the primary timeout in practice. Cleared and restarted on every stdout line; fires (ClaudeTimeoutError, reason: idle) only when the session goes silent this long. Falls back to the default when unset or not a positive integer.
`ANTHROPIC_API_KEY`	`string`	`—`	Anthropic API key. Env-var-only (secret).
`CLAUDE_CODE_OAUTH_TOKEN`	`string`	`—`	Claude Code OAuth token (alternative to ANTHROPIC_API_KEY). Env-var-only (secret).

Slack

All Slack vars are env-var-only (secrets). The agent does not function as a Slack bot without them.

Name	Type	Default	Description
`SLACK_BOT_TOKEN`	`string`	`required for Slack`	Slack bot user OAuth token (xoxb-...).
`SLACK_APP_TOKEN`	`string`	`required for Slack`	Slack app-level token for Socket Mode (xapp-...).
`SLACK_SIGNING_SECRET`	`string`	`required for Slack`	Used to verify incoming Slack request signatures.
`SLACK_ADMIN_TOKEN`	`string`	`—`	Optional admin-level token for privileged Slack operations.
`SLACK_ALERT_CHANNEL`	`string`	`—`	Slack channel ID to post system alerts (e.g. startup errors).
`SLACK_OWNER_USER`	`string`	`—`	Slack user ID of the agent owner, used for DM fallback.

GitHub

Provide either the GitHub App vars (recommended) or GH_TOKEN (PAT). App auth is used when the App env vars are present; GH_TOKEN is the fallback.

Name	Type	Default	Description
`GH_APP_ID`	`string`	`required for App auth`	GitHub App ID (integer as string). Env-var-only (secret).
`GH_APP_INSTALLATION_ID`	`string`	`required for App auth`	Installation ID for the target org/repo. Env-var-only (secret).
`GH_APP_PRIVATE_KEY`	`string`	`required for App auth`	PEM private key for the GitHub App. Env-var-only (secret).
`GH_TOKEN`	`string`	`—`	Personal Access Token. Used only when GitHub App vars are absent. Env-var-only (secret).

Shipwright platform

Name	Type	Default	Description
`SHIPWRIGHT_API_URL`	`string`	`—`	Base URL of the Shipwright admin service, used by the agent entrypoint to fetch config at startup.
`SHIPWRIGHT_AGENT_ID`	`string`	`—`	The agent's ID in the Shipwright platform. Also settable via --agent-id CLI flag.
`SHIPWRIGHT_AGENT_API_KEY`	`string`	`—`	Bearer token for the config fetch at startup (/agents/:id/config and /agents/:id/crons). Also settable via --api-key CLI flag.

Server

Name	Type	Default	Description
`PORT`	`number`	`3000`	Hono server port for the admin service (admin/src/main.ts).
`SHIPWRIGHT_HEALTH_PORT`	`number`	`3459`	Agent health server port for the K8s liveness probe. Served in-process by entrypoint-main.ts on a dedicated port.
`NODE_ENV`	`string`	`—`	Runtime environment. Set to production to enforce production-safety guards.

Metrics & Admin service

Name	Type	Default	Description
`DATABASE_URL_SHIPWRIGHT_ADMIN`	`string`	`required`	Postgres connection string for the admin service schema.
`SHIPWRIGHT_SESSION_SECRET`	`string`	`—`	HS256 secret for signing session cookies. Used by the metrics service (vitals_session cookie) and the admin service (admin_session cookie).
`SHIPWRIGHT_ENCRYPTION_KEY`	`string`	`—`	64-char hex (32 bytes) for AES-256-GCM encryption of secrets at rest. If unset, secrets are stored in plain text.
`SHIPWRIGHT_ADMIN_ALLOWED_EMAILS`	`string`	`—`	Comma-separated list of Google email addresses permitted to log in to the admin UI.
`SHIPWRIGHT_ADMIN_APP_BASE_URL`	`string`	`http://localhost:{PORT}`	Public base URL of the admin service, used to construct the Google OAuth redirect URI.
`GOOGLE_CLIENT_ID`	`string`	`—`	Google OAuth 2.0 client ID. Required for the admin UI login flow.
`GOOGLE_CLIENT_SECRET`	`string`	`—`	Google OAuth 2.0 client secret. Required for the admin UI login flow.

Task store service

Name	Type	Default	Description
`DATABASE_URL_SHIPWRIGHT_TASK_STORE`	`string`	`required`	Postgres connection string for the task-store service. Must be a separate database from the admin service — the schema forbids sharing. Read by @shipwright/task-store and @shipwright/agent.
`SHIPWRIGHT_TASK_STORE_URL`	`string`	`—`	Base URL of the Shipwright task-store service (e.g. http://task-store:3000 or https://tasks.example.com). When set alongside SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN, the admin service wires per-agent tokens during provisioning and injects the URL + token into agent Deployment env vars. Agents use these to authenticate with the task-store API when claiming tasks or updating status.
`SHIPWRIGHT_TASK_STORE_TOKEN`	`string`	`—`	Bearer token for task-store API access. Minted per-agent by the admin provisioner and stored in the agent Secret; injected into the agent Deployment via SHIPWRIGHT_TASK_STORE_TOKEN env var. Used by agents to claim tasks, update status, and query the task queue. Env-var-only (secret).
`SHIPWRIGHT_TASK_STORE_ADMIN_TOKEN`	`string`	`—`	Bearer token for admin-side task-store token minting. Required (alongside SHIPWRIGHT_TASK_STORE_URL) to enable per-agent provisioning at agent-creation time. Env-var-only (secret).
`SHIPWRIGHT_TASK_STORE_CLAIM_TTL_MS`	`number`	`3900000`	Milliseconds a claim (Task or PR review/patch/deploy) remains valid without a heartbeat. When an agent's last heartbeat exceeds this TTL, the claim will be abandoned and the record eligible for re-claiming by another agent. A single unified TTL covers both Task claims (/shipwright:dev-task) and PR claims — 3900000ms (65 min) is the 1-hour claude -p hard ceiling timeout plus a 5-minute buffer.
`SHIPWRIGHT_TASK_STORE_AGENTS_URL`	`string`	`—`	Base URL of the Shipwright agents service. When set alongside SHIPWRIGHT_TASK_STORE_AGENTS_API_KEY, the task-store service uses it to resolve agent tokens to their scoped repos. Optional — not required when agents do not need repo-scoping.
`SHIPWRIGHT_TASK_STORE_AGENTS_API_KEY`	`string`	`—`	Bearer token for the task-store service to call the agents service. Required alongside SHIPWRIGHT_TASK_STORE_AGENTS_URL to enable scope resolution. Env-var-only (secret).

Admin and metrics services

Cross-service vars read by the admin service and metrics service (not the task-store).

Name	Type	Default	Description
`SHIPWRIGHT_ADMIN_PUBLIC_REPO`	`string`	`—`	Repository slug (format: org/repo) scoped for the public read-only task board. When set, GET /public/tasks displays tasks for this repo only, unauthenticated. Optional — omit to disable the public board.
`SHIPWRIGHT_ADMIN_TZ`	`string`	`America/Los_Angeles`	IANA timezone name (e.g. America/New_York) for date/time display in the admin UI. When unset, defaults to America/Los_Angeles.
`METRICS_DASHBOARD_URL`	`string`	`/dashboard`	URL for the Metrics toolbar link in the admin UI. Defaults to /dashboard (same-host relative path). Set to an absolute URL when the metrics service runs on a different host or port.
`METRICS_ADMIN_APP_URL`	`string`	`""`	Base URL of the admin console for the metrics dashboard toolbar Agents/Tasks/PRs links. Defaults to empty (same-host relative links). Set to an absolute URL when the admin console runs on a different origin than the metrics dashboard.

Agent provisioning (Kubernetes)

Controls how the admin service provisions the Kubernetes workload backing each agent at creation time. When provisioning is disabled (the default), create/delete only write the database row — no cluster is required.

Name	Type	Default	Description
`SHIPWRIGHT_K8S_PROVISIONING`	`string`	`—`	Set to enabled to provision a real Kubernetes PersistentVolumeClaim + Secret + Deployment per agent via KubernetesAgentProvisioner. Any other value (or unset) selects the no-op provisioner, preserving DB-only create/delete behavior.
`SHIPWRIGHT_K8S_NAMESPACE`	`string`	`—`	Target namespace for per-agent PersistentVolumeClaim, Secret, and Deployment. When unset, falls back to the pod's own release namespace. Only read when provisioning is enabled.
`SHIPWRIGHT_AGENT_IMAGE`	`string`	`—`	Agent container image (without tag) used for the provisioned Deployment. Only read when provisioning is enabled.
`SHIPWRIGHT_AGENT_IMAGE_TAG`	`string`	`latest`	Image tag joined as image:tag for the provisioned Deployment. Only read when provisioning is enabled.
`SHIPWRIGHT_AGENT_REPLICAS`	`number`	`1`	Replica count for the provisioned agent Deployment. Only read when provisioning is enabled.
`SHIPWRIGHT_AGENT_PVC_STORAGE_GI`	`number`	`40`	Storage size in Gi for the per-agent persistent home directory (PVC). Only read when provisioning is enabled. Must be large enough to hold mise caches and workspace files across pod restarts.
`SHIPWRIGHT_AGENT_PVC_NAME_TEMPLATE`	`string`	`—`	Template for deriving the PVC name from the agent's human-readable name. Use {name} as the placeholder. When unset, PVCs are named {sanitizedAgentId}-home. Only read when provisioning is enabled.

Workspace and tooling

Name	Type	Default	Description
`AGENT_HOME`	`string`	`/data/agent-home`	Persistent storage root. Mount a PVC here in Kubernetes so mise caches, workspace files, and ~/.claude survive pod restarts.
`MISE_DATA_DIR`	`string`	`<AGENT_HOME>/.mise`	Override the mise data directory. Auto-derived from AGENT_HOME.
`MISE_CACHE_DIR`	`string`	`<AGENT_HOME>/.mise/cache`	Override the mise cache directory.
`XDG_CACHE_HOME`	`string`	`<AGENT_HOME>/.cache`	Override the XDG cache directory.
`XDG_DATA_HOME`	`string`	`$HOME/.local/share`	Override the XDG data directory. Used to locate the mise data dir ($XDG_DATA_HOME/mise) when seeding a fresh PVC.
`SHIPWRIGHT_STARTUP_TIMEOUT_MS`	`number`	`180000`	Maximum milliseconds the entrypoint startup sequence may take before the agent exits. Override to a lower value (e.g. 10000) in dev for faster fail-fast feedback.
`AGENT_ALLOWED_TOOLS`	`string (JSON array)`	`—`	JSON array of allowed Claude tool patterns. Set by the admin service config sync; do not set manually in production.

Voice

Optional. When unset, voice transcription and synthesis are disabled.

Name	Type	Default	Description
`GROQ_API_KEY`	`string`	`—`	Groq API key for voice processing. Env-var-only (secret).
`ELEVENLABS_API_KEY`	`string`	`—`	ElevenLabs API key for speech synthesis. Env-var-only (secret).
`ELEVENLABS_VOICE_ID`	`string`	`—`	ElevenLabs voice ID to use for synthesis.
`WHISPER_SERVICE_URL`	`string`	`—`	URL of a Whisper transcription service for voice input.

Dev-only

Do not set these in production.

Name	Type	Default	Description
`ADMIN_DEV_AUTH`	`bool`	`false`	Enables GET /admin/dev-login (bypasses Google OAuth, mints a dev session). Blocked when NODE_ENV=production.
`METRICS_DASHBOARD_DEV_AUTH`	`bool`	`false`	Bypasses /dashboard session auth and /metrics/* API auth for local dev. Must not be enabled in production — exits with an error if NODE_ENV=production.
`TASK_STORE_SEED_ADMIN_TOKEN`	`string`	`—`	Bootstrap admin token seeded into the task-store on startup. Used only in local dev (task stack) to provision a bootstrapped admin token without manual token creation. Ignored if empty.

Policy Config

Agent behavior is controlled by per-agent policy settings stored in the Shipwright database. Edit them in the agent’s settings in the admin UI (or via the agent API); the agent picks up changes on its next config sync, with no cron change or restart.

Fields

Field	Type	Default	Description
`autoPostReviews`	`bool`	`true`	Post review comments to GitHub automatically without manual approval. Set to false to stage reviews locally for owner approval instead.
`allowSelfReview`	`bool`	`false`	Self-review is excluded by default. Set to true to allow the agent to review its own PRs instead of requiring a human reviewer on agent-authored PRs.
`minConfidence`	`number`	`75`	Minimum confidence score (0–100) for a finding to be included in a review.
`maxFindings`	`number`	`5`	Maximum number of findings to include in a single review.
`cleanupMergedWorktrees`	`bool`	`true`	Automatically remove worktrees for merged branches.
`cleanupAfterDays`	`number`	`14`	Age threshold (days) before a merged-branch worktree is eligible for cleanup.