Configuration

Where config lives

By default, Hubcode uses ~/.hubcode as its home directory. The configuration file is:

You can change the home directory by setting HUBCODE_HOME or passing --home to hubcode daemon start.

Precedence

Hubcode merges configuration in this order:

1. Defaults
2. config.json
3. Environment variables
4. CLI flags

Lists append across sources (for example, allowedHosts andcors.allowedOrigins).

Example

Minimal example that configures listening address, host allowlist, provider keys, and MCP:

{
  "$schema": "https://hubcode.ai/schemas/hubcode.config.v1.json",
  "version": 1,
  "providers": {
    "openai": { "apiKey": "..." }
  },
  "daemon": {
    "listen": "127.0.0.1:6767",
    "allowedHosts": ["localhost", ".localhost"],
    "mcp": { "enabled": true }
  }
}

Agent provider runtime settings

Use agents.providers to customize how Hubcode launches agent provider CLIs. This works for claude, codex, and opencode.

command.mode can be default, append, or replace. Use env to inject provider-specific environment variables.

Enable Claude Code Chrome MCP

{
  "agents": {
    "providers": {
      "claude": {
        "command": {
          "mode": "append",
          "args": ["--chrome"]
        }
      }
    }
  }
}

Point Claude to Anthropic-compatible endpoints (z.ai example)

{
  "agents": {
    "providers": {
      "claude": {
        "env": {
          "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
          "ANTHROPIC_AUTH_TOKEN": "auth token",
          "ANTHROPIC_API_KEY": ""
        }
      }
    }
  }
}

Run Claude through Docker

Create a wrapper script that runs Claude in Docker, then tell Hubcode to replace the Claude launch command with that script.

{
  "agents": {
    "providers": {
      "claude": {
        "command": {
          "mode": "replace",
          "argv": ["/Users/you/bin/claude-docker"]
        }
      }
    }
  }
}

#!/usr/bin/env bash
set -euo pipefail
docker run --rm -i \
  -v "$PWD":"$PWD" \
  -w "$PWD" \
  -v "$HOME/.claude":"$HOME/.claude" \
  ghcr.io/anthropics/claude-code:latest \
  claude "$@"

Voice

Voice is configured through features.dictation and features.voiceMode, with provider credentials under providers.

For voice philosophy, architecture, and complete local/OpenAI setup examples, see Voice docs.

Logging

Daemon logging uses separate console and file sinks by default:

• Console: info and above
• File ($HUBCODE_HOME/daemon.log): trace and above
• File rotation: 10m max file size, 2 retained files total (active + 1 rotated)

{
  "log": {
    "console": {
      "level": "info",
      "format": "pretty"
    },
    "file": {
      "level": "trace",
      "path": "daemon.log",
      "rotate": {
        "maxSize": "10m",
        "maxFiles": 2
      }
    }
  }
}

Legacy fields log.level and log.format are still supported and map to the new destination settings.

Common env vars

• HUBCODE_HOME — set Hubcode home directory
• HUBCODE_LISTEN — override daemon.listen
• HUBCODE_ALLOWED_HOSTS — override/extend daemon.allowedHosts
• HUBCODE_LOG_CONSOLE_LEVEL — override log.console.level
• HUBCODE_LOG_FILE_LEVEL — override log.file.level
• HUBCODE_LOG_FILE_PATH — override log.file.path
• HUBCODE_LOG_FILE_ROTATE_SIZE — override log.file.rotate.maxSize
• HUBCODE_LOG_FILE_ROTATE_COUNT — override log.file.rotate.maxFiles
• HUBCODE_LOG, HUBCODE_LOG_FORMAT — legacy log overrides (still supported)
• OPENAI_API_KEY — override OpenAI provider key
• HUBCODE_VOICE_LLM_PROVIDER — override voice LLM provider (claude, codex, opencode)
• HUBCODE_DICTATION_STT_PROVIDER, HUBCODE_VOICE_STT_PROVIDER, HUBCODE_VOICE_TTS_PROVIDER — override voice provider selection (local or openai)
• HUBCODE_LOCAL_MODELS_DIR — control local model directory
• HUBCODE_DICTATION_LOCAL_STT_MODEL — override local dictation STT model
• HUBCODE_VOICE_LOCAL_STT_MODEL, HUBCODE_VOICE_LOCAL_TTS_MODEL — override local voice STT/TTS models
• HUBCODE_VOICE_LOCAL_TTS_SPEAKER_ID, HUBCODE_VOICE_LOCAL_TTS_SPEED — optional local voice TTS tuning

Schema

For editor autocomplete/validation, set $schema to: