Skip to main content

Configuration

Timon reads timon.config.json from its data directory, normally ~/.timon. Set TIMON_HOME to select a different instance directory. This is a process environment variable, not a JSON configuration key.

For a source installation, create the directory and write the following JSON, replacing the example paths with existing absolute paths on your machine:

{
  "version": 1,
  "profile": "linux-desktop",
  "edition": "expert",
  "workspacesRoot": "/path/to/projects",
  "daemon": {
    "installDir": "/path/to/timon/orchestrator",
    "listen": {"host": "127.0.0.1", "port": 3000},
    "supervisor": "systemd-user"
  },
  "host": {"docker": "disabled", "traefik": false},
  "app": {
    "enabled": true,
    "listen": {"host": "127.0.0.1", "port": 3100},
    "publicUrl": "http://127.0.0.1:3100"
  }
}

Use profile: "macos" and supervisor: "launchd" on macOS, or "windows" for both on Windows. Use linux-server for a Linux server. For Docker features, change host.docker as needed; do not enable both app serving modes.

Resolution order​

The loader merges the edition preset with your file, then applies schema defaults and supported environment overrides. Your file wins over the preset. Arrays are replaced, not concatenated.

Registry settings resolve in this order: environment → settings in the file → saved UI setting → default. The UI shows the source, so a value controlled by the environment or file cannot be changed by saving another UI value.

modules controls bundled modules; plugins controls third-party plugins by manifest ID. Values can be true, false, "auto" or an options object with enabled. Plugin toggles recompose the loader without a daemon restart. Changes to daemon addresses, host configuration or process environment require an operator-managed restart.

Paths and credentials

Set daemon.installDir explicitly for source installations. Keep API credentials out of this file; use plugin secret settings or the secrets vault. Never disable authentication on a non-loopback listener.

See the generated configuration reference for every field, default and direct environment override.