Skip to content

Configuration

This page lists every setting that Speccy reads from the command line, the environment, and the served folder. The .speccy.yaml reference lists the keys of the repo configuration file.

speccy starts local mode and opens the browser. speccy serve starts local mode and opens no browser. Local mode has no sign-in.

Flag Default Meaning
--dir the current folder The folder with the bundles.
--addr 127.0.0.1:7878 The address to listen on. It must be a loopback address. Speccy refuses any other address, because local mode has no sign-in.
--no-open off Do not open the browser. speccy serve never opens it.

speccy serve --hosted takes no other flag. It reads its settings from the environment. Run hosted mode shows the setup.

  • Local mode reads .speccy.yaml in the --dir folder.
  • review, action, export, handoff, report, verify, add, tui and mcp look in the current folder first. Then they look in each parent folder. The first folder with .speccy.yaml is the root. With no file, the root is the current folder.
  • speccy init and speccy init --github write .speccy.yaml in the current folder.
  • A GitHub source reads .speccy.yaml at the root of its repo.

A missing file is an empty configuration. In local mode, Speccy ignores a file that does not parse, and it lists the problem on the bundles screen. A command stops with exit code 2 and names the error.

Local mode, speccy tui and speccy mcp keep their state in <root>/.speccy/state/. They make the folder on first start. speccy init adds .speccy/state/ to .gitignore. Do not commit the folder: it holds the key that decrypts your API keys.

Path, under the root Holds Commit it
.speccy.yaml The repo configuration. Yes
.speccy/profiles/<key>.yaml A local profile, and next to it the template file that the profile names. Yes
.speccy/decisions/<doc path>.yaml The sidecar of one spec doc: its waivers and acknowledgements. Yes
.speccy/state/speccy.db The SQLite database. No
.speccy/state/speccy.db-wal, speccy.db-shm The SQLite write-ahead log and its index. They exist while Speccy runs. No
.speccy/state/key The master key of local mode, with mode 0600. No
.speccy/state/tui.log The warnings of speccy tui. No

The database holds the review runs, the findings, the threads, the waiver requests, the handoffs, the verification runs, the model backends and the budget. It also holds the adopted types, the adopted links and the dismissed docs, which Speccy never writes into the repo. The docs, the profiles and the sidecars stay as files in the folder.

The headless commands (review, action, export, handoff, report, verify and init --github) use .speccy/state/ when speccy.db exists there. They then share the models, the cache and the runs with the app. With no database, they use a temporary store and delete it when they finish. Two such runs share no cache, so two runs of speccy review on the same doc can give different results. speccy add always makes .speccy/state/, because the source must outlive the command. SPECCY_STATE_DIR replaces the folder for all of these commands.

The master key explains the key file. Back up and restore says which files to copy.

speccy serve --hosted, speccy admin invite and speccy admin reset-link read these variables. Speccy names every missing or bad variable at once, and does not start.

Variable Required Default Meaning
SPECCY_DATABASE_URL Yes none The Postgres URL, such as postgres://speccy:secret@db:5432/speccy.
SPECCY_MASTER_KEY Yes none 32 random bytes in standard base64. Make one with openssl rand -base64 32. The master key says what it protects.
SPECCY_BASE_URL Yes none The public URL, such as https://speccy.example.com. It must start with http:// or https://. Speccy uses it in links, redirects and cookies. With http://, the cookies lose the Secure flag.
SPECCY_LISTEN No :8080 The address to listen on.
SPECCY_LOG_LEVEL No info debug, info, warn or error. Hosted mode writes JSON logs to standard error.
SPECCY_DB_MAX_CONNS No 20 The most Postgres connections that Speccy opens. It must be at least 2. The job queue shares the same pool.
SPECCY_NOTIFY_WEBHOOK_URL No none The incoming webhook URL of a Slack or Teams channel. Set it with SPECCY_NOTIFY_WEBHOOK_KIND, or not at all. When set, the two lock the webhook in Admin → Notifications.
SPECCY_NOTIFY_WEBHOOK_KIND No none slack or teams.
SPECCY_OIDC_ISSUER No none The issuer URL of an OpenID Connect provider. Set it with the next two, or not at all.
SPECCY_OIDC_CLIENT_ID No none The OIDC client ID.
SPECCY_OIDC_CLIENT_SECRET No none The OIDC client secret.
SPECCY_SETUP_TOKEN No none Opens /setup, where the first admin makes an account. The token stops working when an admin exists. Make one with openssl rand -hex 16.
SPECCY_GITHUB_APP_ID No none The ID of a GitHub App that you made yourself. Set the five SPECCY_GITHUB_APP_ values together, or none. When set, they lock the App in Admin → GitHub.
SPECCY_GITHUB_APP_PRIVATE_KEY No none The PEM text of the App’s private key. A \n in the value is a line break.
SPECCY_GITHUB_APP_CLIENT_ID No none The client ID of the App, for sign-in with GitHub.
SPECCY_GITHUB_APP_CLIENT_SECRET No none The client secret of the App.
SPECCY_GITHUB_APP_WEBHOOK_SECRET No none The webhook secret of the App.
SPECCY_GITHUB_APP_API_URL No https://api.github.com The GitHub API of the App. GitHub Enterprise Server uses https://<host>/api/v3.

Speccy does not start when SPECCY_GITHUB_OAUTH_CLIENT_ID or SPECCY_GITHUB_OAUTH_CLIENT_SECRET is set. Sign-in with GitHub uses the workspace’s GitHub App. Remove the two variables, and make the App in Admin → GitHub.

These variables apply to speccy review, speccy action and the other headless commands. Local mode, speccy tui and speccy mcp do not read them.

Variable Default Meaning
SPECCY_MODELS none The model of each role, as role=backend:model items separated by ; or new lines.
SPECCY_ANTHROPIC_API_KEY none The API key of the anthropic backend in SPECCY_MODELS.
SPECCY_OPENAI_API_KEY none The API key of the openai backend in SPECCY_MODELS.
SPECCY_OPENROUTER_API_KEY none The API key of the openrouter backend in SPECCY_MODELS.
SPECCY_DEEPSEEK_API_KEY none The API key of the deepseek backend in SPECCY_MODELS.
SPECCY_STATE_DIR .speccy/state under the root The store folder of a CI job, which keeps the store and its cache between runs. The key lasts for one run, so SPECCY_MODELS gives the API keys each time. Do not point it at the state folder of the local app: outside CI, Speccy stops when the folder holds a key file.
SPECCY_REPORTS_DIR speccy-reports Where speccy action writes one HTML report for each reviewed bundle.
SPECCY_TOKEN none A personal API token for --server. Make one under Account → API tokens on the server.

A role is reviewer, reader_1, reader_2, reader_3, judge or writer. The role all sets every role. A backend is anthropic, openai, openrouter or deepseek. SPECCY_MODELS takes no agent CLI.

Terminal window
export SPECCY_MODELS="all=anthropic:<model>; reader_2=openai:<model>"
export SPECCY_ANTHROPIC_API_KEY=...
export SPECCY_OPENAI_API_KEY=...
speccy review docs/specs

For each backend in SPECCY_MODELS, Speccy makes or updates a backend named ci-<backend>, with the key from SPECCY_<BACKEND>_API_KEY. Then it assigns the roles. With a kept store, these backends stay in the store. Speccy stops with an error when a key is missing. It picks no default model. Add a model backend explains the roles.

The GitHub Action sets all of these variables from its inputs. GitHub Action lists the inputs.

install.sh reads two variables. They do not reach the speccy binary.

Variable Default Meaning
SPECCY_VERSION the latest release The version to install, such as 0.18.0.
SPECCY_BIN_DIR /usr/local/bin, or ~/.local/bin Where the script puts the binary.
Variable Read by Meaning
VISUAL, then EDITOR speccy tui The editor that opens a file.
GITHUB_TOKEN, GITHUB_REPOSITORY, GITHUB_EVENT_PATH speccy action The pull request and the token that posts the comments. GitHub Actions sets them.
GITHUB_API_URL, GITHUB_SERVER_URL, GITHUB_RUN_ID, GITHUB_STEP_SUMMARY speccy action The GitHub host, the run link and the job summary file. GitHub Actions sets them.

An admin sets these under Admin → Workspace settings. Speccy stores them in the database.

Setting Default Range Mode
Model calls at a time 8 1 to 16, per review run Both
Reviews at a time 3 1 to 20 Both
Pull request reviews at a time 2 1 to 20 Hosted
Largest file (MB) 10 1 to 50 Hosted
Largest bundle (MB) 50 the file limit to 500 Hosted
Invite links expire after (days) 7 1 to 90 Hosted

Reviews at a time limits the jobs that run at once in the interactive queue. These are the reviews from the app, the CLI and MCP, the AI answers in threads, the verification runs and the review requests. Pull request reviews at a time limits the reviews of the GitHub App, in the pr queue. A change to either one waits for the running reviews of its queue to finish. Model calls at a time applies to each running review.

The API has one more setting, resolve_sources, with no control in the app. It turns the grounding source resolver on or off, and it is on by default. The resolver reads the redirect chain, the status and the dates of each grounding source. With it off, a source carries no redirect chain and no retrieval date. A source policy rule that needs them then drops the source. To change it, send PUT /api/v1/admin/settings with all the settings and resolve_sources. HTTP API has the request.