Configuration and environment variables
Generated from core v1.191.0 by generator 0c423a7. Not edited by hand.
A Smeldr server is configured with environment variables. This page lists the 62 variables the server binary reads. They come from two places in the source at the release tag: example/server, which the release binary is built from, and core itself.
- Read as: set or unset means only whether the variable is set matters, so any value turns it on. value means the value is used. required means the server does not start without it; required (see the description) means the setting is required, and the description says where else it may be set.
- Default is the value the source uses when the variable is unset. A default applied later, when the value is checked, is in the description.
- Description is core's own, from the server's documentation at the same release.
- At start the server also checks values and combinations of variables, as the descriptions say. When it refuses to start, the message names the variable.
| Variable | Read as | Default | Description |
|---|---|---|---|
SECRET | value, required | HMAC signing secret (min 32 bytes in production) | |
BASE_URL | value, required (see the description) | canonical origin (e.g. "https://cms.example.com"); in the environment or as base_url in smeldr.config | |
DATABASE_PATH | value | smeldr.db | path to the SQLite database (default: smeldr.db) |
SMELDR_CONFIG | value | path of a config file merged under these variables (default: ./smeldr.config); a missing file is skipped; an unknown key, a line that is not "key = value", the key secret or an invalid value stops the boot | |
PORT | value | 8080 | HTTP listen port (default: 8080) |
ADDR | value | "127.0.0.1:" + port | full listen address (default: 127.0.0.1:PORT) |
ENABLE_TOKENS | set or unset | wire database-backed named token management | |
ENABLE_GOVERNANCE | set or unset | wire role-based access control (requires ENABLE_TOKENS for OAuth) | |
ENABLE_RELATIONS | set or unset | wire the relation graph store | |
ENABLE_DYNAMIC_CONTENT | set or unset | wire the runtime content type system and schema store | |
ENABLE_BLOCKS | set or unset | wire the block/composition system MCP tools | |
ENABLE_SCHEMA_TOOLS | set or unset | wire the schema store and its discovery MCP tools without the rest of the block tools (ENABLE_BLOCKS includes them) | |
ENABLE_GOVERNANCE_RECORDS | set or unset | wire core governance records (Signal, Decision, Amendment, their flows and relation kinds) without the Orchestration add-on. Records, not access: roles and grants are ENABLE_GOVERNANCE. | |
ORGANIZATION_NAME | value | INSTANCE_NAME, else smeldr | the name of the Organization created with the organization (D142; default: INSTANCE_NAME) |
ORGANIZATION_FOUNDER | value | the user ID of the person who created the organization; at boot it gets the admin and approver roles (D142), once (needs ENABLE_GOVERNANCE) | |
ENABLE_ORCHESTRATION | set or unset | wire core governance records and the Orchestration add-on (Task, Goal, Run); implies ENABLE_GOVERNANCE_RECORDS | |
ENABLE_AUTHORITY | set or unset | wire the Authority mechanism (Rule, AuthorityStub: decision-governance-model.md §4). Independent of ENABLE_ORCHESTRATION. | |
ENABLE_CHECK | set or unset | wire the Check precondition on Decision ratification (App.Check; decision-governance-model.md §4). Requires ENABLE_AUTHORITY and governance records (Check targets Decision specifically and queries the Authority graph). | |
INSTANCE_NAME | value | smeldr | source name embedded in Context Packet responses (default: smeldr) |
ENABLE_REDIRECTS | set or unset | wire database-backed redirect management | |
ENABLE_PAGE_META | set or unset | wire per-path SEO override store | |
ENABLE_MEDIA | set or unset | wire local media upload and management | |
MEDIA_STORE_BACKEND | value | local | media backend (default: local; only "local" supported) |
ENABLE_SOCIAL | set or unset | wire social publishing (Mastodon, LinkedIn, X); configure each platform at runtime with create_platform_config (Admin). With neither a stored config nor the MASTODON_* fallback, the server boots, but a Mastodon credential is refused and a Mastodon post fails with "Mastodon is not configured on this server" | |
MASTODON_CLIENT_ID | value | deprecated fallback: Mastodon OAuth client ID; see ENABLE_SOCIAL | |
MASTODON_CLIENT_SECRET | value | deprecated fallback: Mastodon OAuth client secret; see ENABLE_SOCIAL | |
MASTODON_INSTANCE_URL | value | deprecated fallback: Mastodon instance base URL; see ENABLE_SOCIAL | |
ENABLE_WEBHOOKS | set or unset | wire outbound webhook delivery | |
ENABLE_EVENT_STREAM | set or unset | wire GET /_events/stream (opt-in agent event push, T269) | |
ENABLE_EVENT_LOG | set or unset | keep a durable event log behind the stream (requires ENABLE_EVENT_STREAM; ?after=<event id> resumes, D117) | |
EVENT_LOG_RETENTION_DAYS | value | days the event log keeps an event, a whole number of 1 or more (default: 30); any other value refuses the boot when ENABLE_EVENT_LOG is set | |
ENABLE_SUBSCRIPTIONS | set or unset | subscription records on the event stream (D116): a connection without ?channel= delivers its token's subscriptions | |
ENABLE_STRUCTURAL_SWEEP | set or unset | wire a scheduled relation-staleness sweep (requires ENABLE_RELATIONS; App.SweepStructural on a cron schedule, recorded via SweepRunStore) | |
STRUCTURAL_SWEEP_SCHEDULE | value | 0 * * * * | 5-field cron expression for the sweep (default: "0 * * * *", hourly) |
ENABLE_EVAL_QUEUE_DRAIN | set or unset | wire a scheduled smeldr_eval_queue drain (requires governance records; App.DrainEvalQueue on a cron schedule, recorded via SweepRunStore, T211/A258) | |
EVAL_QUEUE_DRAIN_SCHEDULE | value | */5 * * * * | 5-field cron expression for the drain (default: "*/5 * * * *") |
ENABLE_SIGNAL_EXPIRY_SWEEP | set or unset | retired (D115): nothing expires; when set, boot logs that it does nothing | |
TITLE_CUTOVER | value | RFC3339 time after which a Decision, Task, Goal or Amendment without a title, or with one over 120 characters, is refused (default: warnings only, D112) | |
SIGNAL_MESSAGE_CUTOVER | value | RFC3339 time after which a Signal message over 500 characters is refused (default: warnings only, D114) | |
SIGNAL_EVENT_CUTOVER | value | RFC3339 time after which a history signal_type is refused (default: warnings only, D115) | |
PLAN_PATHS_CUTOVER | value | RFC3339 time after which a commit plan without repository and paths is refused (default: warnings only, T1015) | |
REV_CUTOVER | value | RFC3339 time after which a governance write without a rev is refused (default: warnings only, T1010) | |
ENABLE_STANDING_DRIFT_CHECK | set or unset | wire a scheduled standing drift check (report-only: compares each item's stored standing with its state's tag, records a Finding per mismatch; requires governance records; default off) | |
STANDING_DRIFT_CHECK_SCHEDULE | value | 30 3 * * * | 5-field cron expression for the check (default: "30 3 * * *", daily) |
ENABLE_CONTEXT_PACKET | set or unset | wire GET /packet/{type}/{slug} (Editor role required; requires ENABLE_RELATIONS and governance records, T159) | |
ENABLE_REACHABILITY | set or unset | wire GET /reachability/{type}/{id} (Author role required; requires ENABLE_RELATIONS only: not orchestration-specific, A293) | |
ENABLE_PROVENANCE | set or unset | wire transition-provenance recording (App.Provenance) | |
ENABLE_AGENTS | set or unset | wire the agent job system (connects to this server's own /mcp endpoint) | |
AGENT_MCP_URL | value | "http://127.0.0.1:" + port + "/mcp/message" | agent MCP endpoint (default: http://127.0.0.1:PORT/mcp/message) |
AGENT_MCP_TOKEN | value | bearer token for agent MCP calls | |
OAUTH_ISSUER | value | enable OAuth 2.1; set to canonical issuer URL (requires ENABLE_TOKENS) | |
OAUTH_DB_PATH | value | ./oauth.db | path to the OAuth SQLite database (default: ./oauth.db) |
ENABLE_GITHUB | set or unset | mount the pull request check's GitHub adapter (smeldr.dev/github) on POST /github/webhook and POST /github/core-events (T940); requires ENABLE_TOKENS, ENABLE_GOVERNANCE, ENABLE_RELATIONS, ENABLE_WEBHOOKS and ENABLE_GOVERNANCE_RECORDS (or ENABLE_ORCHESTRATION); refuses to start when a value below is missing or wrong, naming it, never its value | |
GITHUB_APP_ID | value | the GitHub App's ID (required when ENABLE_GITHUB) | |
GITHUB_APP_PRIVATE_KEY | value | the App's private key, PEM (a literal \n is a newline), or a file holding it; one of the two | |
GITHUB_APP_PRIVATE_KEY_FILE | value | the App's private key, PEM (a literal \n is a newline), or a file holding it; one of the two | |
GITHUB_WEBHOOK_SECRET | value | the GitHub App's webhook secret (required when ENABLE_GITHUB) | |
GITHUB_ADAPTER_TOKEN_ID | value | the token_id create_token returned for a class job token that holds check_change (grant editor); the adapter acts in process as it | |
GITHUB_CORE_WEBHOOK_SECRET | value | optional: by default the server registers its own core webhook for changecheck.transitioned at BASE_URL/github/core-events | |
GITHUB_NAMES_SHOWN | value | optional comma list of owner/name whose comments show names (D152) | |
GITHUB_CHECK_URL | value | optional link formats for the status and the comment | |
GITHUB_ITEM_URL | value | optional link formats for the status and the comment |
Read by linked modules
The server also links modules that read variables of their own. The table above lists only what the server's own source reads.
With ENABLE_AGENTS, each agent job run creates an Anthropic client with the SDK's defaults, and the SDK reads these variables then. They are not read or checked at start, so a missing key fails the job run, not the server.
| Variable | Read by | When |
|---|---|---|
ANTHROPIC_BASE_URL | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
ANTHROPIC_API_KEY | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
ANTHROPIC_AUTH_TOKEN | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
ANTHROPIC_PROFILE | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
ANTHROPIC_WEBHOOK_SIGNING_KEY | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
ANTHROPIC_CUSTOM_HEADERS | github.com/anthropics/anthropic-sdk-go | each agent job run, with ENABLE_AGENTS |
Depending on which of these are set, the SDK can read further variables for profiles and workload identity; see the SDK's own documentation.