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

# Instances

> One brain per instance — hard physical isolation for multi-agent setups

Every instance is a fully separate brain: its own catalog, lake, sidecars, and `state.sql`, at `~/.duckbrain/<instance>/`.

```bash theme={null}
duckbrain init --instance cindy          # ~/.duckbrain/cindy/
duckbrain search "..." --instance cindy  # flag form
DUCKBRAIN_INSTANCE=cindy duckbrain ...   # env form
DUCKBRAIN_ROOT=/path duckbrain ...       # relocate the whole tree
```

**Two isolation levels:** instances are physical (separate files — one per agent principal); namespaces/container-tags scope logically *within* an instance (per-workspace views of a shared brain).

Moving an instance directory requires re-init or `OVERRIDE_DATA_PATH` — the DuckLake catalog stores its data path internally.


## Related topics

- [init](/commands/init.md)
- [DuckBrain](/index.md)
- [doctor](/commands/doctor.md)
- [sync](/commands/sync.md)
- [Search & Facets](/search.md)