Reference

Configuration

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  >  .shipwright.json  >  built-in default

Env vars are the primary configuration path. Managed Shipwright agents must use env vars — they are injected by the admin service and are the only supported config mechanism for deployed agents. .shipwright.json is a local fallback for use when you install and run the Shipwright plugin directly in Claude Code without a managed agent. Do not commit or rely on .shipwright.json in a managed agent deployment.

Section 1

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
`SHIPWRIGHT_TASK_STORE`	`string`	`—`	Selects the task store backend (github, jira, or json). When set, takes precedence over all file-based config — the .shipwright.json walk-up and SHIPWRIGHT_CONFIG are skipped entirely.
`SHIPWRIGHT_GITHUB_OWNER`	`string`	`—`	GitHub organization or user name. Required when SHIPWRIGHT_TASK_STORE=github.
`SHIPWRIGHT_GITHUB_REPO`	`string`	`—`	GitHub repository name. Required when SHIPWRIGHT_TASK_STORE=github.
`JIRA_BASE_URL`	`string`	`—`	Base URL of the Jira instance (e.g. https://example.atlassian.net). Required when SHIPWRIGHT_TASK_STORE=jira.
`JIRA_PROJECT_KEY`	`string`	`—`	Jira project key (e.g. SHIP). Required when SHIPWRIGHT_TASK_STORE=jira.
`SHIPWRIGHT_REPOS_DIR`	`string`	`<AGENT_HOME>/workspace/repos`	Override the workspace repos directory.
`SHIPWRIGHT_WORKTREE_DIR`	`string`	`<AGENT_HOME>/workspace/worktrees`	Override the workspace worktrees directory.
`SHIPWRIGHT_DEV_CHAT`	`bool`	`false`	Enables the unauthenticated POST /chat endpoint. Must not be set in production.
`SHIPWRIGHT_CONFIG`	`string`	`—`	Explicit path to .shipwright.json when auto-discovery is not suitable.
`GH_CMD`	`string`	`gh`	Override the gh CLI executable. Useful in environments where gh is installed to a non-default path.
`AGENT_HOME`	`string`	`~/.shipwright-agent`	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.
`JIRA_API_TOKEN`	`string`	`—`	API token for Jira authentication. Required when taskStore is jira. Env-var-only (secret).
`JIRA_EMAIL`	`string`	`—`	Email address for Jira authentication. Required when taskStore is jira.

.shipwright.json

.shipwright.json is for use when you install and run the Shipwright plugin in Claude Code directly — without a managed Shipwright agent. Managed agents receive all configuration via env vars from the admin service; they do not read .shipwright.json.

Config-file resolution order: (1) check SHIPWRIGHT_TASK_STORE env var; (2) walk up from cwd looking for .shipwright.json; (3) fall back to SHIPWRIGHT_CONFIG env var; (4) fall back to local JSON state.

Task store keys

Key	Type	Default	Description
`taskStore`	`"json" \| "github" \| "jira"`	`required`	Backend for the task store.
`github.owner`	`string`	`required if taskStore=github`	GitHub org or user that owns the issues repo.
`github.repo`	`string`	`required if taskStore=github`	GitHub repo name containing issues used as tasks.
`jira.baseUrl`	`string`	`required if taskStore=jira`	Base URL of the Jira instance.
`jira.projectKey`	`string`	`required if taskStore=jira`	Jira project key (e.g. SHIP).
`jira.readyJql`	`string`	`—`	Custom JQL to filter ready tasks. Overrides the default status-based query.
`jira.statusMap`	`Record<string, TaskStatus>`	`—`	Maps Jira status names to Shipwright task statuses.

Minimal example

{
  "taskStore": "github",
  "github": {
    "owner": "your-org",
    "repo": "your-repo"
  }
}

Section 2

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).
`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`	Dev-only chat server port (SHIPWRIGHT_DEV_CHAT gate, DEFAULT-DENY). Not used in production.
`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 separate from the chat server.
`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.

Workspace and tooling

Name	Type	Default	Description
`AGENT_HOME`	`string`	`~/.shipwright-agent`	Persistent storage root. Mount a PVC here in Kubernetes so mise caches and workspace files 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.
`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.

Analytics

All analytics vars are env-var-only (secrets/infra identifiers).

Name	Type	Default	Description
`POSTHOG_PROJECT_API_KEY`	`string`	`—`	PostHog project API key for event ingest. Env-var-only (secret).
`POSTHOG_HOST`	`string`	`https://us.i.posthog.com`	PostHog ingest host. Override for self-hosted PostHog deployments.

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
`SHIPWRIGHT_DEV_CHAT`	`bool`	`false`	Enables the unauthenticated POST /chat endpoint. Blocked at startup when NODE_ENV=production.
`ADMIN_DEV_AUTH`	`bool`	`false`	Enables GET /admin/dev-login (bypasses Google OAuth, mints a dev session). Blocked when NODE_ENV=production.

Section 3

Policy Config

Agent behavior is controlled by state/agent-policy.md. This is a Markdown file with a YAML front-matter block. Edit it directly to change review posting, merge permissions, and autonomy levels without reconfiguring crons or restarting the agent.

Fields

Field	Type	Default	Description
`auto_post_reviews`	`bool`	`false`	Post review comments to GitHub automatically without manual approval.
`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`	`true`	Allow the agent to review its own PRs. Set to false to require 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: false
allowed_events: [COMMENT, APPROVE]
review_external_prs: true
allow_self_review: true
min_confidence: 75
max_findings: 5
cleanup_merged_worktrees: true
cleanup_after_days: 14
---