⚙️ Configuration Reference

Randal is configured via a YAML file. Accepted filenames (checked in order):

1. randal.config.yaml
2. randal.config.yml
3. randal.yaml

Or specify explicitly: randal --config path/to/config.yaml <command>

All string values support ${ENV_VAR} substitution from the process environment. The parsed config is deeply frozen (immutable at runtime).

📋 Top-Level

Published Artifact Bootstrap

managed.bootstrap is optional and does not change normal local startup defaults.

managed:
  bootstrap:
    controlPlaneUrl: https://control-plane.example
    workspaceId: workspace-123
    versionId: version-7
    artifactUrl: https://control-plane.example/api/workspaces/workspace-123/setup-versions/version-7/config-export

Rules:

• only published artifacts may be referenced here
• this field is runtime bootstrap metadata, not Studio draft state
• the compiled runtime behavior must remain unchanged by default when managed.bootstrap is absent

🧩 Capabilities

The capabilities field declares core/runtime capability hints. Memory and scheduler remain core primitives. Optional agent tool packs such as Tavily, Image, Video, and Notion are configured through connectors instead of hard-coded capability/env detection.

Example:

# Explicitly declare all capabilities this agent uses
capabilities:
  - memory
  - scheduler

If capabilities is omitted or empty, core MCP servers are still wired based on other config sections such as memory.store, heartbeat.enabled, and cron.jobs.

Use randal connector enable <id> or the Console Connectors panel for optional guided connectors. In Docker/Railway overlay mode, Console-managed connector state is persisted separately at $RANDAL_STATE_DIR/connectors/overlay.yaml (or RANDAL_CONNECTOR_OVERLAY_PATH) while config-declared connectors remain authoritative over overlay entries with the same id.

🔄 Prompt Resolution

All prompt-bearing config fields (identity.persona, identity.systemPrompt, identity.rules, identity.knowledge, heartbeat.prompt, cron.jobs.*.prompt, tools.*.skill) support a unified three-layer resolution system. Values are resolved at prompt build time, not at config parse time.

Resolution Layers

Values are checked in this order:

Layer 3 (code module) is checked first, so ./foo.ts is treated as a code module, not a file reference.

Template Interpolation ({{var}})

File-loaded content (Layer 1) supports {{key}} template interpolation using variables from identity.vars plus auto-populated values:

User-defined vars take precedence over auto-populated vars with the same name. Unknown {{key}} placeholders are left as-is.

Important: {{var}} interpolation only applies to file-loaded content (Layer 1). It does not apply to code module output (Layer 3) or inline YAML values (Layer 0). Inline YAML values already have ${ENV_VAR} substitution at config parse time.

Code Module Contract

Code modules (.ts/.js) must export a default function:

import type { PromptContext } from "@randal/core";

// For string fields (persona, systemPrompt, heartbeat.prompt, etc.)
export default function(ctx: PromptContext): string | Promise<string>;

// For rules arrays, modules may also return string[]
export default function(ctx: PromptContext): string | string[] | Promise<string | string[]>;

PromptContext Interface

interface PromptContext {
  basePath: string;              // Directory containing randal.config.yaml
  vars?: Record<string, string>; // Template variables (identity.vars + auto-populated)
  configName?: string;           // From config.name
}

Examples

Inline string (Layer 0):

identity:
  persona: "You are a helpful AI assistant."

File reference with template vars (Layer 1):

identity:
  persona: ./IDENTITY.md
  vars:
    name: my-agent
    company: Acme Corp

Where IDENTITY.md contains:

# {{name}}
You are {{name}}, built by {{company}}.

Code module (Layer 3):

identity:
  systemPrompt: ./instructions.ts

Where instructions.ts contains:

import type { PromptContext } from "@randal/core";

export default function(ctx: PromptContext): string {
  const isWeekend = [0, 6].includes(new Date().getDay());
  return isWeekend
    ? "Focus on maintenance tasks today."
    : "Prioritize active development tasks.";
}

Mixed rules array:

identity:
  rules:
    - "NEVER delete data"
    - ./safety-rules.md
    - ./dynamic-rules.ts

File entries are split by newlines into individual rules. Code modules may return string (split by newlines) or string[].

🪪 identity

Agent identity and knowledge configuration. Defaults to {} if omitted.

The primary source-machine persona authoring flow is bun run scripts/persona-preseed.ts, which launches an OpenCode interview and writes both review artifacts and a Mac-mini-ready preseed bundle locally. randal init --persona remains available as a secondary local artifact writer.

The durable persona artifacts in that flow are:

• .randal/identity/persona.identity.yaml: structured YAML identity bundle intended to be the source of truth
• .randal/identity/PERSONA.md: readable persona document for human review
• IDENTITY.md: rendered compatibility artifact for existing prompt-resolution flows
• identity.ts: generated and manifest-tracked when the TypeScript identity compatibility path is selected

These generated files are tracked in .randal/managed-artifacts.yaml as Randal-managed outputs.

randal setup --preseed <file> accepts a trusted local wrapper bundle authored on a source machine and copied to the target Mac mini.

schemaVersion: "1"
kind: randal-preseed
trustedLocalOnly: true
authoring:
  sourceMachine: this-machine
  targetMachine: mac-mini
setup:
  configPath: randal.config.yaml
files:
  - scope: project
    path: randal.config.yaml
    kind: config
    content: |
      name: mac-mini-randal
      runner:
        workdir: .

Supported v1 keys:

• schemaVersion: must be "1"
• kind: must be randal-preseed
• trustedLocalOnly: must be true
• authoring.sourceMachine / authoring.targetMachine: optional handoff metadata for the source-machine -> target-machine workflow
• setup.configPath: project-local config path to hand to the normal setup pipeline after materialization
• setup.outputDir: optional OpenCode output override
• files[]: explicit file payloads to materialize before setup runs

Each files[] entry supports:

• scope: project or home
• path: relative path inside that scope
• kind: artifact label recorded in .randal/managed-artifacts.yaml
• content: plaintext file contents

Trusted-local-only note: plaintext secrets are supported in content, including .env payloads, but this format is intentionally not encrypted or remotely fetched in v1.

🎯 runner

Agent execution configuration. The runner section is required.

Cutover note: runner.compaction.* was removed. The only supported execution model is a brain-managed session backed by plan files plus canonical .opencode/loop-state.json state.

Loop-State Cutover

• .opencode/loop-state.json is the canonical durable build-state file.
• Build entries are keyed by plan slug, not by transient runner job ID.
• Corrupted loop-state files now raise explicit errors instead of being silently reset.
• Legacy runner-written statuses such as active, completed, and errored are no longer valid in canonical loop-state.

OpenCode OAuth Example

Use this when you want a headless Railway deploy to reuse a one-time local OpenCode login:

runner:
  defaultAgent: opencode
  defaultModel: openai/gpt-5.4
  workdir: /app/workspace
  opencodeAuth:
    mode: openai-oauth
    authFileEnv: OPENCODE_AUTH_JSON
  opencode:
    variant: xhigh

Bootstrap flow:

1. Run opencode auth login locally.
2. Copy ~/.local/share/opencode/auth.json into a secret named OPENCODE_AUTH_JSON.
3. Start Railway normally; the runner materializes the auth file before spawning OpenCode.

Security handling:

• Treat OPENCODE_AUTH_JSON like a credential.
• Store it in secret management only.
• Never commit it to the repo or paste it into issue threads.
• Avoid logging the JSON payload or writing ad hoc debug copies of the file.

Alternatives remain supported: API-key flows via OPENROUTER_API_KEY, OPENAI_API_KEY, or ANTHROPIC_API_KEY still work without runner.opencodeAuth.*.

🔐 credentials

Environment and secret management. Defaults to {} if omitted.

🧩 connectors

Optional agent tool connectors. Defaults to {} if omitted. Built-in manifests currently include tavily, image, and video under connectors/builtin/.

Connector config stores only non-secret state. Raw connector secrets are stored by the configured secret provider and injected only into spawned brain process environments.

Example:

connectors:
  tavily:
    source: builtin:tavily
    enabled: true
    secretScope: user
    settings:
      defaultSearchDepth: basic

Connector changes made through the gateway keep randal serve running. New sessions load the updated connector config; active brain sessions may be interrupted/reloaded so they can see updated tools.

🔑 secrets

Connector secret-provider configuration. Defaults to the local user env-file provider.

Scoped project .env fallback keys use <CONNECTOR_ID>__<SECRET_NAME>, for example TAVILY__TAVILY_API_KEY. Explicit process env mappings are resolved after scoped local/project files and before optional unscoped fallback keys. See Connectors and Secret Providers for the guided setup and storage model.

🔗 services

Named external service bindings with declarative credential delivery. Defaults to {} if omitted.

Each service is a named entry with a credential delivery mechanism and optional audit logging.

Credential Types

type: env — Inject environment variables directly.

type: file — Copy a credential file and set env vars pointing to it.

type: ambient — Keep existing host binaries and config dirs available.

type: script — Run a script before each job and capture output as credentials.

type: none — Explicitly block access to a service.

Example:

services:
  github:
    description: "GitHub via provisioned PAT"
    credentials:
      type: env
      vars:
        GH_TOKEN: ${GITHUB_PAT}
        GITHUB_TOKEN: ${GITHUB_PAT}
    audit: true

  # GitHub/GH CLI access is a core git-ops service binding today, not a
  # manifest connector. Use credentials/services for branch, PR, and checks work.

  gcloud:
    description: "Google Cloud via service account"
    credentials:
      type: file
      file: ./secrets/gcp-sa-key.json
      mountAs: /tmp/gcp-creds.json
      vars:
        GOOGLE_APPLICATION_CREDENTIALS: /tmp/gcp-creds.json

  aws:
    description: "AWS explicitly blocked"
    credentials:
      type: none
      binaries: [aws, aws-vault]
      vars: [AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN]

  internal-api:
    description: "Internal API via rotating token"
    credentials:
      type: script
      command: ./scripts/get-api-token.sh
      vars:
        INTERNAL_API_TOKEN: stdout
      ttl: 3600

🔒 sandbox

Process isolation configuration. Controls how aggressively Randal restricts the agent child process environment. Defaults to { enforcement: "none" } (current behavior preserved).

When any homeAccess flag is false, a temporary HOME directory is created with only the allowed config dirs symlinked in. The temp dir is cleaned up after the job completes.

Example:

sandbox:
  enforcement: env-scrub
  pathFilter:
    mode: allowlist
    allow: [/usr/bin, /usr/local/bin, ~/.bun/bin]
  homeAccess:
    ssh: false
    gitconfig: false
    aws: false

⬆️ updates

Self-update configuration. Defaults to { autoCheck: false, channel: "stable" }.

Example:

updates:
  autoCheck: true
  channel: stable

📡 gateway

Server and channel configuration. Defaults to {} if omitted.

🌐 HTTP Channel

Hosted HTTP Security Posture

Local development can keep using local-only tokens and same-origin browser access. Hosted deployments should fail closed by configuration:

• set auth: "${RANDAL_API_TOKEN}" with no fallback default
• set corsOrigin: "${RANDAL_CORS_ORIGIN}" to the exact trusted browser origin
• set runner.allowedWorkdirs to the mounted workspace directory
• keep allowQueryTokenAuth unset unless a legacy client migration requires it temporarily

runner:
  workdir: /data/randal/workspace
  allowedWorkdirs:
    - /data/randal/workspace

gateway:
  channels:
    - type: http
      port: 7600
      auth: "${RANDAL_API_TOKEN}"
      corsOrigin: "${RANDAL_CORS_ORIGIN}"

Built-In And Legacy Channel Types

Randal Console and custom relays should use the HTTP channel and /api/sessions/*. Some named adapter config schemas remain in the codebase for compatibility, but they are not the recommended first path for new product surfaces.

Legacy Named Chat Adapter Example

Prefer the Custom Relay Guide for new integrations.

🎙️ Voice Channel

Other Legacy Channel Schemas

Additional named channel schemas exist in packages/core/src/config.ts for compatibility and experiments. For new external products, keep product-specific SDKs in a custom relay and connect through the HTTP session API.

🧠 memory

Memory system configuration. Defaults to {} if omitted.

🗄️ database

database configures the Postgres source of truth. DATABASE_URL or RANDAL_DATABASE_URL may supply the URL at runtime.

Local singleton example:

memory:
  store: postgres
database:
  profile: local
  url: "${DATABASE_URL}"
  ssl: disable
  orgId: "00000000-0000-4000-8000-000000000001"
  projectId: "00000000-0000-4000-8000-000000000001"

Cloud tenant example:

memory:
  store: postgres
database:
  profile: generic
  url: "${DATABASE_URL}"
  ssl: require
  migrationMode: manual
  orgId: "${RANDAL_ORG_ID}"
  projectId: "${RANDAL_PROJECT_ID}"

Artifact metadata, redaction status, retention class, and checksums live in Postgres. External payload stores must be protected and copied separately when restoring or moving databases. See Postgres DAG Operations for runbooks.

🔌 Embedder Configuration

Nested under memory.embedder. Defaults to { type: "builtin" }.

Builtin (default, no configuration needed):

memory:
  embedder:
    type: builtin

OpenAI:

OpenRouter:

Randal-managed OpenRouter traffic uses canonical app attribution headers (HTTP-Referer: https://randal.bot, X-Title: Randal) for direct requests and generated OpenCode provider configuration. This attribution is intentionally not exposed as a normal user-facing override.

Ollama:

🛠️ tools

Array of external tool definitions. Defaults to [].

💰 tracking

Cost tracking configuration. Defaults to {}.

💓 heartbeat

The heartbeat is a periodic "check in and use your judgment" primitive. The agent wakes at a configured interval, reads a prompt/checklist, and decides whether anything needs attention.

Example:

heartbeat:
  enabled: true
  every: 30m
  prompt: ./HEARTBEAT.md
  activeHours:
    start: "08:00"
    end: "22:00"
    timezone: "America/Denver"
  model: anthropic/claude-haiku-4

📅 cron

Precise scheduled tasks with three schedule formats.

Schedule formats:

• ⏰ Cron expression: "0 7 * * *" (5-field: minute hour day-of-month month day-of-week)
• 🔄 Interval: { every: "30m" } (repeating interval)
• 🎯 One-shot: { at: "2026-03-15T14:00:00Z" } (fires once, then marked completed)

Example:

cron:
  jobs:
    morning-briefing:
      schedule: "0 8 * * *"
      prompt: "Review pending tasks. Compile a morning status."
      execution: isolated
      announce: true
    periodic-check:
      schedule: { every: "1h" }
      prompt: "Check system health."
      execution: main
    deploy-reminder:
      schedule: { at: "2026-03-15T14:00:00Z" }
      prompt: "Remind the team about the deployment."
      execution: isolated

🪝 hooks

External event triggers via HTTP webhooks.

When enabled, two endpoints are mounted:

• POST /hooks/wake — Wake the agent with a message. Modes: "now" (immediate heartbeat) or "next-heartbeat" (queued).
• POST /hooks/agent — Submit a job or queue a message. Modes: "now" (isolated job) or "next-heartbeat" (queued).

All requests require Authorization: Bearer <token> or x-randal-token: <token>.

Example:

hooks:
  enabled: true
  token: "${RANDAL_HOOK_TOKEN}"

# Trigger immediate heartbeat with context
curl -X POST http://localhost:7600/hooks/wake \
  -H "Authorization: Bearer $RANDAL_HOOK_TOKEN" \
  -d '{"text": "New VIP email received", "mode": "now"}'

# Queue for next heartbeat
curl -X POST http://localhost:7600/hooks/wake \
  -H "Authorization: Bearer $RANDAL_HOOK_TOKEN" \
  -d '{"text": "Low priority notification", "mode": "next-heartbeat"}'

📁 Example Configs

🏁 Minimal (local one-shot)

name: my-agent
runner:
  workdir: ~/dev/my-project

💻 Personal Dev Agent

name: dev-agent
identity:
  persona: "Senior TypeScript engineer"
  rules:
    - "Write tests for all new functions"
    - "Use Biome for formatting"
runner:
  defaultAgent: opencode
  defaultModel: anthropic/claude-sonnet-4
  defaultMaxIterations: 30
  workdir: ~/dev/my-project
credentials:
  envFile: ./.env
  allow: [ANTHROPIC_API_KEY]
gateway:
  channels:
    - type: http
      port: 7600
      auth: "${RANDAL_API_TOKEN}"
memory:
  store: postgres
database:
  url: "${DATABASE_URL}"

🏭 Production Agent with Postgres

name: support-agent
posse: production
identity:
  persona: "Customer support specialist"
  knowledge:
    - ./knowledge/help-center/*.md
    - ./knowledge/faq.md
  rules:
    - "Never delete production data"
    - "Never expose PII"
    - "Always escalate payment issues"
runner:
  defaultAgent: opencode
  defaultModel: claude-sonnet-4
  workdir: /home/node/workspace
credentials:
  envFile: ./.env
  allow: [ANTHROPIC_API_KEY, SUPABASE_URL, SUPABASE_AGENT_KEY]
gateway:
  channels:
    - type: http
      port: 7600
      auth: "${RANDAL_API_TOKEN}"
memory:
  store: postgres
  sharing:
    publishTo: shared
    readFrom: [shared]
database:
  profile: generic
  url: "${DATABASE_URL}"
  ssl: require
  migrationMode: manual

🛠️ Multi-Tool Agent

name: ops-agent
runner:
  defaultAgent: opencode
  workdir: ~/dev/infra
credentials:
  envFile: ./.env
  allow: [ANTHROPIC_API_KEY, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY]
  inherit: [PATH, HOME, SHELL, TERM, SSH_AUTH_SOCK]
gateway:
  channels:
    - type: http
      port: 7600
      auth: "${RANDAL_API_TOKEN}"
tools:
  - name: terraform
    binary: terraform
    skill: ./skills/terraform.md
    platforms: [darwin, linux]
  - name: kubectl
    binary: kubectl
    platforms: [darwin, linux]
tracking:
  tokenPricing:
    "anthropic/claude-sonnet-4":
      input: 0.000003
      output: 0.000015

💬 Personal Assistant with Console

name: assistant
identity:
  persona: "Personal dev assistant reachable through Randal Console and custom relays."
runner:
  defaultAgent: opencode
  defaultModel: claude-sonnet-4
  workdir: ~/dev
credentials:
  envFile: ./.env
  allow: [ANTHROPIC_API_KEY]
  inherit: [PATH, HOME, SHELL, TERM]
gateway:
  channels:
    - type: http
      port: 7600
      auth: "${RANDAL_API_TOKEN}"
memory:
  store: postgres
  autoInject:
    enabled: true
    maxResults: 5
database:
  url: "${DATABASE_URL}"

🎙️ Voice & Video

Browser/media voice requires LiveKit + STT + TTS configuration. PSTN calling requires Twilio in addition to that browser/media baseline.

🌐 Multi-Instance Mesh

📊 Analytics & Self-Learning

Analytics is default-on and stores annotations in the configured Postgres source of truth. In normal gateway mode, annotation-store initialization failure should degrade analytics with a visible warning/status rather than preventing startup. Inspect live data with randal analytics scores, randal analytics recommendations, and the analytics HTTP routes.

🌍 Browser Automation

🔄 Runner Extensions

MCP Server

💬 Additional Channel Types

The gateway has additional named channel schemas for compatibility and experiments. These are not the recommended path for new product surfaces; prefer a custom relay over /api/sessions/* unless you are maintaining existing adapter code.

Available community channel types: telegram, slack, email, whatsapp, signal, voice. Config schemas remain in packages/core/src/config.ts for reference.