Augureaugure

Configuration Reference

Complete reference for the augure.json5 configuration file

Augure uses a single JSON5 configuration file (augure.json5). JSON5 supports comments and trailing commas, making it suitable for human-edited config.

Environment Variable Interpolation

Secrets are injected via environment variables using ${VAR_NAME} syntax. The config loader replaces these placeholders at startup:

function interpolateEnvVars(raw: string): string {
  return raw.replace(/\$\{([^}]+)\}/g, (match, varName: string) => {
    const value = process.env[varName];
    if (value === undefined) {
      throw new Error(`Missing environment variable: ${varName}`);
    }
    return value;
  });
}

If a referenced variable is missing, the agent refuses to start. Keep all secrets in .env and reference them in the config.

Full Example

{
  identity: {
    name: "Augure",
    personality: "Helpful, proactive, concise. Speaks French by default.",
  },

  llm: {
    default: {
      provider: "openrouter",
      apiKey: "${OPENROUTER_API_KEY}",
      model: "anthropic/claude-sonnet-4-5",
      maxTokens: 8192,
    },
    ingestion: {
      model: "google/gemini-2.5-flash",
      maxTokens: 2048,
    },
    monitoring: {
      model: "google/gemini-2.5-flash",
      maxTokens: 1024,
    },
  },

  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowedUsers: [123456789],
    },
  },

  memory: {
    path: "./memory",
    autoIngest: true,
    maxRetrievalTokens: 2000,
  },

  scheduler: {
    heartbeatInterval: "30m",
    jobs: [
      {
        id: "morning-check",
        cron: "0 8 * * *",              // recurring
        prompt: "Check for anything that needs my attention today.",
        channel: "telegram",
      },
      {
        id: "remind-deadline",
        runAt: "2026-03-15T09:00:00Z",  // one-shot, auto-removed after execution
        prompt: "Remind about the project deadline.",
        channel: "telegram",
      },
    ],
  },

  sandbox: {
    runtime: "docker",
    image: "augure-sandbox:latest",  // optional, Docker image for containers
    defaults: {
      timeout: 300,        // seconds
      memoryLimit: "512m",
      cpuLimit: "1.0",
    },
    codeAgent: {           // optional, enables the "opencode" tool
      command: "claude-code",
      args: ["--no-interactive"],
      env: { ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}" },
    },
  },

  tools: {
    webSearch: {
      provider: "tavily",
      apiKey: "${TAVILY_API_KEY}",
    },
    browser: {
      provider: "browserbase",
      browserbase: {
        apiKey: "${BROWSERBASE_API_KEY}",
      },
      defaults: {
        timeout: 30,
        headless: true,
      },
    },
    http: {
      timeoutMs: 10000,
      presets: {
        github: {
          baseUrl: "https://api.github.com",
          headers: {
            Authorization: "Bearer ${GITHUB_TOKEN}",
            Accept: "application/vnd.github.v3+json",
          },
        },
      },
    },
  },

  skills: {
    path: "./skills",
    maxFailures: 3,
    autoSuggest: true,
    hub: {
      repo: "FaureAlexis/augure-skills",
      branch: "main",
    },
  },

  codeMode: {
    runtime: "auto",
    timeout: 30,
    memoryLimit: 128,
  },

  persona: {
    path: "./personas",
  },

  audit: {
    enabled: true,
    path: "./audit",
  },

  updates: {
    skills: { enabled: true, checkInterval: "6h" },
    cli: { enabled: true, checkInterval: "24h", notifyChannel: "telegram" },
  },

  mcp: {
    enabled: true,
    port: 3100,
  },

  approval: {
    enabled: true,
    timeoutMs: 120000,  // 2 minutes, auto-reject if no response
  },

  security: {
    sandboxOnly: true,
    allowedHosts: [],
    maxConcurrentSandboxes: 3,
  },
}

Sections

identity

Defines the agent's name and personality, injected into the system prompt.

FieldTypeRequiredDescription
namestringYesAgent display name
personalitystringYesPersonality description injected into the system prompt

llm

LLM provider configuration with per-usage model overrides. The default config is required; all other keys are optional overrides that inherit missing fields from default.

FieldTypeRequiredDescription
defaultLLMModelConfigYesDefault model configuration
reasoningPartial<LLMModelConfig>NoOverride for user-facing conversations
ingestionPartial<LLMModelConfig>NoOverride for memory extraction (use a cheap model)
monitoringPartial<LLMModelConfig>NoOverride for heartbeat checks (use a cheap model)
codingPartial<LLMModelConfig>NoOverride for code generation tasks

Each LLMModelConfig has:

FieldTypeDescription
provider"openrouter" | "anthropic" | "openai"API provider
apiKeystringAPI key (use ${ENV_VAR} syntax)
modelstringModel identifier
maxTokensnumberMaximum output tokens

channels

Messaging channel configuration. Currently only Telegram is fully implemented.

channels.telegram

FieldTypeDescription
enabledbooleanEnable the Telegram channel
botTokenstringBot token from @BotFather (use ${ENV_VAR})
allowedUsersnumber[]Array of Telegram user IDs allowed to interact
rejectMessagestringMessage sent to unauthorized users. Optional, silent drop if omitted

channels.whatsapp

FieldTypeDescription
enabledbooleanEnable the WhatsApp channel (not yet implemented)

channels.web

FieldTypeDescription
enabledbooleanEnable the web dashboard (not yet implemented)
portnumberHTTP port for the web interface

memory

Controls the filesystem-based memory system.

FieldTypeRequiredDescription
pathstringYesBase directory for memory files
autoIngestbooleanYesAutomatically extract observations from conversations
maxRetrievalTokensnumberYesMaximum tokens injected into context from memory (approx. 4 chars per token)

scheduler

Job scheduling (recurring and one-shot) and proactive heartbeat.

FieldTypeRequiredDescription
heartbeatIntervalstringYesInterval between heartbeat checks (e.g. "30m", "1h", "300s")
jobsSchedulerJobConfig[]YesArray of scheduled jobs

Each job must have either cron or runAt:

FieldTypeDescription
idstringUnique job identifier
cronstringCron expression for recurring jobs (validated by node-cron)
runAtstringISO 8601 date for one-shot jobs (e.g. "2026-03-15T14:00:00Z")
promptstringThe prompt sent to the agent when the job triggers
channelstringWhich channel to send results to

tools

Configuration for native tools.

tools.webSearch

FieldTypeRequiredDescription
provider"tavily" | "exa" | "searxng"YesSearch provider
apiKeystringFor Tavily/ExaAPI key
baseUrlstringFor SearXNGSelf-hosted instance URL
maxResultsnumberNoDefault max results (fallback: 5)

tools.http

FieldTypeRequiredDescription
defaultHeadersRecord<string, string>NoHeaders added to all HTTP requests
presetsRecord<string, HttpPreset>NoNamed preset configurations
timeoutMsnumberNoRequest timeout in milliseconds (default: 10000)
maxResponseBytesnumberNoMaximum response body size

Each HttpPreset:

FieldTypeDescription
baseUrlstringBase URL prepended when the tool URL does not start with http
headersRecord<string, string>Headers injected for this preset (typically auth tokens)

tools.browser

FieldTypeRequiredDescription
provider"local" | "browserbase"YesBrowser provider. local uses Playwright, browserbase uses cloud browsers
browserbaseobjectFor BrowserbaseBrowserbase credentials
browserbase.apiKeystringYesBrowserbase API key (use ${ENV_VAR})
browserbase.projectIdstringNoBrowserbase project ID
defaultsobjectNoDefault settings for browser sessions
defaults.timeoutnumberNoPage interaction timeout in seconds (default: 30)
defaults.headlessbooleanNoRun browser headless (default: true, local only)
defaults.viewportobjectNoDefault viewport { width, height } (default: 1280x720)

sandbox

Container execution configuration. The pool creates Docker containers on demand and caches idle ones, keyed by trust level (sandboxed = no network, trusted = host network).

FieldTypeRequiredDescription
runtime"docker"YesContainer runtime (only Docker supported)
imagestringNoDocker image to use (default: "augure-sandbox:latest")
defaults.timeoutnumberYesDefault execution timeout in seconds
defaults.memoryLimitstringYesContainer memory limit (e.g. "512m")
defaults.cpuLimitstringYesContainer CPU limit (e.g. "1.0")
codeAgentobjectNoConfiguration for the opencode tool (see below)

sandbox.codeAgent

When configured, enables the opencode tool which runs a coding agent (claude-code, opencode, codex) inside a Docker container.

FieldTypeRequiredDescription
commandstringYesCLI command to invoke (e.g. "claude-code")
argsstring[]NoAdditional arguments (e.g. ["--no-interactive"])
envRecord<string, string>NoEnvironment variables passed to the exec (e.g. API keys)

skills

Self-generated skill system configuration. When present, the agent can create, run, and auto-heal skills. Requires the sandbox section to be configured (skills execute in Docker containers).

FieldTypeRequiredDefaultDescription
pathstringYes"./skills"Base directory for skill files
maxFailuresnumberYes3Consecutive failures before a skill is paused
autoSuggestbooleanYestrueAllow the agent to suggest creating new skills
hubobjectNo--Curated skills hub configuration

skills.hub

FieldTypeRequiredDefaultDescription
repostringYes--GitHub repository in owner/repo format
branchstringNo"main"Branch to fetch skills from

codeMode

Optional. When present, enables Code Mode -- the LLM writes TypeScript that calls typed APIs in a sandbox instead of making individual tool calls.

FieldTypeDefaultDescription
runtime"vm" | "docker" | "auto""auto"Execution runtime. vm = Node.js vm module (fast), docker = container sandbox (isolated), auto = VM with Docker fallback
timeoutnumber30Maximum execution time in seconds
memoryLimitnumber128Memory limit in MB (VM runtime only; Docker uses sandbox.defaults.memoryLimit)

approval

Optional. When enabled, tools marked with riskLevel: "high" require explicit user approval before execution. The agent sends an approval request via the active channel (e.g. Telegram inline buttons) and waits for a response.

Currently, three tools are high-risk: sandbox_exec, opencode, and manage_skill.

FieldTypeDefaultDescription
enabledboolean--Enable the approval gate
timeoutMsnumber120000Milliseconds to wait before auto-rejecting

If the channel does not support interactive approval (e.g. not yet implemented for WhatsApp/web), high-risk tools are auto-approved with a warning log.

mcp

Optional. When present, enables the built-in MCP server for integration with Claude Desktop, Cursor, and other MCP clients.

FieldTypeDefaultDescription
enabledboolean--Enable the MCP HTTP server when the agent starts
portnumber3100HTTP port for the MCP server

The MCP server can also be started standalone via augure mcp (stdio transport) or enabled at runtime with augure start --mcp.

persona

Optional. Points to a directory of persona .md files (with YAML frontmatter). Personas are injected into the system prompt and exposed as MCP prompts.

FieldTypeRequiredDescription
pathstringYesDirectory containing persona markdown files

audit

Optional. When enabled, the agent writes an append-only audit log of all tool calls and LLM interactions.

FieldTypeRequiredDescription
enabledbooleanYesEnable audit logging
pathstringYesDirectory for audit log files

updates

Optional. Configures automatic update checks for skills and the CLI.

updates.skills

FieldTypeDefaultDescription
enabledboolean--Enable automatic skill update checks
checkIntervalstring--Interval between checks (e.g. "1h", "6h")

updates.cli

FieldTypeDefaultDescription
enabledboolean--Enable CLI version update checks
checkIntervalstring--Interval between checks
notifyChannelstring--Channel to notify about available updates

security

Global security settings.

FieldTypeRequiredDescription
sandboxOnlybooleanYesRequire all code execution in containers
allowedHostsstring[]YesRestrict outbound network to these hosts (empty = allow all)
maxConcurrentSandboxesnumberYesMaximum number of concurrent containers

Validation

The config is parsed and validated with Zod at startup. If any field is invalid or missing, the agent prints a clear error and exits. The full Zod schema is defined in packages/core/src/config.ts.

On this page