Configuration

Configuration Reference

ZoarkBot is controlled by a single JSON config file. This page explains where it lives, the key options, and how to apply changes.

Where the config file lives

ZoarkBot reads its configuration from:

Config file path

~/.zoarkbot/zoarkbot.json

This file supports JSON5 — meaning you can use comments (//) and trailing commas. Regular JSON also works.

If the file doesn't exist, ZoarkBot uses built-in defaults. You usually only need a config to restrict who can use the bot, connect channels, or adjust agent behavior.

Minimal working config (Telegram)

This is the smallest valid config that connects Telegram and restricts the bot to your account only:

~/.zoarkbot/zoarkbot.json

{
  // Your workspace folder — agents read/write files here
  agents: { defaults: { workspace: "~/zoarkbot" } },

  // Gateway settings
  gateway: {
    port: 18789,
    auth: { token: "your-gateway-token-here" }
  },

  // Telegram channel — only allow messages from your account
  channels: {
    telegram: {
      allowFrom: ["your_telegram_username"],
      token: "your_telegram_bot_token"
    }
  }
}

After editing, restart ZoarkBot for changes to take effect:

zoarkbot restart

Key configuration options

gateway.portdefault: 18789

The port ZoarkBot listens on. Only change if 18789 conflicts with something else on your machine.

gateway.auth.tokendefault: auto-generated

The auth token clients (like Mission Control) use to connect. Find yours with zoarkbot token.

channels.telegram.tokendefault: none

Your Telegram bot token from @BotFather. Required for Telegram to work.

channels.telegram.allowFromdefault: []

List of Telegram usernames or IDs allowed to trigger the bot. Empty = no one can use it.

channels.telegram.groupsdefault: {}

Group chat settings. Use "*": { requireMention: true } to require @botname in groups.

agents.defaults.workspacedefault: ~/zoarkbot

The folder on disk where agents store files, drafts, and outputs.

logging.leveldefault: "info"

Log verbosity. Use "debug" to see detailed agent activity.

Using environment variables

Instead of hardcoding secrets in the config file, you can use environment variables. ZoarkBot supports substitution with ${VAR_NAME} syntax:

{
  gateway: {
    auth: { token: "${ZOARKBOT_GATEWAY_TOKEN}" }
  },
  channels: {
    telegram: { token: "${TELEGRAM_BOT_TOKEN}" }
  }
}

Store secrets in the environment file instead of the config:

Environment file (safe — not committed to git)

~/.zoarkbot/.env

~/.zoarkbot/.env contents

ANTHROPIC_API_KEY=sk-ant-...
ZOARKBOT_GATEWAY_TOKEN=your-token-here
TELEGRAM_BOT_TOKEN=1234567890:ABC...

Applying changes

After editing ~/.zoarkbot/zoarkbot.json, restart ZoarkBot:

zoarkbot restart

Important

ZoarkBot validates the config on startup. If there are syntax errors or unknown keys, it will refuse to start and show an error.

Check the error with: zoarkbot status

ZoarkBot also hot-reloads safe config changes without a full restart. Critical changes (like port or auth) always require a restart.

Config validation

ZoarkBot only accepts configs that match its schema exactly. Unknown keys or wrong types cause the gateway to refuse to start.

If ZoarkBot won't start after a config change:

# Check what's wrong
zoarkbot status

# View detailed logs
zoarkbot logs

Config backup tip

Before making big changes, back up your working config:

cp ~/.zoarkbot/zoarkbot.json ~/.zoarkbot/zoarkbot.json.bak