---
title: Workspaces
summary: Workspace lifecycle — attach, exit, detach, worktree isolation, and how workspaces differ from shell directories.
order: 17
---
# Workspaces
A workspace is the execution root for an agent — where it reads files, runs
commands, and applies patches. Every agent always has exactly one active
workspace.
## What a Workspace Defines
| Instruction root | Where `AGENTS.md` and policy files resolve |
| Execution root | Default working directory for commands |
| ApplyPatch target | Where file mutations land |
| Memory scope | Workspace-scoped episode records and indexes |
## Workspace vs Shell Directory
A workspace is **not** a shell `cd`. Shell `cd` changes the directory for
that one command process. Changing the active workspace requires
`holon workspace attach` or the `UseWorkspace` tool — this redefines where
runtime tools operate.
| `cd /other` in shell | Only affects that command |
| `UseWorkspace` | Changes active workspace for all subsequent operations |
| `holon workspace attach /path` | CLI equivalent of UseWorkspace |
## Workspace Commands
### Attach
Attach to a project directory as the active workspace:
```bash
holon workspace attach /path/to/project
holon workspace attach --agent my-agent /path/to/project
```
This discovers or creates a workspace record for the directory and makes it
active for the agent. The workspace persists across sessions.
### Exit
Return to the agent's home workspace:
```bash
holon workspace exit
holon workspace exit --agent my-agent
```
### Detach
Remove a workspace record entirely:
```bash
holon workspace detach <workspace-id>
```
Detaching does not delete the directory — it removes the workspace record
from Holon's index. Memory and episode records associated with the workspace
are preserved.
## Workspace Modes
### Direct Mode
The default. All operations happen in-place on the real filesystem:
```bash
holon workspace attach /home/user/project
```
Use direct mode for normal development work where you want changes to
persist on disk immediately.
### Isolated Mode (Worktrees)
Isolated workspaces create a managed worktree — a separate checkout that can
be modified without affecting the original:
```bash
# The runtime creates an isolated worktree
holon workspace attach /path/to/repo --mode isolated --isolation-label experiment
```
Isolated workspaces are useful for:
- Safe experimentation without polluting the working copy
- Parallel work on the same repository by different agents
- PR review branches where changes should not leak
## Agent Home vs Project Workspace
| Agent home | Agent-local state and memory | `~/.holon/agents/my-agent/` |
| Project workspace | Code and files being worked on | `/path/to/project` |
Every agent starts with its agent home as the active workspace. Use
`workspace attach` to switch to a project workspace, and `workspace exit` to
return to agent home.
## UseWorkspace Tool
Agents use the `UseWorkspace` tool during execution to switch workspaces
programmatically:
- `UseWorkspace({ path: "/repo" })` — attach to a directory
- `UseWorkspace({ workspace_id: "agent_home" })` — return to agent home
- `UseWorkspace({ workspace_id: "ws-..." })` — switch to a known workspace
- `mode: "isolated"` — request an isolated worktree
- `access_mode: "exclusive_write"` — request write access
## See Also
- [Runtime Model](/concepts/runtime-model.md) — Workspace lifecycle in the runtime
- [CLI Reference](/reference/cli.md) — All workspace commands
- [Agent Templates](/guides/agent-templates.md) — How templates initialize agent homes