Configuration & SOUL

Every variable, file, and manifest slaude reads at boot — with types, defaults, and copy-paste examples. One page to go from zero env to a validated deploy.

This page is the single source of truth for runtime configuration. It mirrors src/config/env.ts, src/config/home.ts, src/soul/*, and src/cli/validate.ts — if code and this page disagree, code wins and this page has a bug.

On this page:

• Slack tokens & app setup
• Anthropic auth & model selection
• Runtime environment variables
• Filesystem layout — SLAUDE_HOME
• Connect broker
• SOUL.md — persona schema
• Dependency manifests — slaude.json & slaude.lock
• External MCP — .mcp.json
• Validation — bun run validate-soul

Slack #

slaude speaks to Slack exclusively through Socket Mode (no public HTTP endpoint). Two tokens and one app-level scope make that work.

Tokens#

Callout — Do not commit tokens. .env and ~/.slaude/.env are gitignored. If a token appears in git diff --cached, git reset immediately and rotate it in Slack. Treat xoxb/xapp/xoxp with the same care as sk-ant.

Socket Mode & required scopes#

slaude is Socket Mode-only. The manifest at src/cli/manifest.ts declares these bot scopes — install will fail if any are missing:

{
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "canvases:write",
        "channels:history",
        "channels:manage",
        "channels:read",
        "chat:write",
        "chat:write.public",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "groups:write",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:write",
        "reactions:read",
        "reactions:write",
        "users:read",
        "users.profile:write",
        "assistant:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "interactivity": { "is_enabled": true },
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "assistant_thread_started",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim"
      ]
    },
    "org_deploy_enabled": false
  }
}

App-level scopes & setup checklist#

Setup checklist (api.slack.com/apps):

1. bun run manifest > manifest.json → Create New App → From manifest → paste.
2. Basic Information → App-Level Tokens → create token → enable connections:write → copy xapp-… as SLACK_APP_TOKEN.
3. OAuth & Permissions → Install to workspace → copy xoxb-… as SLACK_BOT_TOKEN. Reinstall after any manifest change.
4. Agents & AI Apps → enable assistant view (unlocks status indicator, requires assistant:write).
5. Socket Mode → enable (must be on; no HTTP Events URL needed).

Agents & AI status#

When assistant:write is granted, slaude calls assistant.threads.setStatus to show live status in the thread header: is thinking…, running Read …, writing file …. No extra env needed — if the scope is missing the call is silently skipped and threads still work, just without the animation.

Optional — post as the real user#

Security note for SLACK_POST_AS_USER — reads also route through the user token in this mode, so the xoxp must carry both write scopes (chat:write, reactions:write, files:write, plus canvases:write, pins:write, channels:manage and groups:write for the Canvas, pin and topic tools) and read scopes (channels:history, groups:history, im:history, users:read, and search:read for search_messages). The agent's read reach equals the human account's (private channels and DMs included). Only enable for accounts whose full scope you are comfortable exposing to tool use.

# .env — bot-only (default, recommended)
SLACK_BOT_TOKEN=xoxb-1234567890-XXXXXXXXXXXX
SLACK_APP_TOKEN=xapp-1-A111-abc123def456

# .env — post as your real Slack user (opt-in)
SLACK_USER_TOKEN=xoxp-1234567890-XXXXXXXXXXXX
SLACK_POST_AS_USER=true

Anthropic auth & model selection #

slaude talks to any Anthropic-compatible Messages API. That includes api.anthropic.com, OpenRouter, Z.ai, or a self-hosted gateway — same wire format, different base URL.

Auth modes — pick one#

Rules:

• API key wins when both are set. Explicit ANTHROPIC_API_KEY beats CLAUDE_CODE_OAUTH_TOKEN.
• ANTHROPIC_AUTH_TOKEN — alternative bearer token for gateways that expect Authorization: Bearer instead of x-api-key. Rarely needed; ANTHROPIC_API_KEY covers Anthropic and most gateways.
• Generate the OAuth token: on a machine already logged into Claude Code, run claude setup-token, paste the sk-ant-oat01-… value into slaude's env. Both the SDK child and the soul extractor (src/soul/extract.ts) auto-detect it.

# Gateway matrix — same .env shape for every provider
# Anthropic direct (default base URL)
ANTHROPIC_API_KEY=sk-ant-...

# OpenRouter / Z.ai / self-hosted — point the base URL, pin a provider-qualified model (required)
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
ANTHROPIC_API_KEY=sk-or-...          # OpenRouter key
SLAUDE_MODEL=anthropic/claude-sonnet-4-6

# Claude Pro / Max subscription — no API key, inherits subscription default model
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
# leave SLAUDE_MODEL unset to inherit the subscription default — set it only to pin a tier-allowed model

# .env — auth validation errors you will see
# missing both keys:
#   Error: missing env SLACK_BOT_TOKEN          (startup, from src/config/env.ts req())
#   Error: missing auth: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN   (soul extractor / model listing)

ANTHROPIC_BASE_URL — gateways#

Additional provider env forwarded to the SDK child (and scrubbed from telemetry paths) by src/agent/manager.ts:

ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN,
CLAUDE_CODE_OAUTH_TOKEN
→ forwarded as providerEnv
DISABLE_TELEMETRY=1, DISABLE_AUTOUPDATER=1,
DISABLE_BUG_COMMAND=1, DISABLE_ERROR_REPORTING=1,
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
→ forced to 1 so non-Anthropic gateways do not crash on telemetry

Model selection — precedence & the small/fast model#

There is no per-tier var like ANTHROPIC_OPUS_MODEL / ANTHROPIC_SONNET_MODEL. Only two vars are honoured:

Precedence in the SDK child (from src/agent/manager.ts):

1. options.model  (= SLAUDE_MODEL, when non-empty)   ← highest, set per-session at boot + via /model
2. ANTHROPIC_MODEL  (CLI-native env, when SLAUDE_MODEL empty)
3. CLI built-in default for the active auth mode
     • under CLAUDE_CODE_OAUTH_TOKEN → subscription default (leave both unset)
     • under ANTHROPIC_API_KEY       → Anthropic default model

When to leave SLAUDE_MODEL unset. With CLAUDE_CODE_OAUTH_TOKEN you usually want to inherit the subscription default — the SDK chooses a tier-allowed model automatically. Set SLAUDE_MODEL only to pin a specific model, or when using ANTHROPIC_BASE_URL.

# Model selection examples

# 1. Subscription — inherit default (recommended for CLAUDE_CODE_OAUTH_TOKEN)
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
# (no SLAUDE_MODEL, no ANTHROPIC_MODEL)

# 2. Subscription — pin a tier-allowed model
CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
SLAUDE_MODEL=claude-sonnet-4-6

# 3. Non-Anthropic gateway — SLAUDE_MODEL is required
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
ANTHROPIC_API_KEY=sk-or-...
SLAUDE_MODEL=anthropic/claude-sonnet-4-6
# If SLAUDE_MODEL is missing on OpenRouter/Z.ai the request fails:
#   extractor http 400 / SDK model-not-found — provider does not recognise the default model id

# 4. CLI-native fallback (SLAUDE_MODEL unset, ANTHROPIC_MODEL set)
ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-haiku-4-5

# 5. Fast-tier override (independent of main model)
ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

Per-thread model switching is also available at runtime via /model (and slaude model MCP) — it calls Query.setModel() live and persists to sessions.model for resume. The env vars above are the boot default.

Runtime environment variables #

All vars are read via src/config/env.ts (req() throws on missing, opt() returns "" or a fallback). SLAUDE_HOME and its derived paths live in src/config/home.ts.

Required#

Anthropic / provider#

Slack — optional#

Home & paths#

See Filesystem layout for every file under SLAUDE_HOME.

Queue & Redis — horizontal scale #

Used by the gateway/node split (src/queue/): BullMQ turn queues, the warm-session registry, session/leader locks, and abort/reload/gate pub-sub. A single-process (mono) deploy never touches Redis and needs none of these.

Tests for this layer run only against a real Redis (BullMQ's Lua scripts don't run on ioredis-mock) and are gated on SLAUDE_REDIS_TEST_URL, mirroring the SLAUDE_PG_TEST_URL gate for Postgres.

Control panel — operator web console #

What it does and how to enable it: Control panel.

The panel mounts at /panel on the gateway's HTTP server for the mono and gateway roles (never node). It is its own OIDC relying party: it authenticates the operator against a single issuer and mints its own session cookies. It stores no operator records — identity comes from an ID-token claim and roles come from a file or the env lists below.

¹ Required when SLAUDE_PANEL=1; ignored otherwise.

Boot also fails if both role lists resolve empty (a panel nobody can reach is a misconfiguration, not a safe default), or if the removed SLAUDE_PANEL_ALLOW is still set — a leftover allowlist would silently stop granting the access its operator believes it grants.

Sessions are a 15-minute access token and an 8-hour refresh token, both HttpOnly; Secure; SameSite=Lax. The refresh window is absolute — after 8 hours the operator re-authenticates at the provider. There is no revocation: removing someone from the role list blocks them at their next request, but a stolen cookie stays valid until it expires. Serve the panel over TLS; the cookies are Secure and browsers will not send them over plain HTTP.

Deployment walkthrough, role-file example and cross-replica behaviour: Multi-node scale-out.

Sessions & UX#

Metrics & context budget#

MCP OAuth — loopback vs paste-back#

Two modes for the authorization-code callback when connecting HTTP MCP servers via /mcp connect in /1on1:

# MCP OAuth examples

# Loopback (default, local / same-host container) — no extra env; ephemeral port
# SLAUDE_OAUTH_LOOPBACK_HOST=0.0.0.0 in-container so docker -p mapping is reachable

# Paste-back (k8s / remote)
SLAUDE_OAUTH_REDIRECT_URL=https://slaude.example.com/oauth/paste
# That static page must display `code` and `state` and instruct the user to paste the full callback URL back into the locked Slack thread.

# Shared always-on loopback (multi-session concurrency behind one port)
SLAUDE_OAUTH_SHARED_LOOPBACK=true
SLAUDE_OAUTH_SHARED_LOOPBACK_PORT=3118
SLAUDE_OAUTH_PUBLIC_URL=https://slaude.example.com
SLAUDE_OAUTH_LOOPBACK_HOST=0.0.0.0
SLAUDE_OAUTH_LOOPBACK_PORTS=40100-40110

Skills repo & evolution#

External MCP env references#

Any env var referenced via ${VAR} inside ~/.slaude/.mcp.json is expanded at load time (see External MCP). Common examples:

# Full .env example — copy to ~/.slaude/.env and fill in
# --- Slack (required) ---
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# --- Slack optional ---
# SLACK_USER_TOKEN=xoxp-...       # presence / post-as-user
# SLACK_POST_AS_USER=false

# --- Provider (pick ONE auth mode) ---
ANTHROPIC_API_KEY=sk-ant-...
# CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
# ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
# ANTHROPIC_AUTH_TOKEN=...
# SLAUDE_MODEL=claude-sonnet-4-6
# ANTHROPIC_MODEL=claude-sonnet-4-6
# ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

# --- Home ---
# SLAUDE_HOME=~/.slaude
# SLAUDE_DB_PATH=db.sqlite
# SLAUDE_DB=pg
# SLAUDE_PG_URL=postgres://slaude:change-me@localhost:5432/slaude
# SLAUDE_MASTER_KEY=<openssl rand -base64 32>
# SLAUDE_WORKSPACES=workspaces

# --- Sessions ---
SLAUDE_DEFAULT_MODE=ask
SLAUDE_AUTO_ALLOW_TOOLS=Read,Grep,Glob,LS
SLAUDE_IDLE_MINUTES=15
SLAUDE_HEALTH_PORT=8080
# SLAUDE_TOKEN_WARN_PCT=0.8
# SLAUDE_TOKEN_CRITICAL_PCT=0.92
# SLAUDE_FALLBACK_CONTEXT_WINDOW=200000

# --- Approvers fallback (SOUL.md wins when present) ---
SLAUDE_APPROVERS=

# --- Metrics ---
# SLAUDE_METRICS_LABELS=agent=hermes,env=prod
# SLAUDE_METRICS_PER_USER=0

# --- MCP OAuth (loopback by default; set redirect for k8s paste-back) ---
# SLAUDE_OAUTH_REDIRECT_URL=https://slaude.example.com/oauth/paste
# SLAUDE_OAUTH_LOOPBACK_HOST=127.0.0.1
# SLAUDE_OAUTH_LOOPBACK_PORTS=40100-40110
# SLAUDE_OAUTH_SHARED_LOOPBACK=
# SLAUDE_OAUTH_SHARED_LOOPBACK_PORT=3118
# SLAUDE_OAUTH_PUBLIC_URL=
# SLAUDE_OAUTH_STATE_SECRET=

# --- Skills evolution ---
# SLAUDE_SKILLS_REPO=github:owner/repo
# SLAUDE_AUTO_EVOLVE=1
# SLAUDE_SOUL_PARSE_MAX_TOKENS=8192
# SLAUDE_SOUL_PARSE_MODEL=claude-haiku-4-5-20251001

# --- External MCP vars referenced from .mcp.json ---
GRAFANA_URL=
GRAFANA_API_KEY=

Filesystem layout — SLAUDE_HOME #

SLAUDE_HOME defaults to ~/.slaude (src/config/home.ts → process.env.SLAUDE_HOME || join(homedir(), ".slaude")). Every path below is resolved against it — see overrides SLAUDE_DB_PATH and SLAUDE_WORKSPACES above.

~/.slaude/
├── SOUL.md              # persona (you author this)
├── .env                 # env — never commit
├── .mcp.json            # external MCP servers
├── slaude.json          # dependency manifest
├── slaude.lock          # pinned shas
├── db.sqlite            # sessions + overrides + jobs
├── cache/
│   └── soul.<sha>.json  # LLM-extracted SoulData cache
├── skills/
│   └── <slug>/SKILL.md
├── knowledge/
│   └── <label>/         # markdown wiki per KB
├── workspaces/
│   └── T111-C222-1700000000.000000/
├── .claude/
│   ├── plugins/
│   │   └── installed_plugins.json
│   └── projects/        # per-session transcripts
└── personas/            # multi-persona (optional)
    └── <name>/
        ├── SOUL.md
        └── mcp.json

Container note. When SLAUDE_HOME is mounted from a read-only image layer, use SLAUDE_DB_PATH and SLAUDE_WORKSPACES to place mutable state on a separately-mounted volume. install.ts stages clones inside a sibling of the eventual destination (not $SLAUDE_HOME/.tmp) so renameSync stays on the same filesystem across PVC subPath volumes.

Connect broker #

slaude ships two connection models. Understanding which you need avoids over-configuring.

/1on1 mode (shipped, no extra env)#

/1on1 locks a thread to you + manager and isolates the Claude child's CLAUDE_CONFIG_DIR per initiator ($SLAUDE_HOME/oauth/<userId>). This is slaude's per-thread contextual MCP story — it works with no broker env. Most teams only need this.

Connect broker — when you need it#

The connect broker exposes per-user OAuth'd MCP connections as slaude tools scoped to the calling thread. It is off by default. When disabled, no slaude_connect tools mount at all — /1on1 still works but there is no cross-user MCP brokering.

Current code: the broker gate is documented in README.md as SLAUDE_ENABLE_CONNECT_BROKER + SLAUDE_ENCRYPTION_KEY. At the time this page was written those two vars are referenced as the broker's mount condition and the encryption secret (32-byte base64, e.g. openssl rand -base64 32), and src/agent/child-env.ts scrubs SLAUDE_ENCRYPTION_KEY from the SDK child env so it never leaks to the model. If you enable the broker you must set both — one without the other leaves the tool unmounted.

# Connect broker — OFF by default (no tools mounted)
# SLAUDE_ENABLE_CONNECT_BROKER=
# SLAUDE_ENCRYPTION_KEY=

# Enable (both required):
SLAUDE_ENABLE_CONNECT_BROKER=1
SLAUDE_ENCRYPTION_KEY=$(openssl rand -base64 32)   # 32 random bytes, base64

Key hygiene. SLAUDE_ENCRYPTION_KEY is the encryption-at-rest key for broker-held secrets. Rotate by re-encrypting stored credentials; do not reuse a development key in production. The child-env scrub guarantees the model cannot exfiltrate it via tool args.

SOUL.md — persona schema #

SOUL.md is the operator-authored file at ~/.slaude/SOUL.md (or ~/.slaude/personas/<name>/SOUL.md in multi-persona mode). On first boot if the file is missing, slaude seeds the starter scaffold from src/soul/loader.ts — fill it in before going live.

The runtime enforces two layers:

• Runtime baseline (in code, RUNTIME_BASELINE in loader.ts) — non-negotiable rules about Slack output discipline, formatting, approval, engagement, channel trust, KB-first, skill evolution, and harness overrides. You never author this; a new release can tighten it without touching your persona.
• Persona (your SOUL.md) — who the agent is: name, role, voice, manager, mandate, values, channels, approvers, redaction. This is what the agent's system prompt renders inside <persona>…</persona>.

Structured extraction (src/soul/extract.ts) calls the configured provider with EXTRACTION_PROMPT (src/soul/data.ts), validates the JSON with SoulDataSchema (zod), checks that every extracted Slack id appears verbatim in the raw persona (hallucinated ids are rejected), and caches the result at ~/.slaude/cache/soul.<sha>.json keyed by sha256(SOUL.md). On any extraction failure it falls back to a regex parser that only fills approvers.

Validated schema — what extraction looks for#

Every field below is optional in the markdown (the extractor omits what it cannot find), but three are required for bun run validate-soul to pass: identity.name, manager.userId, mandate.

Required vs warnings — what validate-soul checks#

src/soul/validate.ts implements validateSoul(data):

• Missing (blocks ok): identity.name, manager.userId, mandate — any empty/absent → missing: [...], exit 1.
• Warnings (do not block ok, but review):
  • approvers empty → request_approval falls back to SLAUDE_APPROVERS env or accepts anyone.
  • allowedChannels + trustedChannels both empty → only manager/backup can chat outside DMs.
  • backupManager.userId === manager.userId → backup is redundant.
  • Any redactPatterns entry that fails new RegExp(p, "gi") → rejected as invalid regex.

Writing SOUL.md — section cookbook#

Every list below is one id per line, in any of these forms: <@U0XXXXXXXXX>, <#C0123456789|name>, raw U0XXXXXXXXX / C0123456789. Trailing ; starts an inline comment.

# Persona

## Identity
- Name: Slaude
- Role: engineering teammate in #platform
- Voice: terse, direct, no filler. fragments OK.

## Reporting
- Manager: U0MANAGER123
- Manager handle: @you
- Backup manager: U0DEPUTY456
- Backup manager handle: @deputy

## DM allowlist
- <@U0TEAMMATE1>
- <@U0TEAMMATE2>

## Redaction
- AKIA[0-9A-Z]{16}                  ; AWS access keys
- ghp_[0-9A-Za-z]{36}               ; GitHub personal tokens
- xox[baprs]-[0-9A-Za-z-]{10,}      ; Slack tokens

## Approval timeout
- 600

## Allowed channels
- <#C0123456789|engineering>
- <#G0123456789|private-ops>

## Trusted channels
- <#C0711111111|squadron-team>

## Values
- Ownership over ceremony. Ship the smallest thing that proves the idea.
- Prefer explicit defaults over clever inference.

## Mandate
- Own the #platform Slack surface. Triage threads, ship fixes, keep context warm so humans can delegate async.

## Approvers
- <@U0MANAGER123>:    anything                ; catchall, always eligible
- <@U0REVIEWER123>:   code changes, repo writes, refactors, dependency bumps
- <@U0DBA123>:        database migrations, schema changes, prod data, SQL
- <@U0SRE123>:        deploys, infra, kubernetes, rollbacks, ingress, CI/CD
- <@U0SECURITY123>:   secrets, credentials, IAM, env vars, OAuth scopes
- <@U0COMMS123>:      external comms, customer messages, emails, social

Approvers #

Each approver line is <id-or-mention>: <scope description> — one per person.

- <@U123>: anything                                    → catchall — always eligible
- <@U456>: database migrations, schema changes, SQL    → keyword-matched against the agent's plan summary
- <@U777>: production deploys, infra, kubernetes
- <@U888>: external comms — emails, customer messages

Catchall keywords (case-insensitive, tested at start of scope): anything, any, all, *, default, catchall, everything — marked catchall: true, always included.

Keyword matching (src/soul/loader.ts → selectApprovers / tokenize): the runtime tokenizes the plan summary and each approver's scope (lowercased, split on [^a-z0-9], crude-stemmed s|es|ing|ed, stopword-filtered, minimum 3 chars), then selects every approver whose scope tokens overlap with summary tokens, plus all catchalls. If nothing matches, it falls back to every listed approver so the request is not undeliverable. Comma, dash, and and are equivalent separators in scope text.

Fallback chain:

1. ## Approvers exists → keyword-matched entries from SOUL.md (or channel override when in that channel).
2. No ## Approvers → SLAUDE_APPROVERS env (comma-separated ids, no scopes — all treated as catchalls).
3. Neither → any clicker accepted (only safe for solo / DM workspaces).

Grounding guard. The extractor verifies every id it returns appears verbatim in the raw SOUL.md text (assertIdsGroundedInPersona in extract.ts). A hallucinated id is thrown rather than widening the allowlist.

Channel overrides #

Repeatable ## Channel <#Cxxx|name> (or raw Cxxx/Gxxx/Dxxx) blocks replace the global Mandate and/or Approvers when slaude operates in that channel. Replace semantics — absent subsection falls back to global.

The manager and backup manager are always retained as catchall approvers in every channel override (withManagerApprover in extract.ts) — a channel block can only add approvers, never lock the operator out.

## Channel <#C0999999999|incidents>

### Mandate
- Own incident triage in #incidents — acknowledge within 2 minutes, keep the timeline, page on-call if needed.

### Approvers
- <@U0INCIDENTLEAD>: anything             ; catchall for this channel
- <@U0DBA123>:       migrations, SQL, schema changes

Resolution at runtime: effectiveSoulForChannel(channelId) in extract.ts starts from the global soulData() (runtime overlays preserved), looks up the matching channelOverrides entry, and applies: mandate replaced when the override sets one (non-empty after trim), approvers replaced when the override lists ≥ 1. The channel mandate is injected as <channel-mandate> directive that supersedes the global Mandate for that channel.

Template stub block. The seeded SOUL.md contains a ## Channel <#C0123456789|example-channel> stub with a placeholder id — the extractor skips it (placeholder ids like C0123456789 and <@manager-id> are ignored). Delete the stub or fill it with a real channel id.

Minimal valid SOUL.md#

This is the smallest file that passes bun run validate-soul:

# Persona

## Identity
- Name: Slaude

## Reporting
- Manager: U0MANAGER123

## Mandate
- Own the #engineering Slack surface — triage, ship, keep context warm.

bun run validate-soul
# [validate] ok                        → exit 0
# [validate] missing required fields:  → exit 1
#   - identity.name
#   - manager.userId
#   - mandate
# [validate] warnings:                 → exit 0, but review
#   - approvers is empty — request_approval blocks will fall back to env or accept anyone
#   - allowedChannels + trustedChannels both empty — only manager/backup can chat outside DMs

Add the optional sections above as your workspace grows. Update SOUL.md without a restart — soulData() re-reads overrides on every call, and the extractor cache is keyed by sha256(SOUL.md) so an edit triggers a fresh extraction on next boot.

Runtime overrides without redeploy #

Managers can mutate ACLs at runtime without editing SOUL.md or restarting. The soul_overrides sqlite table (effective view = (base ∪ adds) − removes per field) backs two surfaces:

• Slash: /soul trust <#Cxxx> / /soul allow <#Cxxx> / /soul block <@Uxxx> / /soul dm <@Uxxx> and their remove counterparts.
• MCP: slaude_soul_override with the same FIELD_ALIASES (trust→trustedChannels, allow→allowedChannels, dm→dmAllowedUsers, block→blockedUsers).

Validation (src/soul/overrides.ts → mutateOverride): id shape (^[CGD][A-Z0-9]+$ for channels, ^[UW][A-Z0-9]+$ for users), self-lockout guard (refusing to block the manager), authority check performed by the caller.

# Runtime ACL examples (Slack slash)
/soul trust <#C0711111111|squadron-team>   # add to trustedChannels
/soul block <@U0NOISY999>                  # block a noisy user in an otherwise trusted channel
/soul dm <@U0TEAMMATE1>                    # allow DM from a teammate

Dependency manifests — slaude.json & slaude.lock #

slaude.json and slaude.lock live at ~/.slaude/slaude.json and ~/.slaude/slaude.lock. They are the declarative dependency surfaces for plugins, skills, and knowledge bases — MCP is deliberately excluded and stays in .mcp.json.

Schema lives in src/config/manifest-schema.ts; installer is src/cli/install.ts (bun run install-deps / slaude install).

slaude.json#

Entry shapes:

// Plugin — explicit marketplace git + plugin name + ref
{ marketplace: "github:owner/repo" | "https://…", plugin: "my-plugin", ref: "v1.2.3" }

// Skill — three mutually exclusive modes
{ source: "owner/repo" }                          // vercel-style, ref defaults to "main"
{ source: "owner/repo/skill-path" }               // path inside repo
{ source: "owner/repo@ref" }                      // pinned ref
{ source: "owner/repo/skill-path@ref" }
{ git: "github:owner/repo", ref: "main" }         // git-backed
{ slug: "local-skill" }                           // local (no git)

// Knowledge — label + optional git
{ label: "my-kb", git: "github:owner/repo", ref: "main", path: "wiki" }
{ label: "local-kb" }                             // local

Source → git resolution (resolveSkillSource): owner/repo[/path][@ref] → { git: "github:owner/repo", ref: "<ref or main>", path?: "<path>" }. Slug resolution falls back to last path segment or repo name lowercased.

Full example:

{
  "plugins": [
    { "marketplace": "github:example/marketplace", "plugin": "my-plugin", "ref": "v1.2.3" }
  ],
  "skills": [
    { "source": "example/repo/my-skill@v1.0.0" },
    { "git": "github:example/other-repo", "ref": "main" },
    { "slug": "local-helper" }
  ],
  "knowledge": [
    { "label": "team-wiki", "git": "github:example/team-wiki", "ref": "main" }
  ]
}

slaude.lock#

Pinned shas produced by bun run install-deps. Every entry records the resolved 40-char sha so builds are reproducible.

Installer flags:

Install layout inside SLAUDE_HOME:

Dockerfile pattern. Run slaude install --frozen inside the Dockerfile before the runtime stage so the image ships self-contained with no network at boot. Stage clones inside a sibling of the eventual destination (not $SLAUDE_HOME/.tmp) so renameSync stays on the same filesystem across PVC subPath volumes.

No slaude.json → no-op. If ~/.slaude/slaude.json is missing the installer logs no slaude.json — nothing to install and exits 0.

External MCP — .mcp.json #

External MCP servers are declared in ~/.slaude/.mcp.json (global) or ~/.slaude/personas/<name>/mcp.json (per-persona overlay in multi-persona mode). Missing file → empty result — slaude still boots.

Loader: src/gateway/core/external-mcp.ts → loadExternalMcp(personaName?) + parseExternalMcp(parsed, env).

File shape#

{
  "mcpServers": {
    "workbench": {
      "type": "http",
      "url": "https://workbench.example.com/mcp",
      "headers": { "Authorization": "Bearer ${GRAFANA_API_KEY}" }
    },
    "local-tool": {
      "command": "node",
      "args": ["./server.js", "--port", "${PORT}"],
      "env": { "API_KEY": "${MY_API_KEY}" }
    }
  },
  "privateServices": ["workbench"]
}

Env substitution: every ${VAR} placeholder across env values, headers values, url, and args entries is expanded via env[VAR] ?? "". Use it to keep secrets out of the file:

{
  "mcpServers": {
    "grafana": {
      "type": "http",
      "url": "${GRAFANA_URL}",
      "headers": { "Authorization": "Bearer ${GRAFANA_API_KEY}" }
    }
  }
}

# .env companions for the .mcp.json above
GRAFANA_URL=https://grafana.example.com/mcp
GRAFANA_API_KEY=eyJrIjoi…

Trust boundary for private services: inside a /1on1 locked thread, each privateServices entry is mounted as a clearCredentials copy — env and headers emptied, URL username/password/search/hash stripped. Host/path preserved so the server still launches and reaches its endpoint — just anonymous. Source map is never mutated.

Plugin .mcp.json landmine: claude-agent-sdk 0.1.x handles --plugin-dir (skills/commands/hooks/agents) but does not mount the plugin's .mcp.json MCP servers. slaude works around this by loading each installed plugin's .mcp.json in src/config/plugins.ts (loadInstalledPluginMcps) and merging them into Options.mcpServers. npx is also rewritten to bunx so plugins authored for Node still work on slaude's bun-only base image.

Per-session mount: the gateway's McpResolver resolves mcpServers fresh per session; the private-services override is applied when the thread is /1on1-locked. GET /readyz and POST /mcp style flows use this same resolver.

Validation — bun run validate-soul #

Validate ~/.slaude/SOUL.md against the required schema at any time — locally, in CI, or before a deploy.

bun run validate-soul
# alias: bun src/cli/validate.ts

# Exit codes
#   0 — ok (all required fields present; warnings may still print)
#   1 — missing required fields (identity.name, manager.userId, or mandate)
#   2 — extraction failure (missing auth: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN, or provider unreachable)

What it does (src/cli/validate.ts + src/soul/validate.ts):

1. loadSoulData() — cache hit (~/.slaude/cache/soul.<sha>.json) → return; otherwise call the provider's /v1/messages with EXTRACTION_PROMPT, validate with SoulDataSchema, assert every extracted Slack id appears verbatim in SOUL.md, cache, return. On any failure → regex fallback (approvers only).
2. validateSoul(data) — check the three required fields; emit warnings for empty approvers, empty channels, redundant backup manager, invalid redactPatterns regexes.
3. Print missing to stderr, warnings to stderr, and ok to stdout; exit with the code above.

# Success
$ bun run validate-soul
[validate] ok

# Missing required fields — still exits 1
$ bun run validate-soul
[validate] missing required fields:
  - identity.name
  - mandate
[validate] warnings:
  - approvers is empty — request_approval blocks will fall back to env or accept anyone
  - allowedChannels + trustedChannels both empty — only manager/backup can chat outside DMs

# Extraction failure — no auth configured (exit 2)
$ bun run validate-soul
[validate] failed to load SOUL.md: missing auth: set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN

# Warnings only — still exit 0 (review but deploy is not blocked)
$ bun run validate-soul
[validate] warnings:
  - approvers is empty — request_approval blocks will fall back to env or accept anyone
[validate] ok

CI recipe. Fail the build on exit 1 (missing identity), allow exit 0 with warnings (triage later), and treat exit 2 as a provider/config error — distinct from a bad SOUL.md.

# .github/workflows/validate.yml
- run: bun run validate-soul
# exit 0 → green (warnings are non-blocking)
# exit 1 → red — SOUL.md missing required fields
# exit 2 → red — extraction failure (check ANTHROPIC_API_KEY / CLAUDE_CODE_OAUTH_TOKEN)

When to re-validate. SOUL.md is re-read on every inbound message (soulData() applies runtime overlays per call and the extractor cache is keyed by sha256(SOUL.md)), but running validate-soul explicitly surfaces the missing/warnings breakdown and the exit code — useful after editing SOUL.md, after a /soul runtime override, or in a preflight check before docker build.

Quick reference — copy-paste starters#

# 1. Tokens — .env
SLACK_BOT_TOKEN=xoxb-1234567890-XXXXXXXXXXXX
SLACK_APP_TOKEN=xapp-1-A111-abc123def456
ANTHROPIC_API_KEY=sk-ant-...

# 2. Minimal SOUL.md → validate → boot
cat > ~/.slaude/SOUL.md << 'MD'
# Persona
## Identity
- Name: Slaude
## Reporting
- Manager: U0MANAGER123
## Mandate
- Own the #engineering Slack surface — triage, ship, keep context warm.
MD
bun run validate-soul   # → [validate] ok
bun run dev

# 3. Full SOUL.md once the team grows — add trusted channels, redaction, approvers
#    See the section cookbook above and the minimal valid example.

# 4. External MCP — .mcp.json with env substitution
cat > ~/.slaude/.mcp.json << 'JSON'
{
  "mcpServers": {
    "grafana": { "type": "http", "url": "${GRAFANA_URL}", "headers": { "Authorization": "Bearer ${GRAFANA_API_KEY}" } }
  },
  "privateServices": ["grafana"]
}
JSON

# 5. Dependencies — slaude.json + lock + frozen install (Dockerfile)
cat > ~/.slaude/slaude.json << 'JSON'
{ "skills": [{ "source": "example/repo/my-skill@v1.0.0" }], "knowledge": [{ "label": "team-wiki", "git": "github:example/wiki", "ref": "main" }] }
JSON
bun run install-deps          # resolve shas → slaude.lock
bun run install-deps --frozen # verify at build time (fails if lock is stale)

Related pages: Getting Started · Architecture · Guides · Deployment & Ops