Skip to main content

​
Configure workspaces

A daemon starts with one primary 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. Add direct Git repositories to either configuration with --add-workspace or addWorkspaces in daemon-config.json.

​
Single repository

Point --workspace directly to the Git repository:

​
Repository collection

For multiple repositories, place them beneath one non-Git container directory. For example:
Set the container as the primary workspace and specify how many directory levels the daemon should search:
--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:
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 do not 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. Every discovered or explicitly added workspace must be a Git repository to use isolation. A non-Git discovery container is not placed in a worktree and does not prevent isolation. New isolated worktrees use the latest fetched commit from the current branch’s tracked upstream by default. Start the daemon with --no-worktree-pull to base new worktrees on the daemon workspace’s local HEAD instead. Existing worktrees are not rebased or recreated. 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 emits one Isolation blocker warning for each failing prerequisite. Each warning identifies Host Git or the specific Primary workspace or Additional workspace path and includes a stable reason code.

​
See also