From d99fc89790beeb1645408c0f2f662ce56698155d Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Wed, 7 Jan 2026 00:04:03 +0100 Subject: [PATCH] docs: add agent workspace guide --- docs/agent-workspace.md | 187 ++++++++++++++++++++++++++++++++++++++++ docs/agent.md | 2 + docs/clawd.md | 2 + docs/hubs.md | 1 + docs/wizard.md | 1 + 5 files changed, 193 insertions(+) create mode 100644 docs/agent-workspace.md diff --git a/docs/agent-workspace.md b/docs/agent-workspace.md new file mode 100644 index 000000000..7e85fd7a6 --- /dev/null +++ b/docs/agent-workspace.md @@ -0,0 +1,187 @@ +--- +summary: "Agent workspace: location, layout, and backup strategy" +read_when: + - You need to explain the agent workspace or its file layout + - You want to back up or migrate an agent workspace +--- +# Agent workspace + +The workspace is the agent's home. It is the only working directory used for +file tools and for workspace context. Keep it private and treat it as memory. + +This is separate from `~/.clawdbot/`, which stores config, credentials, and +sessions. + +## Default location + +- Default: `~/clawd` +- If `CLAWDBOT_PROFILE` is set and not `"default"`, the default becomes + `~/clawd-`. +- Override in `~/.clawdbot/clawdbot.json`: + +```json5 +{ + agent: { + workspace: "~/clawd" + } +} +``` + +`clawdbot onboard`, `clawdbot configure`, or `clawdbot setup` will create the +workspace and seed the bootstrap files if they are missing. + +If you already manage the workspace files yourself, you can disable bootstrap +file creation: + +```json5 +{ agent: { skipBootstrap: true } } +``` + +## Workspace file map (what each file means) + +These are the standard files Clawdbot expects inside the workspace: + +- `AGENTS.md` + - Operating instructions for the agent and how it should use memory. + - Loaded at the start of every session. + - Good place for rules, priorities, and "how to behave" details. + +- `SOUL.md` + - Persona, tone, and boundaries. + - Loaded every session. + +- `USER.md` + - Who the user is and how to address them. + - Loaded every session. + +- `IDENTITY.md` + - The agent's name, vibe, and emoji. + - Created/updated during the bootstrap ritual. + +- `TOOLS.md` + - Notes about your local tools and conventions. + - Does not control tool availability; it is only guidance. + +- `HEARTBEAT.md` + - Optional tiny checklist for heartbeat runs. + - Keep it short to avoid token burn. + +- `BOOTSTRAP.md` + - One-time first-run ritual. + - Only created for a brand-new workspace. + - Delete it after the ritual is complete. + +- `memory/YYYY-MM-DD.md` + - Daily memory log (one file per day). + - Recommended to read today + yesterday on session start. + +- `MEMORY.md` (optional) + - Curated long-term memory. + - Only load in the main, private session (not shared/group contexts). + +- `skills/` (optional) + - Workspace-specific skills. + - Overrides managed/bundled skills when names collide. + +- `canvas/` (optional) + - Canvas UI files for node displays (for example `canvas/index.html`). + +If any bootstrap file is missing, Clawdbot injects a "missing file" marker into +the session and continues. `clawdbot setup` can recreate missing defaults +without overwriting existing files. + +## What is NOT in the workspace + +These live under `~/.clawdbot/` and should NOT be committed to the workspace repo: + +- `~/.clawdbot/clawdbot.json` (config) +- `~/.clawdbot/credentials/` (OAuth tokens, API keys) +- `~/.clawdbot/agents//sessions/` (session transcripts + metadata) +- `~/.clawdbot/skills/` (managed skills) + +If you need to migrate sessions or config, copy them separately and keep them +out of version control. + +## Git backup (recommended, private) + +Treat the workspace as private memory. Put it in a **private** git repo so it is +backed up and recoverable. + +Run these steps on the machine where the Gateway runs (that is where the +workspace lives). + +### 1) Initialize the repo + +```bash +cd ~/clawd +git init +git add AGENTS.md SOUL.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md memory/ +git commit -m "Add agent workspace" +``` + +### 2) Add a private remote (beginner-friendly options) + +Option A: GitHub web UI + +1. Create a new **private** repository on GitHub. +2. Do not initialize with a README (avoids merge conflicts). +3. Copy the HTTPS remote URL. +4. Add the remote and push: + +```bash +git branch -M main +git remote add origin +git push -u origin main +``` + +Option B: GitHub CLI (`gh`) + +```bash +gh auth login +gh repo create clawd-workspace --private --source . --remote origin --push +``` + +### 3) Ongoing updates + +```bash +git status +git add . +git commit -m "Update memory" +git push +``` + +## Do not commit secrets + +Even in a private repo, avoid storing secrets in the workspace: + +- API keys, OAuth tokens, passwords, or private credentials. +- Anything under `~/.clawdbot/`. +- Raw dumps of chats or sensitive attachments. + +If you must store sensitive references, use placeholders and keep the real +secret elsewhere (password manager, environment variables, or `~/.clawdbot/`). + +Suggested `.gitignore` starter: + +```gitignore +.DS_Store +.env +**/*.key +**/*.pem +**/secrets* +``` + +## Moving the workspace to a new machine + +1. Clone the repo to the desired path (default `~/clawd`). +2. Set `agent.workspace` to that path in `~/.clawdbot/clawdbot.json`. +3. Run `clawdbot setup --workspace ` to seed any missing files. +4. If you need sessions, copy `~/.clawdbot/agents//sessions/` from the + old machine separately. + +## Advanced notes + +- Multi-agent routing can use different workspaces per agent. See + `docs/provider-routing.md` for routing configuration. +- If `agent.sandbox` is enabled, non-main sessions can use per-session sandbox + workspaces under `agent.sandbox.workspaceRoot`. diff --git a/docs/agent.md b/docs/agent.md index 44b449748..c5081f6ab 100644 --- a/docs/agent.md +++ b/docs/agent.md @@ -13,6 +13,8 @@ CLAWDBOT uses a single agent workspace directory (`agent.workspace`) as the agen Recommended: use `clawdbot setup` to create `~/.clawdbot/clawdbot.json` if missing and initialize the workspace files. +Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace) + If `agent.sandbox` is enabled, non-main sessions can override this with per-session workspaces under `agent.sandbox.workspaceRoot` (see [`docs/configuration.md`](https://docs.clawd.bot/configuration)). diff --git a/docs/clawd.md b/docs/clawd.md index 7f4115b70..615d96009 100644 --- a/docs/clawd.md +++ b/docs/clawd.md @@ -93,6 +93,8 @@ Tip: treat this folder like Clawd’s “memory” and make it a git repo (ideal clawdbot setup ``` +Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace) + Optional: choose a different workspace with `agent.workspace` (supports `~`). ```json5 diff --git a/docs/hubs.md b/docs/hubs.md index 46fccefa2..4da01a328 100644 --- a/docs/hubs.md +++ b/docs/hubs.md @@ -28,6 +28,7 @@ Use these hubs to discover every page, including deep dives and reference docs t - [Architecture](https://docs.clawd.bot/architecture) - [Agent runtime](https://docs.clawd.bot/agent) +- [Agent workspace](https://docs.clawd.bot/agent-workspace) - [Agent loop](https://docs.clawd.bot/agent-loop) - [Multi-agent routing](https://docs.clawd.bot/multi-agent) - [Sessions](https://docs.clawd.bot/session) diff --git a/docs/wizard.md b/docs/wizard.md index c513eb377..13e10925c 100644 --- a/docs/wizard.md +++ b/docs/wizard.md @@ -59,6 +59,7 @@ It does **not** install or change anything on the remote host. 3) **Workspace** - Default `~/clawd` (configurable). - Seeds the workspace files needed for the agent bootstrap ritual. + - Full workspace layout + backup guide: [`docs/agent-workspace.md`](https://docs.clawd.bot/agent-workspace) 4) **Gateway** - Port, bind, auth mode, tailscale exposure.