Configuration Guide

Codecast reads its configuration from a YAML file. The file is searched in this order:

1. A path provided as a CLI argument: codecast /path/to/config.yaml
2. ~/.codecast/config.yaml (recommended location)
3. ./config.yaml in the current working directory (development fallback)

To get started, copy the example config:

mkdir -p ~/.codecast
cp /path/to/codecast/config.example.yaml ~/.codecast/config.yaml

Environment Variable Expansion

All string values support ${ENV_VAR} syntax. If the variable is not set, the expression is left as-is.

bot:
  discord:
    token: ${DISCORD_TOKEN}

Path values also support ~ expansion (e.g. ~/.ssh/id_rsa expands to /home/user/.ssh/id_rsa).

Passwords can be read from a file using the file: prefix:

password: file:~/.secrets/my-password

The file should contain only the password text (whitespace is trimmed).

peers

Defines the remote machines (peers) that Codecast can connect to. Each key is a machine ID used in commands like /start gpu-1 /path.

peers:
  gpu-1:
    host: gpu1.example.com
    user: your-ssh-user
    ssh_key: ~/.ssh/id_rsa
    port: 22
    proxy_jump: gateway
    password: file:~/.secrets/gpu1-password
    daemon_port: 9100
    default_paths:
      - /home/your-user/project-a
      - /home/your-user/project-b

Peer transport types

For ssh transport (the default), use these fields:

For http transport, use these fields:

ProxyJump example

For machines behind a bastion host:

peers:
  gateway:
    host: bastion.example.com
    user: admin

  gpu-2:
    host: gpu2.lab.internal
    user: researcher
    proxy_jump: gateway
    daemon_port: 9100
    default_paths:
      - /data/experiments

The gateway peer is used only as a jump host and does not need default_paths.

bot

Configures the bot connections. At least one bot must be configured for Codecast to start.

bot.discord

bot:
  discord:
    token: ${DISCORD_TOKEN}
    allowed_channels:
      - 123456789012345678
    admin_users:
      - 987654321098765432
    command_prefix: "/"

bot.telegram

bot:
  telegram:
    token: ${TELEGRAM_TOKEN}
    allowed_users:
      - 123456789
    allowed_chats:
      - -1001234567890
    admin_users:
      - 123456789

bot.lark

bot:
  lark:
    app_id: ${LARK_APP_ID}
    app_secret: ${LARK_APP_SECRET}
    allowed_chats:
      - "oc_abcdef1234567890"
    admin_users:
      - "ou_abcdef1234567890"
    use_cards: true

bot.webui

Enables the browser-based Web UI alongside the chat bots.

bot:
  webui:
    enabled: true
    port: 8080
    host: 127.0.0.1

default_mode

default_mode: auto

The default permission mode for new sessions. Can be changed per-session with /mode.

tool_batch_size

tool_batch_size: 15

The number of consecutive tool_use events (file reads, shell commands, etc.) that are compressed into a single summary message. Reduces chat noise during large operations. Default is 15.

skills

skills:
  shared_dir: ./skills
  sync_on_start: true

daemon

Controls how the Codecast daemon (a single static Rust binary) is deployed to and managed on remote machines.

daemon:
  install_dir: ~/.codecast/daemon
  auto_deploy: true
  log_file: ~/.codecast/daemon.log

No Node.js or npm is required on remote machines. The daemon is a self-contained binary with no external runtime dependencies.

file_pool

Controls how files uploaded to bot chats are staged for use in AI sessions.

file_pool:
  max_size: 1073741824
  pool_dir: ~/.codecast/file-pool
  remote_dir: /tmp/codecast/files
  allowed_types:
    - text/plain
    - text/markdown
    - application/pdf
    - image/*
    - video/*
    - audio/*

file_forward

Controls automatic forwarding of files from remote machines to chat when the AI's response contains matching file paths.

file_forward:
  enabled: true
  download_dir: ~/.codecast/downloads
  default_max_size: 5242880
  default_auto: false
  rules:
    - pattern: "*.png"
      max_size: 10485760
      auto: true
    - pattern: "*.log"
      max_size: 1048576
      auto: false

Each rule in rules has:

When auto is false for a matched file, the bot sends a prompt asking whether to forward it.

Complete Example

peers:
  gateway:
    host: bastion.university.edu
    user: admin

  gpu-1:
    host: gpu-node-1.internal
    user: researcher
    proxy_jump: gateway
    daemon_port: 9100
    default_paths:
      - /data/ml-project
      - /data/nlp-experiments

  cloud-dev:
    host: 203.0.113.42
    user: ubuntu
    ssh_key: ~/.ssh/cloud-key.pem
    daemon_port: 9100
    default_paths:
      - /home/ubuntu/webapp

bot:
  discord:
    token: ${DISCORD_TOKEN}
    allowed_channels:
      - 1234567890123456789
    admin_users:
      - 9876543210987654321

  telegram:
    token: ${TELEGRAM_TOKEN}
    allowed_users:
      - 987654321
    admin_users:
      - 987654321

  lark:
    app_id: ${LARK_APP_ID}
    app_secret: ${LARK_APP_SECRET}
    allowed_chats:
      - "oc_abcdef1234567890"

  webui:
    enabled: false
    port: 8080
    host: 127.0.0.1

default_mode: auto

tool_batch_size: 15

skills:
  shared_dir: ./skills
  sync_on_start: true

daemon:
  install_dir: ~/.codecast/daemon
  auto_deploy: true
  log_file: ~/.codecast/daemon.log

file_pool:
  max_size: 1073741824
  pool_dir: ~/.codecast/file-pool
  remote_dir: /tmp/codecast/files

file_forward:
  enabled: false
  download_dir: ~/.codecast/downloads
  default_max_size: 5242880
  default_auto: false
  rules: []