---
title: "Workspace model"
description: "Understand projects, groups, sessions, layouts, session ids, resume ids, and startup behavior."
---

Desk's workspace model is intentionally small. A manifest contains projects;
projects contain groups; groups contain sessions.

## Projects

A project represents a working tree or root directory. It gives Desk a stable
scope for sessions, editor roots, Git discovery, and group organization.

Use one project per repository when your agents work in different repos. Use
one project with multiple groups when several agents work in the same repo.

## Groups

A group is a cell-grid workspace inside a project — each cell holds a session
rendered as a native agent chat or a terminal. Groups are useful for:

- separating roles such as frontend, backend, reviewer, and release
- keeping noisy commands away from agent sessions
- switching between related session grids
- preserving layout and selected sessions per workstream

Each group has a layout such as one cell, a grid, or custom split sizes. Desk
persists layout changes to the manifest.

## Sessions

A session describes one Moor-backed process. It can be:

- a managed Codex session
- a managed Claude session
- a managed OpenCode session
- a Bash shell
- a custom command

Managed agent sessions get Desk launch flags, permission handling, resume
capture, attention hooks, and optional LSP MCP wiring. Custom commands run as
the command you provide.

## Session ids

Every session has a durable `sessionId`. Desk preserves an existing id or mints
one from the session name when you add or migrate a session. The id is the
shared key for:

- the Moor control socket
- terminal generation and snapshot state
- channels membership and delivery queues
- attention, resume capture, and agent event routing

## Resume ids

Resume ids belong to the agent CLI, not to Moor. Desk stores known resume ids in
the manifest and can also harvest them after a first turn for managed agents.

Use resume ids when you want a restarted agent CLI to reconnect to the same
conversation. Bash and custom command sessions do not use agent resume ids.

## Startup behavior

`desk up` reads the manifest, checks the configured Moor control sockets, and
starts only the missing sessions. It does not replace running sessions.

Use `desk up --dry-run` before changing a large fleet.

## Browser state

The browser stores selected views, open editor tabs, panel sizes, and UI
preferences separately from Moor process lifetime. If you reload the browser,
Desk reconnects to the running sessions through the binary terminal transport.

## Next steps

- Build a real manifest in [Create an agent fleet](/guide-create-agent-fleet).
- Read [Configuration](/configuration) for every manifest field.
- Read [Operations](/operations) for session controls and health checks.