Configure Self-Hosted Daemons with daemon-config.json

About `daemon-config.json`

Use daemon-config.json to configure a self-hosted Cosmos daemon without repeating command-line flags. Auggie loads it automatically when you run auggie daemon; restart the daemon after changing it.

daemon-config.json requires Auggie 1.x. If you currently run Auggie 0.x, follow Migrate from Auggie 0.x.

For installation and authentication, see Self-Hosted Environments. See Workspaces and Isolation and Daemon Pools for related setup.

Quickstart

Create .augment/daemon-config.json in your workspace with only the settings you want to change. This configuration gives the daemon a recognizable name and limits it to 125 concurrent sessions:

{
  "name": "development-daemon",
  "maxAgents": 125
}

Start Auggie from the workspace:

cd /path/to/workspace
auggie daemon

This file sets only the daemon name and concurrency limit. Other effective values can still come from higher- or lower-precedence configuration, persisted daemon state, indexing permissions, or defaults.

daemon-config.json uses strict JSON, so inline comments and trailing commas are not supported. Keep explanations outside the JSON document, as shown above.

Example

The following example configures a pooled team daemon with repository discovery, one additional repository, isolated-worktree behavior, and file logging. Replace the pool ID and paths before using it, or omit settings that do not apply to your environment.

{
  "name": "team-daemon",
  "maxAgents": 125,
  "workspace": "/srv/repositories",
  "poolId": "replace-with-pool-id",
  "addWorkspaces": [
    "/srv/standalone-repository"
  ],
  "allowIndexing": true,
  "gitCredentialMode": "none",
  "worktreeDir": "~/.augment/worktrees",
  "noWorktreePull": false,
  "discoverWorkspaces": {
    "enabled": true,
    "depth": 2
  },
  "logFile": "~/.augment/logs/daemon.log",
  "logLevel": "info"
}

allowIndexing: true enables indexing for eligible configured workspaces. Review the indexing permission behavior before enabling it.
gitCredentialMode: "none" disables daemon-provided Git credentials. Review Git credential mode before selecting another mode.
Set noWorktreePull to true to base new worktrees on local HEAD instead of the latest fetched upstream commit.
Omit poolId if the daemon should not join a pool. Use spaceId instead to assign a standalone daemon to a Space.
vmId and newVmId are intentionally omitted so Auggie can reuse the persisted daemon identity.

Generate Configuration from Flags

Auggie can convert explicitly supplied daemon flags into daemon-config.json fields. These actions run offline and exit without starting the daemon.

Preview Generated JSON

Use --config-print to print strict JSON to standard output:

auggie daemon \
  --name team-daemon \
  --max-agents 125 \
  --allow-indexing \
  --config-print

Only flags supplied in that command are included. Existing configuration values and parser defaults are not copied, and relative paths are converted to absolute paths from the invocation directory. The one-shot --new-vm-id action is omitted with a warning because persisting it would request a new identity on every launch.

Write a Configuration File

Use --config-write=scope to write the generated configuration directly:

Scope	Option	Destination
Global	`--config-write` or `--config-write=global`	Global daemon configuration
Project	`--config-write=project`	`<workspace>/.augment/daemon-config.json`
Local project	`--config-write=local`	`<workspace>/.augment/daemon-config.local.json`

For example:

auggie daemon \
  --workspace /srv/repositories \
  --name team-daemon \
  --max-agents 125 \
  --allow-indexing \
  --config-write=project

Use the --config-write=project or --config-write=local equals-sign syntax. An explicit --workspace selects the destination workspace; otherwise Auggie uses the current Git root or current directory.

Writing configuration replaces the entire destination file; it does not merge with existing content. Auggie asks for confirmation before replacing an existing file in an interactive terminal and refuses the replacement when confirmation is unavailable. Use --config-print and merge manually when you need to preserve existing settings.

Configuration File Locations

Daemon configuration follows the same file hierarchy described in Hierarchical Settings File, using daemon-specific filenames. The scope locations are the same, but merge behavior differs: use the precedence and replacement rules documented on this page for daemon-config.json. Auggie checks four configuration scopes on every daemon start:

Scope	Location	Recommended use
Managed	`/etc/augment/daemon-config.json` on macOS and Linux; `C:\ProgramData\augment\daemon-config.json` on Windows	Organization-managed defaults for a host
Local project	`<workspace>/.augment/daemon-config.local.json`	Personal overrides for one workspace; add this file to `.gitignore`
Project	`<workspace>/.augment/daemon-config.json`	Team configuration that can be committed with the repository
Global	`~/.augment/daemon-config.json` on macOS and Linux; `C:\Users\<username>\.augment\daemon-config.json` on Windows	Personal defaults for every daemon

Configuration files are optional. Project and local files are resolved from an explicit --workspace path, otherwise from the current Git root or current directory. A workspace value inside the file changes the daemon’s primary workspace but does not relocate config discovery.

Precedence and daemon-specific merging

daemon-config.json uses the same file-scope order as settings.json: managed, local project, project, then global. The key precedence difference is that explicit daemon CLI flags sit above every file and can override managed daemon configuration, while managed settings.json values are locked and cannot be overridden by users. The formats also merge differently:

Behavior	`daemon-config.json`	`settings.json`
Managed values	Can be overridden by explicit daemon CLI flags	Cannot be overridden by users
Arrays and objects	Replaced as complete values by the higher-precedence file	Generally combined across tiers, with field-specific rules
File syntax	Strict JSON	JSON with Comments (JSONC)

Keep these daemon-specific rules in mind:

Missing keys inherit from lower-precedence scopes. Set a key to null to mask a lower value.
Arrays and objects are replaced, not combined or deep-merged. For example, a local addWorkspaces array replaces the project array.
worktreeDir falls back to its value in settings.json when it is absent from CLI flags and every daemon config scope.
allowIndexing is enable-only at the command line. Effective config true or --allow-indexing enables it; there is no CLI disable flag.
vmId cannot be combined with newVmId, and poolId cannot be combined with spaceId. When changing a configuration-only value, set the old key to null in the higher scope.
For persisted pool or Space membership, null only masks a lower config value. Use poolId: "" or spaceId: "" to actively clear existing membership.

Path resolution

workspace, addWorkspaces, worktreeDir, and logFile accept absolute paths or ~-prefixed home paths. Other relative paths resolve from the directory containing the config file—not the workspace root. For example, ../../repo-b in /srv/repo-a/.augment/daemon-config.json resolves to /srv/repo-b.

Use absolute paths in machine-specific global or managed configuration.

Configuration reference

Every key is optional. Any supported key may be set to null to mask a lower-precedence value.

Key	Type	Description
`name`	string	Name shown for the daemon. Defaults to `<hostname>:<workspace-name>`.
`maxAgents`	positive integer	Maximum number of concurrent child-agent sessions. Defaults to `100`.
`workspace`	string	Primary workspace path. Defaults to the directory from which the daemon is launched. A global or managed value applies to every daemon on the machine and produces a warning.
`vmId`	UUID v4 string	Reconnect using a specific existing daemon identity. Allowed only in project or local project configuration. Most users should omit this key and let Auggie reuse its persisted identity.
`newVmId`	boolean	When `true`, generate a new daemon identity. Prefer the one-time `--new-vm-id` flag unless every start should request a new identity. Cannot be combined with `vmId`.
`poolId`	string	Join the specified daemon pool. Set to `""` to clear persisted pool membership. Cannot be combined with `spaceId`.
`spaceId`	string	Assign a standalone daemon to a Space by UUID, name, or slug. Set to `""` to clear persisted Space membership. Cannot be combined with `poolId`; pooled daemons inherit Space membership from their pool.
`addWorkspaces`	array of strings	Additional Git repository paths. Each entry is resolved independently. The daemon does not search these paths for nested repositories.
`allowIndexing`	boolean	Allow child agents to index eligible configured workspaces. Defaults to `false`. Either effective config `true` or `--allow-indexing` enables it; there is no command-line disable flag.
`gitCredentialMode`	string	Select daemon-provided Git credentials: `none`, `user-oauth`, or `github-app`. The file stores only the policy, not credential material.
`worktreeDir`	string	Base directory for isolated-workspace Git worktrees. Defaults to `~/.augment/worktrees`. An empty `--worktree-dir=` flag is treated as absent and does not clear a configured value.
`noWorktreePull`	boolean	When `true`, base new isolated worktrees on the daemon workspace’s local `HEAD`. When `false` or omitted, use the latest fetched commit from the current branch’s upstream when available. Existing agent worktrees are not rebased or recreated.
`discoverWorkspaces`	object	Controls Git repository discovery beneath a non-Git primary workspace. See Repository discovery.
`logFile`	string	Daemon log path. If omitted, Auggie uses `augment-daemon.txt` in its temporary directory. The value `"-"` is not supported.
`logLevel`	string	Logging verbosity: `error`, `warn`, `info`, or `debug`. Defaults to `info`. Values are lowercase.

Repository discovery

See Workspaces and isolation for layouts and behavior. In daemon-config.json, set discoverWorkspaces.enabled to true or false; when enabled, optional depth must be from 1 through 5 and defaults to 1. Discovery is refused at the user’s home directory or a filesystem root. The daemon advertises up to 64 additional workspaces; overflow entries are dropped with a warning.

Workspace isolation

See Workspace isolation for requirements and behavior. worktreeDir controls where isolated worktrees are stored. By default, new worktrees use the latest fetched commit from the tracked upstream; set noWorktreePull to true to use local HEAD instead. Existing worktrees are not changed.

Git Credential Mode

gitCredentialMode controls whether the daemon provides Git credentials to child-agent Git operations:

none disables daemon-provided Git credentials.
user-oauth uses the daemon user’s GitHub OAuth access and is supported on macOS and Linux.
github-app uses GitHub App access available to the daemon.

The configuration stores only the selected policy, not tokens or other credential material. An explicit --git-credential-mode flag overrides configured values for that launch.

Project configuration is treated as user-approved policy and can enable credential access for child sessions. Review gitCredentialMode before starting a daemon from a repository you do not trust.

Indexing and Indexing Permissions

Set allowIndexing to enable indexing for configured workspaces that do not already have an explicit indexing permission:

{
  "allowIndexing": true
}

Auggie evaluates indexing permissions separately for each eligible workspace:

Paths covered by indexingDenyDirs in settings.json, stored deny decisions, and the home-directory hard block remain disabled. allowIndexing does not override them.
Paths covered by indexingAllowDirs or a stored allow decision can be indexed without allowIndexing.
Eligible paths without an allow or deny rule are indexed only when effective config allowIndexing is true or the daemon starts with --allow-indexing.
Git worktrees inherit the indexing permission of their main repository.
When the daemon starts interactively without allowIndexing, it may prompt to save allow decisions for unruled workspaces. Non-interactive startup does not prompt, so those workspaces remain disabled.

indexingAllowDirs and indexingDenyDirs belong in settings.json, not daemon-config.json. Their hierarchy and merge behavior are described in Hierarchical Settings File. Stored decisions are written to ~/.augment/indexing-permissions.json by default. To revoke a stored allow, remove the relevant entry, ensure the path is not enabled by allowIndexing or indexingAllowDirs, and restart the daemon. There is no --no-allow-indexing flag. To disable a configured value, change the file that enables it or mask a lower-scope value with null in a higher-precedence file.

A committed project configuration applies to everyone who starts a daemon from that workspace. Review allowIndexing and gitCredentialMode before committing it, and never place credentials or secrets in a daemon configuration file.

Local overrides

Keep shared defaults in .augment/daemon-config.json. Add .augment/daemon-config.local.json to .gitignore and use it for personal overrides:

{
  "allowIndexing": false,
  "logLevel": "debug",
  "logFile": "daemon.local.log"
}

Override configuration for one launch

Explicit flags override file values. For example, auggie daemon --max-agents 125 --log-level debug. An explicit --pool-id or --space-id also clears the configured alternative for that launch. Run auggie daemon --help for the full reference.

Validation

Auggie validates config at startup. Malformed JSON, invalid known values, forbidden global or managed vmId, and conflicting option pairs stop startup; unknown keys produce warnings and are ignored. A global or managed workspace is accepted with a warning because it affects every daemon on the machine.

Getting Started

Cosmos

Auggie CLI

Other clients

Admin

Models & Pricing

Troubleshooting

Configure Self-Hosted Daemons with daemon-config.json

About `daemon-config.json`

Quickstart

Example

Generate Configuration from Flags

Preview Generated JSON

Write a Configuration File

Configuration File Locations

Precedence and daemon-specific merging

Path resolution

Configuration reference

Repository discovery

Workspace isolation

Git Credential Mode

Indexing and Indexing Permissions

Local overrides

Override configuration for one launch

Validation

See also

​About daemon-config.json

​Quickstart

​Example

​Generate Configuration from Flags

​Preview Generated JSON

​Write a Configuration File

​Configuration File Locations

​Precedence and daemon-specific merging

​Path resolution

​Configuration reference

​Repository discovery

​Workspace isolation

​Git Credential Mode

​Indexing and Indexing Permissions

​Local overrides

​Override configuration for one launch

​Validation

​See also

About `daemon-config.json`

Quickstart

Example

Generate Configuration from Flags

Preview Generated JSON

Write a Configuration File

Configuration File Locations

Precedence and daemon-specific merging

Path resolution

Configuration reference

Repository discovery

Workspace isolation

Git Credential Mode

Indexing and Indexing Permissions

Local overrides

Override configuration for one launch

Validation

See also