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 * * *",
        prompt: "Check for anything that needs my attention today.",
        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}",
    },
    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",
    },
  },

  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

Cron-based job scheduling and proactive heartbeat.

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

Each job:

FieldTypeDescription
idstringUnique job identifier
cronstringCron expression (validated by node-cron)
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)

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

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