HAL is configured via a config file in the config directory (default: the current working directory, or --config when set). The recommended way to create or complete your config is the Setup wizard — run npx @marcopeg/hal wiz, or run npx @marcopeg/hal and accept the prompt when HAL detects the config is missing/incomplete. Three formats are supported — only one per file is allowed.

Base and local configs can use different formats (e.g. hal.config.yaml + hal.config.local.json). If multiple formats exist for the same file (e.g. both .json and .jsonc), the loader exits with an error.

This section is the index for all configuration options; detailed subsections are split into focused docs.

Create a config file in your config directory (default: the current working directory, or --config when set). Secrets like bot tokens should be kept out of this file — use ${VAR_NAME} placeholders and store the values in .env or the shell environment instead. Keep .env out of git (see Env files).

YAML is the recommended format for examples and for configs with comments. A full key reference (all options, with links to doc pages) is reference.yaml. A short copy-paste example is examples/hal.config.yaml. JSON and JSONC are also supported — see Configuration alternatives below.

Example (YAML):

globals:
  engine:
    name: claude
  logging:
    level: info
    flow: true
    persist: false
  rateLimit:
    max: 10
    windowMs: 60000
  access:
    allowedUserIds: [123456789]

projects:
  backend:
    cwd: ./backend
    telegram:
      botToken: "${BACKEND_BOT_TOKEN}"
    logging:
      persist: true
  frontend:
    cwd: ./frontend
    engine:
      name: copilot
      model: gpt-5-mini
    telegram:
      botToken: "${FRONTEND_BOT_TOKEN}"

An optional local config file placed next to the main config is deep-merged on top of the base config at boot time. It is gitignored and is the recommended place for machine-specific values or secrets that you don't want committed.

Every field is optional. projects is a map with the same keys as the base config; each local entry is deep-merged into the base project with the same key. Keys that do not exist in the base config are invalid and cause a load error — you cannot introduce new projects from local config.

projects:
  backend:
    telegram:
      botToken: "7123456789:AAHActual-token-here"
    logging:
      persist: true

hal.config.json and hal.config.jsonc are supported alongside hal.config.yaml. Runtime behavior is identical; the loader accepts any of the three formats (one per file).

For a full config structure use the YAML reference or example; you can convert to JSON/JSONC (e.g. with a tool or AI) if needed.

JSONC supports:

• Single-line comments: //
• Block comments: /* ... */
• Trailing commas in objects and arrays

JSONC does not support: unquoted keys, single-quoted strings, or other non-standard JSON extensions.

Minimal JSON example (globals + one project):

{
  "globals": {
    "engine": { "name": "claude" },
    "access": { "allowedUserIds": [123456789] }
  },
  "projects": {
    "mybot": {
      "telegram": { "botToken": "${BOT_TOKEN}" }
    }
  }
}

Minimal JSONC example (same structure with // comments and trailing commas):

{
  "globals": {
    "engine": { "name": "claude" },
    "access": { "allowedUserIds": [123456789] },
  },
  "projects": {
    "mybot": {
      "telegram": { "botToken": "${BOT_TOKEN}" },
    },
  },
}

Any string value in the config files can reference an environment variable with ${VAR_NAME} syntax. Values inside context blocks support the same ${expr} syntax but with a richer resolver (full context map + env) and two additional patterns (#{cmd} boot-time shell, @{cmd} message-time shell) — see Context. This works identically for all config formats (JSON, JSONC, YAML).

Variables are resolved at boot from env files next to your config (.env and .env.local). The docs use .env as the standard file; .env.local is an optional override. For full details on loading modes, precedence, the env config key, wizard file selection, and .gitignore guidance, see Env files.

If a referenced variable cannot be resolved from any source the bot exits at boot with a clear error message naming the variable and the config field that references it.

Default settings applied to all projects. Any setting defined in a project overrides its global counterpart.

Per-engine options (Codex, Antigravity) are documented in Engines.

engine.session is a single value: false (stateless), true (adapter default), "shared", or "user". Full reference, per-engine behaviour, and boot-error rules: Session configuration.

Important: true means the engine default, not the same behavior for every engine. In particular, Codex and Copilot now default to per-user mode, while Cursor still defaults to shared mode.

Per-engine model lists for the /model command and the set of engines available for /engine. Top-level sibling of globals and projects. Entries may include default: true (at most one per engine) to set the model when engine.model is omitted. Explicit engine.model always overrides the provider default. See Engines — Model list for full details, field reference, and examples.

Per-project providers can override the top-level list for a specific project (only for engines already listed in the base config; local config cannot add new engine keys).

Configuration shapes:

When a built-in command is disabled, HAL does not intercept it. The slash command falls through to project custom commands, global custom commands, skills, and finally the agent.

Every project must have a valid access policy or the bot refuses to start. A valid policy is one of:

• access.allowedUserIds contains at least one Telegram user ID, or
• access.dangerouslyAllowUnrestrictedAccess is explicitly true.

When allowedUserIds is non-empty it takes precedence — only listed users are allowed, even if dangerouslyAllowUnrestrictedAccess is also true.

Format: Each allowedUserIds entry may be a number (e.g. 123456789) or a string (e.g. "123456789" or "${TELEGRAM_USER_ID}" for env substitution). After environment variable substitution, every value is validated as a valid Telegram user ID (positive integer in the official range) and normalized to a number. Invalid values (e.g. spaces, decimals, non-numeric text) cause config load to fail with an error that includes the config path and the invalid value; the process exits at boot or on hot reload.

Project-level replacement: if a project defines access (even as "access": {}), it fully replaces the global access — the two are not merged. If a project omits access entirely, the global value is inherited. An empty "access": {} at project level is a validation error because it has neither user IDs nor the dangerous flag.

This validation runs at both initial boot and after config hot-reload. A reload that introduces an invalid access config is rejected and the previous config stays active.

projects is an object (map) keyed by project key. Each key identifies one project and one Telegram bot connected to one directory. This key is used in logs, data paths, and errors (legacy internal name: slug).

Key format: Only letters, numbers, dashes, and underscores ([a-zA-Z0-9_-]+). This keeps the default cwd safe as a path segment when omitted.

Defaults from key: If you omit name, it defaults to the map key. If you omit cwd, it defaults to the map key (so a key backend implies cwd: "backend" unless overridden). You can still set name and cwd explicitly to override these defaults.

The project key (the key in the projects map) is the single source of identity and is used in log/data paths. It is not derived from name or cwd. You may still see this key referred to as slug in code and internal fields — treat slug as legacy naming.

Log file paths and options are documented in Logging.

With a config at ~/workspace/hal.config.yaml (or .json / .jsonc):

~/workspace/
├── hal.config.yaml          (or .json / .jsonc)
├── hal.config.local.yaml    (or .json / .jsonc — gitignored, local overrides / secrets)
├── .hal/
│   ├── hooks/
│   │   └── context.mjs            (global context hook, optional)
│   ├── commands/
│   │   └── mycommand.mjs          (global command, available to all projects)
│   └── logs/
│       ├── backend/
│       │   └── 2026-02-26.txt     (when persist: true)
│       └── frontend/
│           └── 2026-02-26.txt
├── .env                     (gitignored — local secrets, do not commit)
├── .env.local               (optional gitignored override)
├── backend/
│   ├── CLAUDE.md
│   ├── .claude/
│   │   ├── settings.json
│   │   └── skills/
│   │       └── deploy/
│   │           └── SKILL.md         (skill exposed as /deploy command)
│   └── .hal/
│       ├── hooks/
│       │   └── context.mjs        (project context hook, optional)
│       ├── commands/
│       │   └── deploy.mjs         (project-specific command, optional)
│       └── users/
│           └── {userId}/
│               ├── uploads/       # Files FROM user (to engine)
│               ├── downloads/     # Files TO user (from engine)
│               └── session.json   # Session data
└── frontend/
    ├── CLAUDE.md
    └── .hal/
        └── users/