Workspaces

A workspace is a self-contained environment for working on a thing. Each workspace has its own sources, skills, agents, commands, labels, statuses, sessions, and optionally its own theme. Switch workspaces and you get a different set of tools and history.

Typical pattern: one workspace per project, one per client, or one for "personal" vs "work".

Where workspaces live

Every workspace is a folder. By default, workspaces live at:

~/.fabric-agent/workspaces/{workspace-id}/

A workspace ID is a slug derived from the name you gave it. You can also create a workspace anywhere on disk — point Fabric Agents at ~/code/my-project/ and that folder becomes the workspace root. This is handy for project-scoped workspaces committed to a repo, so teammates get the same sources and skills.

Inside a workspace folder:

{workspace}/
├── config.json            # workspace defaults (permission mode, thinking level, theme, …)
├── sources/               # one subdirectory per source
├── sessions/              # one subdirectory per session
├── skills/                # skill .md files
├── agents/                # agent .md files
├── commands/              # slash command .md files
├── labels.json
├── statuses.json
└── .fabric-agent/
    └── color-theme.json   # per-workspace theme override (optional)

Per-workspace vs global

So: adding a source in workspace A doesn't show up in workspace B. But your Anthropic API key, your preferred language, and the connection list are shared.

Creating a workspace

• Sidebar → workspace switcher → Add Workspace.
• Choose Create New (default location) or Choose Location (point at a folder you already have).
• Give it a name. Optionally connect to a remote server (see below).
• Click Create.

The app generates an ID from the name, creates the folder structure, and switches you into it.

Switching

The workspace switcher at the top of the sidebar shows every workspace you have. Click one to switch. The current window swaps its workspace context — sources re-load, sessions re-populate, themes re-apply.

Open in a new window — Cmd/Ctrl + click on a workspace (or the external-link button beside it) opens it in a separate window. You can run two workspaces side-by-side this way, each with its own server connection.

Window titles — with a single window open, the title bar shows the app name. As soon as a second window opens, each window's title switches to the name of the workspace it's showing, so they're easy to tell apart in Cmd-Tab, Mission Control, and the Windows taskbar. Close back down to one window and the title reverts to the app name.

Multi-workspace mode ("show all")

Toggle Show sessions from all workspaces in the sidebar to see every session across every workspace in one inbox. Workspace badges appear on each session row so you can tell them apart.

Clicking a session from a different workspace auto-switches the window to that workspace before opening the session. This is the fastest way to triage a mixed inbox without manually hopping.

Deleting

Remove a workspace from the switcher → Remove Workspace. This only removes it from the app's list — the folder on disk stays put. If you want to wipe the data too, delete the folder yourself:

rm -rf ~/.fabric-agent/workspaces/{workspace-id}

Remote workspaces (thin-client)

A workspace can point at a remote Fabric Agents server instead of running locally. The desktop app becomes a thin client: UI renders locally, all session logic, tool execution, and LLM calls happen on the remote machine.

Setup:

# On the server (e.g. a Linux VPS)
FABRIC_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

# Copy the printed FABRIC_SERVER_URL and FABRIC_SERVER_TOKEN

Then in the desktop app: Add Workspace → Connect Remote → paste the URL and token → pick which remote workspace to connect to.

Once connected:

• The switcher shows a cloud icon beside remote workspaces with a real-time health check.
• Sessions, sources, and skills live on the server, not your laptop.
• Closing the laptop doesn't pause long-running work.
• You can connect from multiple machines — phone-home-from-coffee-shop style.

A few things to know:

• The connection uses a WebSocket; if it drops, the app retries with exponential backoff. Reconnect preserves session state.
• Credentials for sources live on the server, not the client. This means teammates sharing a remote server share credential visibility.
• Token rotation: change FABRIC_SERVER_TOKEN on the server and re-paste in the desktop app.

Keyboard and ergonomics

• Cmd / Ctrl + Shift + N opens a new window (workspace picker on first launch).
• The workspace switcher remembers the last workspace per window — close and reopen and you land where you left off.

Related

• Conversations — sessions are workspace-scoped
• Sources — added per-workspace
• Sharing — publish a single session outside the workspace