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-4-6`	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 on POST /agents. 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 on POST /agents. 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_ADMIN_DEPLOYMENT_NAME`	`string`	`—`	Name of the admin Deployment, used as the ownerReference target so per-agent resources are garbage-collected with the admin Deployment. Only read when provisioning is enabled.
`SHIPWRIGHT_ADMIN_DEPLOYMENT_UID`	`string`	`—`	UID of the admin Deployment, paired with SHIPWRIGHT_ADMIN_DEPLOYMENT_NAME for the ownerReference. 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 state/agent-policy.md. Ask your agent to change review posting, merge permissions, and autonomy levels without reconfiguring crons or restarting the agent. Alternatively, for local development or self-hosted setups without a connected agent, edit the Markdown file directly — it uses a YAML front-matter block.

Fields

Field	Type	Default	Description
`auto_post_reviews`	`bool`	`true`	Post review comments to GitHub automatically without manual approval. Set to false to stage reviews locally for owner approval instead.
`allowed_events`	`string[]`	`["COMMENT", "APPROVE"]`	GitHub review event types the agent may emit.
`review_external_prs`	`bool`	`true`	Review PRs opened by users other than the agent.
`allow_self_review`	`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.
`min_confidence`	`number`	`75`	Minimum confidence score (0–100) for a finding to be included in a review.
`max_findings`	`number`	`5`	Maximum number of findings to include in a single review.
`cleanup_merged_worktrees`	`bool`	`true`	Automatically remove worktrees for merged branches.
`cleanup_after_days`	`number`	`14`	Age threshold (days) before a merged-branch worktree is eligible for cleanup.

Example

---
auto_post_reviews: true
allowed_events: [COMMENT, APPROVE]
review_external_prs: true
allow_self_review: false
min_confidence: 75
max_findings: 5
cleanup_merged_worktrees: true
cleanup_after_days: 14
---