Top-level runtime keys: worktreeRoot, worktreeAcceleration, worktreeMaxCount, models.*, discovery.*, update.*, acp.*, and wizard.*.

For the full key index and the other top-level config domains, see Configuration reference.

worktreeRoot

Optional global root directory for managed worktree checkouts. Defaults to <apus-state-dir>/worktrees.

{
  worktreeRoot: "/mnt/workspaces/apus-worktrees",
}

Use an absolute Gateway-host path, ~ for the Gateway user's home directory, or ~/ followed by a folder inside it; relative paths are rejected. Apus creates checkouts at <worktreeRoot>/<repo-fingerprint>/<name>. This setting applies to all agents and all managed-worktree owners, with no per-agent override. The shared state database and allocation limits remain under the existing state directory.

Changes affect new allocations only. Registered worktrees retain their original paths for reuse, cleanup, and snapshot restore; existing checkouts are not moved automatically. Keep their original storage available while those records are still needed.

worktreeAcceleration

Optional global boolean for managed worktree filesystem acceleration. Defaults to true, which selects an available filesystem backend automatically and otherwise uses normal Git checkout.

{
  worktreeAcceleration: false,
}

Set false to use normal Git checkout and file copying for new worktrees. This option applies across agents and managed-worktree owners; existing checkouts are unchanged. Supported backends are Btrfs snapshots on Linux, APFS directory clones on macOS, and ReFS block clones on Windows. Repository setup and dependencies remain per-worktree.

worktreeMaxCount

Optional positive integer limiting live managed worktrees across all agents, repositories, and owners in the same Apus state directory. Defaults to 4096. Removed checkouts with retained recovery snapshots do not count toward this limit.

{
  worktreeMaxCount: 4096,
}

The cap is enforced: cleanup purges merged or squashed branches first, then idle worktrees by last-used age, including manual checkouts and unsaved data. Snapshot capture is best effort during cap eviction; a failed snapshot does not prevent purge. Lowering the cap can therefore remove existing checkouts. Live runs remain protected; if no other checkout can be evicted, creation fails with the cap and live owners in the error. Raise worktreeMaxCount or let those runs finish before retrying.

Background maintenance and creation use the same eviction owner. Concurrent creates cannot each claim the final slot. Disk-space admission remains a separate guard even when the configured count leaves room.

Models

Provider definitions, model allowlists, and custom provider setup live in Configuration - tools and custom providers. The models root also owns global model-catalog behavior.

{
  models: {
    // Optional. Hosted catalog updates default on.
    catalogRefresh: {
      enabled: true,
      // url: "https://catalog.example.com/apus/catalog.json",
    },
  },
}

V2 includes pricing in each model row. Unknown or unavailable pricing does not mean a model is free. Models outside the catalog, such as older model IDs or models routed through a gateway, use standalone rates in the same file: a gateway that charges the vendor's price reads that vendor's rate once, without a per-gateway copy. Explicit model costs still take precedence.

Pricing updates ship in the same hosted catalog file as model metadata. The retired models.pricing toggle is removed automatically by apus doctor --fix; use models.catalogRefresh.enabled: false when Apus must avoid all hosted catalog traffic.

Discovery

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

Wide-area (DNS-SD)

{
  discovery: {
    wideArea: { domain: "apus.internal" },
  },
}

Setting discovery.wideArea.domain enables wide-area discovery and writes a unicast DNS-SD zone under ~/.apus/dns/. For cross-network discovery, pair with a DNS server (CoreDNS recommended) + Tailscale split DNS.

Setup: apus dns setup --apply.

Update

{
  update: {
    channel: "stable", // stable | extended-stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
    },
  },
}

Headless nodes have a separate default-on nodeHost.autoUpdate.enabled policy with hourly checks and idle-only activation. update.checkOnStart: false and APUS_NO_AUTO_UPDATE=1 disable that policy too. See Headless node updates.

ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    fallbacks: ["acpx-secondary"],
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    stream: {
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
    },
  },
}

Wizard

Behavior and metadata for CLI guided setup flows (onboard, configure, doctor):

{
  wizard: {
    accessMode: "full",
    appRecommendations: true,
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",
  },
}

Bridge (legacy, removed)

Current builds no longer include the TCP bridge. Nodes connect over the Gateway WebSocket. bridge.* keys are no longer part of the config schema (validation fails until removed; apus doctor --fix can strip unknown keys).

Legacy bridge config (historical reference) 
{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}