Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration File Reference

File Location

juglans.toml is read from the project root. The runtime walks up from the current working directory looking for the first ancestor containing a juglans.toml file (find_project_root). When no juglans.toml exists anywhere on the path up to root, defaults are used.

Per-user (~/.config/juglans/juglans.toml) and system-wide (/etc/juglans/juglans.toml) config paths are not searched. Per-deployment overrides go through environment variables instead — see Environment Variables.

Complete Configuration Example

[account]
id = "user_123"
name = "John Doe"
role = "admin"

[workspace]
id = "ws_default"
name = "My Workspace"
members = ["user_123", "user_789"]
agents = []  # deprecated, agents are now inline in .jg files
workflows = ["src/**/*.jg", "src/workflows/**/*.jgflow"]
prompts = ["src/prompts/**/*.jgx"]
tools = ["src/tools/**/*.json"]
exclude = ["**/*.backup", "**/test_*"]

[server]
host = "127.0.0.1"
port = 3000
endpoint_url = "https://agent.juglans.ai"

# LLM providers — juglans is local-first; configure at least one provider
[ai.providers.openai]
api_key = "${OPENAI_API_KEY}"

[ai.providers.anthropic]
api_key = "${ANTHROPIC_API_KEY}"

[ai.providers.deepseek]
api_key = "${DEEPSEEK_API_KEY}"

[ai.providers.qwen]
api_key = "${QWEN_API_KEY}"

[ai]
default_model = "gpt-4o-mini"

[debug]
show_nodes = false
show_context = false
show_conditions = false
show_variables = false

[limits]
max_loop_iterations = 100
max_execution_depth = 10
http_timeout_secs = 120
python_workers = 1

[paths]
base = "."

[env]
DATABASE_URL = "postgresql://localhost/mydb"
CUSTOM_VAR = "value"

[channels.telegram.main]
token = "${TELEGRAM_BOT_TOKEN}"
agent = "default"
# mode = "polling"   # auto-detected from server.endpoint_url; override here if needed

[channels.feishu.events]
app_id = "cli_xxx"
app_secret = "secret"
agent = "default"
base_url = "https://open.feishu.cn"

[channels.feishu.alerts]              # egress-only: push to a Feishu group
incoming_webhook_url = "https://open.feishu.cn/...hook/abc"

[channels.wechat]                     # accounts auto-discovered from .juglans/wechat/
agent = "default"

[channels.discord.community]
token = "${DISCORD_BOT_TOKEN}"
agent = "default"

[registry]
url = "https://jgr.juglans.ai"

[account]

User account information. Identity slot — future juglans-issued agent IDs will live here.

FieldTypeRequiredDefaultDescription
idstringYesUser ID
namestringYesDisplay name
rolestringNoRole (e.g., admin, user)

[workspace]

Workspace for multi-user collaboration and batch resource management.

FieldTypeRequiredDefaultDescription
idstringYesWorkspace ID
namestringYesWorkspace name
membersstring[]No[]Member user IDs
agentsstring[]No[](deprecated — prefer inline agent map nodes in .jg files)
workflowsstring[]No[]Workflow file glob patterns
promptsstring[]No[]Prompt file glob patterns
toolsstring[]No[]Tool file glob patterns
excludestring[]No[]Exclude patterns

Resource paths support glob: * matches filenames, ** matches directories recursively.


[ai]

LLM provider configuration. juglans calls providers directly using their respective APIs — no remote backend involved. Configure at least one provider here, or set the corresponding *_API_KEY environment variable.

FieldTypeRequiredDefaultDescription
default_modelstringNoDefault model used when an agent node does not specify one
[ai]
default_model = "gpt-4o-mini"

[ai.providers.<name>]
api_key = "..."
base_url = "..."  # optional, for OpenAI-compatible endpoints

Supported provider names: openai, anthropic, deepseek, gemini, qwen, byteplus, xai.

You can also configure providers entirely via env vars without a juglans.toml:

Env VarProvider
OPENAI_API_KEYopenai
ANTHROPIC_API_KEYanthropic
DEEPSEEK_API_KEYdeepseek
GEMINI_API_KEYgemini
QWEN_API_KEYqwen
ARK_API_KEYbyteplus (ByteDance Ark)
ARK_API_BASEbyteplus base URL override
XAI_API_KEYxai

[server]

HTTP server configuration (used by juglans serve).

FieldTypeRequiredDefaultDescription
hoststringNo127.0.0.1Bind address
portu16No3000Port number
endpoint_urlstringNoPublic endpoint URL for this server

[debug]

Debug output control.

FieldTypeDefaultDescription
show_nodesboolfalseShow node execution info
show_contextboolfalseShow context variables
show_conditionsboolfalseShow condition evaluation details
show_variablesboolfalseShow variable resolution process

[limits]

Runtime limits to prevent runaway execution.

FieldTypeDefaultDescription
max_loop_iterationsusize100Maximum loop iterations
max_execution_depthusize10Maximum nested execution depth
http_timeout_secsu64120HTTP request timeout (seconds)
python_workersusize1Python worker pool size

[paths]

Path alias configuration.

FieldTypeDefaultDescription
basestring(disabled)Base directory for @ path alias, relative to project root

When set to ".", @/prompts/foo.jgx resolves to <project_root>/prompts/foo.jgx.


env_file

Specify .env files to load (pydantic-settings style). Files are loaded in order; later files override earlier ones. Default: [".env"].

env_file = [".env", ".env.local", ".env.deploy"]

After loading, all variables are available via the env() expression function:

[step]: api_key = env("API_KEY")

${VAR} Interpolation

All string values in juglans.toml support ${VAR_NAME} syntax. Variables are resolved from the process environment (including .env files loaded via env_file).

env_file = [".env"]

[ai.providers.openai]
api_key = "${OPENAI_API_KEY}"

If a variable is not set, it is replaced with an empty string.


[env]

Custom environment variables available during workflow execution. Supports ${VAR} interpolation.

[env]
DATABASE_URL = "postgresql://localhost/mydb"
CLIENT_ID = "${CLIENT_ID}"
CLIENT_SECRET = "${CLIENT_SECRET}"

Accessible in workflows via config.env.DATABASE_URL or directly via env("DATABASE_URL").


MCP Servers

MCP (Model Context Protocol) servers are not configured in juglans.toml — they are declared inline on a chat() call via the mcp= parameter, so each agent can opt into the exact set of tools it needs:

[reply]: chat(
  agent = my_agent,
  message = input.text,
  mcp = {
    "filesystem": "http://localhost:3001/mcp/filesystem",
    "github": {
      "url": "http://localhost:3001/mcp/github",
      "token": env("GITHUB_TOKEN")
    }
  }
)

See How to Use MCP Tools for the full flow, including the std/mcps.jg helper library.


[channels]

Per-instance configuration for chat-platform integrations. Format is [channels.<kind>.<instance_id>] — each subsection declares one named channel; multiple instances per platform are supported.

juglans serve reads this section, instantiates each entry as a Channel, and runs them all in one process: active ingress channels (long-poll, websocket) get tokio tasks; passive ingress channels (webhooks) mount HTTP routes on the shared axum router. Replies to the user route back through whichever channel triggered the workflow run, automatically — workflows just call reply() and the runtime routes through ChannelOrigin.

Legacy [bot.<kind>] configuration was removed. Migrate by moving each section to [channels.<kind>.<instance_id>].

[channels.telegram.<id>]

[channels.telegram.main]
token = "${TELEGRAM_BOT_TOKEN}"
agent = "default"
# mode = "polling"   # or "webhook" — auto-detected from server.endpoint_url
FieldTypeDefaultDescription
tokenstringTelegram bot token. Required.
agentstring"default"Agent slug / workflow name
modestringauto"polling", "webhook", or unset (auto: webhook iff server.endpoint_url is set)

When mode = "webhook", the channel mounts POST /webhook/telegram/<instance_id> on the same axum server juglans serve is running. Streaming replies use sendMessage + debounced editMessageText (~1Hz); native sendMessageDraft (Bot API 9.5) is a future optimization.

[channels.feishu.<id>]

A Feishu channel comes in two flavors — pick one per instance:

Event-subscription mode (bidirectional). Requires app_id + app_secret. Mounts POST /webhook/feishu/<instance_id> for the platform to push events to; replies via Feishu OpenAPI.

[channels.feishu.events]
app_id = "cli_xxx"
app_secret = "secret"
agent = "default"

Incoming-webhook mode (egress-only). Requires incoming_webhook_url. Pushes plain-text messages to the Feishu group bound to that URL. No ingress.

[channels.feishu.alerts]
incoming_webhook_url = "https://open.feishu.cn/open-apis/bot/v2/hook/abc..."
FieldTypeDefaultDescription
app_idstringFeishu app ID (event mode)
app_secretstringFeishu app secret (event mode)
incoming_webhook_urlstringIncoming webhook URL (egress-only mode)
agentstring"default"Agent slug to use (event mode)
base_urlstringhttps://open.feishu.cnAPI base (https://open.larksuite.com for Lark)
approversstring[][]Approver open_ids — used by approval workflows

[channels.wechat]

WeChat is special: accounts are auto-discovered from .juglans/wechat/<account_id>.json files (created by QR-login flow). There’s no per-instance subsection — config sets defaults that apply to every discovered account.

[channels.wechat]
agent = "default"
FieldTypeDefaultDescription
agentstring"default"Agent slug used for every discovered account

If no accounts are persisted yet, juglans serve runs the QR-login flow to bring up the first one (writes the QR payload to .juglans/wechat/qr.pending.txt for external observers).

[channels.discord.<id>]

Discord Gateway (WebSocket). Use ${VAR} interpolation to pull the token from env (see env_file).

[channels.discord.community]
token = "${DISCORD_BOT_TOKEN}"
agent = "main"
intents = ["guilds", "guild_messages", "message_content", "direct_messages"]
FieldTypeDefaultDescription
tokenstringDiscord bot token. Required.
agentstring"default"Agent slug / workflow name
intentsstring[][guilds, guild_messages, message_content, direct_messages]Gateway intent names (see Discord docs)
intents_bitmasku64Raw intents bitmask — wins over intents when set
dm_policystringReserved — parsed but not enforced; warns at startup if set.
group_policystringReserved.
guildsstring[][]Reserved — guild allowlist.

Privileged intents. message_content is a privileged intent — enable “MESSAGE CONTENT INTENT” in the Discord Developer Portal, otherwise the gateway closes with code 4014.

Deployment. Persistent WebSocket — serverless platforms that suspend idle containers don’t fit. Run on a long-lived host.

Session resume. Adapter persists session state at .juglans/discord/gateway.json so restarts resume without a fresh Identify.


[history]

Conversation history storage for chat(). When enabled, each chat() node with a resolved chat_id automatically loads the tail of the thread before the LLM call and appends the user/assistant turn afterwards. chat_id is resolved in this priority order: explicit chat_id= parameter → reply.chat_id (chained within a run) → input.chat_id (adapter-injected, e.g. telegram:12345:my_agent).

Persistence honors the state parameter — state="silent" or state="display_only" skips storage.

[history]
enabled = true            # master switch
backend = "jsonl"         # jsonl | sqlite | memory | none
dir = ".juglans/history"  # jsonl: one file per chat_id
# path = ".juglans/history.db"  # sqlite path
max_messages = 20         # cap auto-loaded messages per call
max_tokens = 8000         # soft token budget (rough 4-char ≈ 1-token estimate)
retention_days = 30       # eligible-for-GC age (0 disables)
FieldTypeDefaultDescription
enabledbooltrueWhen false, chat_id still works as a field but nothing is stored or loaded
backendstring"jsonl"jsonl, sqlite, memory, none
dirstring.juglans/historyDirectory for the JSONL backend (one .jsonl per chat_id)
pathstring.juglans/history.dbDB file path for the SQLite backend
max_messagesuint20Hard upper bound on messages auto-loaded per chat() call
max_tokensuint8000Soft token budget (estimate)
retention_daysuint30Days after which old messages are eligible for GC (0 = never)

Environment overrides: JUGLANS_HISTORY_BACKEND, JUGLANS_HISTORY_DIR, JUGLANS_HISTORY_PATH, JUGLANS_HISTORY_MAX_MESSAGES, JUGLANS_HISTORY_MAX_TOKENS, JUGLANS_HISTORY_ENABLED.

Programmatic access from workflows is exposed via the history.* builtins.


[registry]

Package registry configuration used by juglans publish / juglans add.

FieldTypeDefaultDescription
urlstringhttps://jgr.juglans.aiRegistry URL to publish to / fetch from

To publish packages, set JUGLANS_REGISTRY_API_KEY (or REGISTRY_API_KEY) in your environment.


Environment Variables

VariableDescription
RUST_LOGLog level / module filter (e.g. debug, juglans::runtime::python=debug)
OPENAI_API_KEY / ANTHROPIC_API_KEY / DEEPSEEK_API_KEY / GEMINI_API_KEY / QWEN_API_KEY / ARK_API_KEY / XAI_API_KEYLLM provider API keys (alternative to [ai.providers]) — the juglans proxy provider is config-only, no env var
OPENAI_API_BASE / ANTHROPIC_BASE_URL / ARK_API_BASEProvider base URL overrides (local proxies, Ollama, Azure OpenAI, etc.)
DEFAULT_LLM_PROVIDERFallback provider when chat(model="default") is used and no ai.default_model is set (openai | anthropic | byteplus | qwen | …)
JUGLANS_HISTORY_BACKEND / JUGLANS_HISTORY_DIR / JUGLANS_HISTORY_PATH / JUGLANS_HISTORY_MAX_MESSAGES / JUGLANS_HISTORY_MAX_TOKENS / JUGLANS_HISTORY_ENABLEDOverride [history] section fields
JUGLANS_REGISTRY_API_KEY / REGISTRY_API_KEYPackage registry credential for juglans publish
SERVER_HOST / SERVER_PORTOverride [server] host/port
TELEGRAM_BOT_TOKEN / FEISHU_APP_ID / FEISHU_APP_SECRETChannel overrides — when set, juglans synthesizes a [channels.telegram.default] / [channels.feishu.default] instance even if juglans.toml doesn’t declare one (handy for serverless / container deployments)

Project vs User Configuration

Project config (./juglans.toml) – committed to version control, no secrets:

[server]
port = 8080

[ai.providers.openai]
api_key = "${OPENAI_API_KEY}"

User config (~/.config/juglans/juglans.toml) – personal settings:

[account]
id = "my_user_id"
name = "My Name"
role = "developer"

Or just set everything in .env:

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...