Configuration

Murph stores non-secret process settings in ~/.murph/config.yaml, runtime-host secrets in ~/.murph/.credentials, and runtime state in SQLite. Setup does not read or write .env files. Environment variables are an advanced override path for process control, development, and hosted deployments.

The runtime host is the machine running Murph: your laptop, a VPS, a home server, or another host you control. In V1, config, credentials, SQLite, bot ingress, and agent execution are colocated on that host. Murph supports shared messenger channel coverage.

CLI-first setup

Use the CLI setup wizard for normal OSS configuration:

murph setup

Inspect runtime-host credentials with:

murph credentials doctor

You can re-run setup when credentials, channels, schedules, or policy choices change. The full wizard runs the same core sections as the CLI:

core -> provider -> distribution role -> channel providers -> bot app setup -> owner OAuth -> channels -> schedule -> policy -> status

Use a focused section when only one part changed:

murph setup provider
murph setup slack
murph setup discord
murph setup channels
murph setup policy
murph setup status

Use murph setup slack or murph setup discord to connect the shared channel bot. The browser setup page is a status and command surface; it does not replace the CLI setup workflow.

The schedule timezone is used when starting a session from Coverage or murph monitor. Murph computes the session stop time on the server and expires the session at the configured workday start in that timezone.

AI providers

Murph supports OpenAI and Anthropic. At least one provider key is required. Use murph setup provider to save provider keys into ~/.murph/.credentials.

Runtime replies and murph agent share the same provider/model by default. Normal setup writes non-secret model defaults into ~/.murph/config.yaml:

ai:
  defaultProvider: openai
  defaultModel: gpt-5.5

The CLI asks for the runtime AI provider first, then the Murph Agent model. murph setup ai remains as a compatibility alias. If you want the local setup/coding agent to use a different model from runtime replies, save an optional agent override:

ai:
  defaultProvider: openai
  defaultModel: gpt-5.5
  agent:
    provider: anthropic
    model: claude-opus-4-7

Command flags such as murph agent --provider openai --model gpt-5.5 still override them for one run.

Murph also runs a small no-tool policy execution classifier after the main runtime agent drafts. It uses the default runtime model unless you save an optional classifier override:

ai:
  policy:
    provider: openai
    model: gpt-5.4-mini

Storage

Murph uses local SQLite by default. SQLite is the transactional source of truth for sessions, runs, events, tool calls, policy decisions, action results, channel defaults, and runtime memory.

The SQLite path is stored in the runtime host's ~/.murph/config.yaml:

app:
  sqlitePath: data/murph.sqlite

SQLite is the transactional runtime memory source. Murph also writes a generated source-index catalog under ~/.murph/memory/source-index/ to route retrieval toward relevant connected resources. The source index is not factual grounding evidence.

Secrets are stored in plaintext at ~/.murph/.credentials on the runtime host with owner-only file permissions. Runtime credential reads come from that file, not SQLite.

Runtime-host credential storage

Murph writes ~/.murph/.credentials with 0600 permissions, so only the runtime-host user account can read it. For self-hosted installs, credentials are not uploaded to Murph-run servers. They only leave the runtime host when Murph uses them to call the providers you connected, such as Slack, GitHub, Notion, Linear, OpenAI, or Anthropic. If you run Murph on a VPS or cloud VM, that machine is the runtime host and must be trusted with the configured credentials.

Core runtime-host settings

Normal setup writes these values into ~/.murph/config.yaml:

app:
  distribution: team
  url: http://localhost:5173
  sqlitePath: data/murph.sqlite
  sourceIndexEnabled: true
  sourceIndexIntervalMs: 86400000
  sourceIndexRetryIntervalMs: 3600000

Channel-related setup values are stored in SQLite, not config.yaml. This includes bot roles, channel provider, workspace and owner identity, watched-channel mode, selected channels, and per-workspace channel defaults.

Source indexing is enabled by default. The runtime checks for due source-index work at startup and during heartbeat. sourceIndexIntervalMs controls how often a successful provider refresh becomes due again. sourceIndexRetryIntervalMs controls when failed provider refreshes are retried.

Runtime refresh

After local config or capability changes, Murph refreshes runtime state for active sessions that inherit config. This includes policy, SQLite setup defaults, integration connections, workspace capabilities, scoped plugin reloads, channel setup, provider config, and skills.

Config-bound sessions receive the updated policy, channel scope, and runtime revision. Sessions with explicit policy or explicit channel-scope overrides keep those choices. If a request is already running, Murph marks refresh as pending and applies it at the next run boundary. See Core Concepts for the runtime model.

Advanced process overrides

For normal setup, prefer ~/.murph/config.yaml and ~/.murph/.credentials on the runtime host. Environment variables are still supported when you need to control one process, point the CLI at a different runtime, isolate a test home directory, or run Murph in a hosted deployment.

Common process-control overrides:

MURPH_DISTRIBUTION=team
MURPH_HOME=/path/to/murph-home
MURPH_CONFIG_PATH=/path/to/config.yaml
MURPH_CREDENTIALS_PATH=/path/to/.credentials
MURPH_URL=http://localhost:5173
MURPH_PORT=5173
MURPH_HEARTBEAT_INTERVAL_MS=900000
MURPH_SOURCE_INDEX_ENABLED=true
MURPH_SOURCE_INDEX_INTERVAL_MS=86400000
MURPH_SOURCE_INDEX_RETRY_INTERVAL_MS=3600000

MURPH_URL is the CLI control URL used by commands such as setup, status, and policy calls. MURPH_PORT controls the local server port when starting Murph from the CLI. MURPH_HEARTBEAT_INTERVAL_MS controls how often the runtime checks scheduled background work, including whether any source-index provider is due; it does not force every provider to rebuild on every heartbeat.

MURPH_DISTRIBUTION=team is the supported compatibility value for the runtime distribution. MURPH_PRODUCT_MODE=channel is kept only as a compatibility alias. Unsupported distribution values are rejected.

Most runtime config keys also have environment-variable equivalents, but those should be treated as explicit overrides. If you override the local origin with MURPH_URL, MURPH_PORT, MURPH_APP_URL, or DISCORD_REDIRECT_URI, update provider callback URLs to match before reconnecting the channel.

Policy

Policy controls whether Murph sends, queues, or abstains from a drafted action. Runtime grounding is separate: it checks whether required read/context tools were attempted before Murph answers.

Built-in profiles include:

• default
• engineering
• product
• investor
• yolo

Role profiles are conservative by default and keep auto-send off. yolo is an explicit maximum-autonomy preset for trusted local runs; grounding still runs as a runtime obligation outside the policy gate. Use:

murph policy profiles
murph policy get
murph policy set --profile engineering

The durable policy profile is stored in ~/.murph/config.yaml:

policy:
  profile: engineering

New sessions inherit the selected profile's mode by default. Use a session-level mode only for a temporary override such as dry-run or review-everything testing.

There is no separate policy.mode config value. To change the default execution mode, select a different profile or edit the selected profile's mode.

Use Policy for custom profiles. Murph Agent is the preferred path for creating or changing custom policy; direct profile files live in ~/.murph/policies/*.md.

The OSS Admin page shows the selected profile and effective behavior, but policy changes belong to murph policy or murph agent.

Local health

Use the doctor check after changing configuration:

murph doctor