Self-hosted Environments

You can run your agents on your own virtual or physical infrastructure with self-hosted daemons.

About self-hosted daemons

Self-hosted daemons are ideal for teams that want Cosmos agents to run on your own infrastructure. You can run a single daemon to quickly use your personal setup to work with Cosmos, or deploy a daemon pool to provide a group of workers to Cosmos to distribute sessions to. Daemons have access to the host machine’s CPU, disk, and network; agents execute tools and make edits on the host machine but still make all LLM calls to Augment’s external services.

You can use daemon pools to group multiple separate machines into a single environment. Sessions started in those pooled environments will automatically select the first available slot in the pool without requiring the user to select a specific machine.

Using daemons

Each host must run the daemon process available through Auggie CLI.

Setup Auggie CLI

The daemon process is bundled with Auggie CLI, so you will need to install Auggie CLI on each host you want to run the daemon. You will need npm available on the host to install the package. Install the CLI with the following command:

npm install -g @augmentcode/auggie

Before you can start the daemon, you will need to authenticate the CLI. Your session will be persisted to the host machine. Login to your Augment account with the following command:

auggie login

You can also use other available authentication methods in Auggie CLI to set your credentials.

Start the daemon

After you have authenticated the Auggie CLI, start the daemon with the following command:

auggie daemon

Configuration

You can configure the daemon with the following optional CLI flags:

Flag	Details
--name <name>	Name of the daemon in the UI (defaults to hostname:workspace)
--max-agents <number>	Maximum number of concurrent sessions on the host (default: 100)
--workspace <path>	Set the primary path. Point to a Git repository for a single-repository workspace, or a non-Git container when using repository discovery (default: current working directory)
--add-workspace <path>	Add one Git repository explicitly (repeatable). This path is never searched for nested repositories
--discover-workspaces[=depth]	Discover Git repositories only beneath the non-Git --workspace path. Use =depth to search 1–5 directory levels (default: 1)
--no-discover-workspaces	Disable Git repository discovery
--vm-id <id>	The ID for the host (default: autogenerated UUID)
--pool-id <id>	The daemon pool to join

Workspace

The daemon starts with --workspace. If that path is a Git repository, the daemon uses it directly. If it is a non-Git container, the daemon can discover repositories beneath it. Use --add-workspace to add direct Git repositories to either configuration. Discovery never searches an --add-workspace path.

Single repository

Point --workspace directly to the Git repository:

auggie daemon --workspace /path/to/repo-a

Repository collection

For multiple repositories, we recommend placing them beneath one non-Git container directory. For example:

references/
├── group-a/
│   ├── repo-a/
│   └── repo-b/
├── group-b/
│   ├── repo-c/
│   └── repo-d/
└── group-c/
    └── repo-e/

Set the container as the primary workspace and specify how many directory levels the daemon should search:

auggie daemon --workspace /path/to/references --discover-workspaces=2

--discover-workspaces=2 searches beneath --workspace for repositories in a references/group/repository layout. Discovery searches only the primary workspace; it does not search directories passed with --add-workspace.

Mixed mode

Use --add-workspace to include direct Git repositories outside the discovery tree:

auggie daemon --workspace /path/to/references --discover-workspaces=2 \
  --add-workspace /path/to/standalone-repo

This configuration includes repositories discovered beneath references and the explicitly added standalone-repo. The daemon does not search beneath standalone-repo. To add repositories explicitly without discovery, point --workspace to one Git repository and repeat --add-workspace for each additional Git repository.

A non-Git container workspace can include up to 64 repositories across discovered repositories and explicit --add-workspace entries.

Workspace isolation

Cosmos offers two workspace behaviors for daemon-backed sessions:

• Isolated Workspace: Gives each agent its own Git worktree so file edits don’t affect the daemon workspace. For multiple repositories, the daemon creates a separate per-session worktree for each discovered or explicitly added Git repository.
• Shared Workspace: Agents use the daemon workspace directly, so file edits affect its working copy. Concurrent sessions can overwrite changes, create conflicts, or leave the checkout in an unexpected state.

We recommend Isolated Workspace when running concurrent sessions or when you want to keep agent changes separate from your working copy.

To use Isolated Workspace, every discovered or explicitly added workspace must be a Git repository. The non-Git discovery container itself is not placed in a worktree and does not prevent isolation.

Isolated daemon workspaces require Git 2.31.0 or newer, released March 15, 2021. At startup, the daemon logs the installed Git version and the minimum required version. If Git is old, unavailable, or its version cannot be parsed, the daemon remains online but reports worktrees as unsupported and cannot serve isolated pools. Upgrade or install Git, or use Shared Workspace instead.

When aggregate worktree isolation is unsupported, startup also emits one Isolation blocker warning for each failing prerequisite. Each warning identifies Host Git or the specific Primary workspace / Additional workspace path and includes a stable reason code.

Disconnecting

You can disconnect the daemon at any time with Cmd/Ctrl+C or by shutting down the host machine. Sessions using a disconnected daemon will queue any sent messages until the daemon is reconnected.

The session expects the reconnected daemon to be in the same filesystem state as it was when working, so it is recommended that you use git worktrees to reduce errors when agents connect to an out-of-sync environment.

Networking

Daemons need outbound access to Augment services to complete inference requests. See the full guide to network configuration for the allowlist of necessary domains.

Use daemon pools

Daemon pools allow you to group distinct hosts into a single environment. When a new session starts in the daemon pool environment, it will use one of the available slots from the connected hosts. Create and manage a pool in the Cosmos web UI or declaratively with Auggie Cloud, then connect hosts to it.

Creating a pool in the web UI

Create a new daemon pool in the Cosmos web UI by going to the Environments list and selecting Create an environment > Daemon Pool.

Managing pools with the CLI

Use a daemon pool bundle to create or update a pool from a YAML file. Initialize a bundle, set spec.pool.workspaceIsolation to shared or isolated, preview the change, and apply it:

auggie cloud pool init --name team-pool -o pool.yaml
# Edit pool.yaml and set spec.pool.workspaceIsolation to shared or isolated.
auggie cloud pool apply -f pool.yaml --dry-run
auggie cloud pool apply -f pool.yaml

After an apply, the CLI writes metadata.poolId and metadata.resourceVersion to the bundle. Subsequent applies use them for concurrency-safe updates. To begin from an existing pool instead, export its bundle:

auggie cloud pool export <pool-id> -o pool.yaml

Daemon pool bundles are a Preview CLI feature available to early adopters. Use auggie cloud pool --help to confirm that your installed CLI includes these commands.

Configuration

Name

The pool must have a unique name across your organization.

Connector

Only daemons with the proper authentication can connect to the pool. Select either Current user or a service account to use as the valid connector for the daemon. All daemons must be authenticated as this user or service account to join the pool.

Workspace behavior

When creating a daemon pool, you must choose how sessions use the workspaces on its daemons:

• Isolated Workspace: Each agent uses its own Git worktrees. Every daemon connected to the pool must support Git worktree isolation across all of its configured repositories. A non-Git discovery container is supported, but every discovered or explicitly added workspace must be a Git repository.
• Shared Workspace: Agents edit each daemon’s working copy directly. Concurrent sessions can overwrite changes, create conflicts, or leave the checkout in an unexpected state.

This setting applies to every session routed to the pool. Before choosing Isolated Workspace, configure and start each daemon with workspaces that meet the workspace isolation requirements.

Connecting to a pool

Once you have created a pool, you can start a daemon to join it. To connect to the pool you must: 1) pass the --pool-id flag when starting the daemon, 2) be autheticated as the user or service account set by the pool.

You can find the pool-id from the pool’s detail page. Then start it with the following command:

auggie daemon --pool-id <pool-id>