OrfynOrfyn
View as markdown

Configuration

Orfyn loads configuration from a single JSON file in your Orfyn home directory, with optional environment variable and CLI overrides.

Where config lives

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

~/.orfyn/config.json

You can change the home directory by setting ORFYN_HOME or passing --home to orfyn daemon start.

Precedence

Orfyn merges configuration in this order:

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

Lists append across sources (for example, hostnames and cors.allowedOrigins).

Example

Minimal example that configures listening address, hostnames, and MCP:

{
  "$schema": "https://orfyn.in/schemas/orfyn.config.v1.json",
  "version": 1,
  "daemon": {
    "listen": "127.0.0.1:6767",
    "hostnames": ["localhost", ".localhost"],
    "mcp": { "enabled": true }
  }
}

daemon.hostnames is the primary field. The old daemon.allowedHosts name still works as a deprecated alias for backward compatibility.

Agent providers

Agent providers, both the first-class ones Orfyn ships with and custom entries you add under agents.providers, are documented on their own page.

See Providers for the mental model and Supported providers for the full list of agents Orfyn can launch. For pointing Claude at Anthropic-compatible endpoints (Z.AI, Alibaba/Qwen), multiple profiles, custom binaries, ACP agents, and the additionalModels merge behavior, see Custom providers.

Worktrees

New worktrees are created under $ORFYN_HOME/worktrees by default. To place new worktrees somewhere else, set worktrees.root:

{
  "worktrees": {
    "root": "/mnt/fast/orfyn-worktrees"
  }
}

Relative paths are resolved against ORFYN_HOME. Existing worktrees remain where they are; changing this setting only changes where Orfyn creates and discovers Orfyn-managed worktrees going forward.

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.

Bundled web UI

The daemon can serve the browser web client from the same HTTP server. This is enabled in the official Docker image and disabled by default for normal CLI and desktop-managed daemons.

Enable it from the CLI:

orfyn daemon start --web-ui

Or set the environment variable:

ORFYN_WEB_UI_ENABLED=true orfyn daemon start

Or persist it in config.json:

{
  "features": {
    "webUi": {
      "enabled": true
    }
  }
}

When enabled, open the daemon HTTP origin, for example http://localhost:6767/, to load the web app. Static UI files load without daemon auth; API and WebSocket requests still require the configured password.

Logging

Daemon logging uses separate console and file sinks by default:

  • Console: info and above
  • File ($ORFYN_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.

Password authentication

You can require a password to connect to the daemon. When set, all HTTP and WebSocket clients must authenticate. Only the /api/health liveness endpoint is exempt, so that process supervisors and load balancers can probe without credentials.

The easiest way to set a password is with the CLI:

orfyn daemon set-password

This prompts for a password, writes the bcrypt hash to config.json, and tells you to restart the daemon.

Alternatively, set the ORFYN_PASSWORD environment variable (plaintext, hashed automatically at startup):

ORFYN_PASSWORD=my-secret orfyn daemon start

Or write the hash directly in config.json:

{
  "daemon": {
    "auth": {
      "password": "$2b$12$..."
    }
  }
}

After setting a password, restart the daemon for the change to take effect.

Connecting with a password

The CLI picks up a password from, in order:

  1. The password query parameter on a tcp:// host URI:

    orfyn --host "tcp://192.168.1.10:6767?password=my-secret" ls

  2. The ORFYN_PASSWORD environment variable, used as a fallback when the host carries no embedded password (works for localhost:6767, bare host:port, or tcp:// hosts without a password= query):

    ORFYN_PASSWORD=my-secret orfyn ls
ORFYN_PASSWORD=my-secret orfyn --host 192.168.1.10:6767 ls

A password= in the URI always wins over the env var, so you can keep ORFYN_PASSWORD set globally and still target a different daemon by spelling its password into the URI.

In the mobile app, enter the password in the direct connection setup screen.

Common env vars

  • ORFYN_HOME, set Orfyn home directory
  • ORFYN_PASSWORD, on the daemon, the password to require (plaintext, hashed at startup); on the CLI, the password used to connect when the host URI doesn't include one
  • ORFYN_LISTEN, override daemon.listen
  • ORFYN_HOSTNAMES, override/extend daemon.hostnames
  • ORFYN_ALLOWED_HOSTS, deprecated alias for ORFYN_HOSTNAMES
  • ORFYN_WEB_UI_ENABLED, enable or disable the daemon-served web UI
  • ORFYN_WEB_UI_DIST_DIR, override the daemon web UI build directory
  • ORFYN_TRUSTED_PROXIES, configure trusted reverse proxy ranges for X-Forwarded-* headers
  • ORFYN_LOG_CONSOLE_LEVEL, override log.console.level
  • ORFYN_LOG_FILE_LEVEL, override log.file.level
  • ORFYN_LOG_FILE_PATH, override log.file.path
  • ORFYN_LOG_FILE_ROTATE_SIZE, override log.file.rotate.maxSize
  • ORFYN_LOG_FILE_ROTATE_COUNT, override log.file.rotate.maxFiles
  • ORFYN_LOG, ORFYN_LOG_FORMAT, legacy log overrides (still supported)
  • OPENAI_API_KEY, override OpenAI provider key
  • OPENAI_STT_API_KEY, OPENAI_STT_BASE_URL, OpenAI speech-to-text endpoint (dictation + voice mode STT)
  • OPENAI_TTS_API_KEY, OPENAI_TTS_BASE_URL, OpenAI text-to-speech endpoint (voice mode TTS)
  • ORFYN_VOICE_LLM_PROVIDER, override voice LLM provider (claude, codex, opencode)
  • ORFYN_DICTATION_STT_PROVIDER, ORFYN_VOICE_STT_PROVIDER, ORFYN_VOICE_TTS_PROVIDER, override voice provider selection (local or openai)
  • ORFYN_LOCAL_MODELS_DIR, control local model directory
  • ORFYN_DICTATION_LOCAL_STT_MODEL, override local dictation STT model
  • ORFYN_VOICE_LOCAL_STT_MODEL, ORFYN_VOICE_LOCAL_TTS_MODEL, override local voice STT/TTS models
  • ORFYN_DICTATION_LANGUAGE, ORFYN_VOICE_LANGUAGE, override dictation and voice STT language
  • ORFYN_VOICE_LOCAL_TTS_SPEAKER_ID, ORFYN_VOICE_LOCAL_TTS_SPEED, optional local voice TTS tuning

Schema

For editor autocomplete/validation, set $schema to:

https://orfyn.in/schemas/orfyn.config.v1.json