> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Self-Hosted Daemons with daemon-config.json

> Configure Auggie's self-hosted daemon with discovered JSON files or generate configuration from explicit command-line flags.

## 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.

<Note>
  `daemon-config.json` requires Auggie 1.x. If you currently run Auggie 0.x, follow [Migrate from Auggie 0.x](/cosmos/environments/daemons#migrate-from-auggie-0-x).
</Note>

For installation and authentication, see [Self-Hosted Environments](/cosmos/environments/daemons). See [Workspaces and Isolation](/cosmos/environments/daemon-workspaces) and [Daemon Pools](/cosmos/environments/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:

```json theme={null}
{
  "name": "development-daemon",
  "maxAgents": 125
}
```

Start Auggie from the workspace:

```sh theme={null}
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.

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

## 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.

```json theme={null}
{
  "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](#indexing-and-indexing-permissions) before enabling it.
* `gitCredentialMode: "none"` disables daemon-provided Git credentials. Review [Git credential mode](#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:

```sh theme={null}
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:

```sh theme={null}
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.

<Warning>
  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.
</Warning>

## Configuration File Locations

Daemon configuration follows the same file hierarchy described in [Hierarchical Settings File](/cli/config#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`](/cli/config#hierarchical-settings-file): 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`.

<Tip>
  Use absolute paths in machine-specific global or managed configuration.
</Tip>

## 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](#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](/cosmos/environments/daemon-workspaces#configure-workspaces) 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](/cosmos/environments/daemon-workspaces#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.

<Warning>
  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.
</Warning>

## Indexing and Indexing Permissions

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

```json theme={null}
{
  "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](/cli/config#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.

<Warning>
  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.
</Warning>

## Local overrides

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

```json theme={null}
{
  "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.

## See also

* [Self-Hosted Environments](/cosmos/environments/daemons)
* [Workspaces and Isolation](/cosmos/environments/daemon-workspaces)
* [Daemon Pools](/cosmos/environments/daemon-pools)
* [Migrate from Auggie 0.x](/cosmos/environments/daemons#migrate-from-auggie-0-x)
* [Auggie CLI authentication](/cli/setup-auggie/authentication)
* [CLI reference](/cli/reference)