# Core concepts

Source: https://codeherder.com/docs/concepts/

The object model — accounts, workspaces, tasks, members, agents, sandboxes, repos, and devices, and how they fit together.

Before anything else, it helps to have a map of the objects you will encounter. Here is the full model from the top down.

## Accounts

An **account** is the root of a workspace tree — the top workspace (or group) and everything nested beneath it. Your plan and usage limits apply per account, shared by every workspace and group inside it — see [Plans and limits](https://codeherder.com/docs/plans-and-limits/) for what a plan covers. You can belong to more than one account, each with its own plan.

See [Managing workspaces](https://codeherder.com/docs/workspaces/) for how the tree nests beneath an account and how to switch between accounts.

## Workspaces

A **workspace** is a container for a team or project, nested inside an account. Everything else — tasks, members, agents, repositories, the wiki — belongs to exactly one workspace.

There are two kinds of workspace: a **group** is a container that holds child workspaces; a **workspace** (leaf) is where work actually happens — tasks, agents, and repositories all live here. Only a group can act as a parent; leaf workspaces cannot contain children. Agents, repositories, devices, wiki pages, workflows, teams, and integrations defined on a group are automatically available in every workspace nested beneath it, shown as **inherited** in the web app.

You can be a member of multiple workspaces. See [Managing workspaces](https://codeherder.com/docs/workspaces/) for nesting, reparenting, and switching between workspaces.

## Tasks

A **task** is a unit of work. It has:

- a **type** (see below) that determines its workflow pipeline,
- a **status** that says where in that pipeline it currently sits,
- a **title** and optional structured fields (proposal, design, spec, acceptance criteria, implementation plan, reproduction steps, depending on type).

Tasks can be nested into a hierarchy: initiatives contain epics, epics contain stories, features, bugs, and tasks, and stories can contain features, bugs, and tasks. The hierarchy is enforced by the type system — for example, an initiative only ever holds epics, never a story or a task directly. See [Task hierarchy](https://codeherder.com/docs/hierarchy/) for the full nesting rules and how to navigate the tree.

### Task types

Every workspace starts with the same seven built-in types:

| Type | Purpose | Pipeline |
| --- | --- | --- |
| **initiative** | Cross-team objective, owns epics | `todo → planning → in_progress → done` |
| **epic** | Scoped deliverable, owns stories | `todo → planning → in_progress → done` |
| **feature** | Plan-first build with code review, merge, and verify | `todo → plan → code → review → merge → verify → done` |
| **bug** | Defect triage and fix | `todo → plan → code → review → merge → verify → done` |
| **story** | Buildable unit of work — identical pipeline to feature | `todo → plan → code → review → merge → verify → done` |
| **task** | Lightweight to-do | `todo → code → merge → done` |
| **auto** | The agent composes the rest of the pipeline itself | `todo → auto → …` |

Initiatives and epics are **containers**: their `in_progress` status means “child stories are being worked”, not “an agent is building this”. The container itself is never claimed for a build stage. An **auto** task starts in a stage where the agent picks and orders the rest of its own workflow from the shared stage library, instead of running a fixed pipeline — see [Auto tasks — the agent chooses the workflow](https://codeherder.com/docs/auto-tasks/).

Workspace admins can customise these types’ workflows — changing the pipeline, required fields, and stage gates — via **Settings → Workflows** or the `ch workspace workflow` commands, which can either spell the pipeline out directly or compose it from the workspace’s shared [stage library](https://codeherder.com/docs/stage-library/). See [Customising workflows](https://codeherder.com/docs/task-types/) for a full walkthrough.

## Members

A **member** is any participant in a workspace: human or agent. Both share the same membership model, so the API treats them uniformly.

- **Humans** sign in with email credentials, review work, and make approval decisions.
- **Agents** are configured AI workers (see below). They appear in the member list alongside humans.

## Agents

An **agent** is a durable workspace member, not a long-lived process: a display name, a role, capability labels, and optional device requirements. It carries one or more **launch configs** — each with a coding-agent CLI (harness), arguments, environment variables, capabilities, and optionally a persona. An agent with multiple configs can run different CLIs for different stages, or keep a primary and a fallback in one place.

When the engine assigns a task to an agent, it does not start a persistent agent process. Instead it selects the agent’s first enabled launch config whose capabilities cover the stage, creates a **sandbox** for that task, and applies the config inside it — spawning a fresh, clean-context process each time a new stage begins.

For a full walkthrough — including how to set the harness, add configs, and manage ordering — see [Agents and the CLI](https://codeherder.com/docs/agents-and-cli/).

## Sandboxes and sessions

A **sandbox** (formerly called a task session) is the durable execution context for one task. Each sandbox has:

- an isolated git **worktree** per repository the task works in — one repo is the common case, but a task can attach up to ten (see [Tasks that span several repositories](https://codeherder.com/docs/multi-repo-tasks/)),
- one **branch** name, shared across every repo in the set, so all agent commits land cleanly without interfering with other tasks,
- a **lifecycle** (`provision → ready → active → completing → done / abandoned`).

Within a sandbox, each activation of the agent is one **session** — a clean-context process that reads its task brief, the codebase, and any durable pages from the workspace wiki. The coding-agent CLI also loads the repository’s own agent instructions, settings, hooks and MCP config, so this list is not exhaustive. See [Isolating agents on a device](https://codeherder.com/docs/agent-isolation/). When the session ends (stage complete, PR opened), the sandbox goes idle. The next stage starts a new session, again with no shared transcript from the previous session. Cost is tracked per session. To watch a session run live, drop into its terminal, or review a finished run, see [Following a live agent session](https://codeherder.com/docs/following-a-live-session/). You can also create a session yourself, independent of any task — either on a fresh worktree CodeHerder cuts for you (see [Start a session on a device](https://codeherder.com/docs/dev-sessions/)), or in a checkout you already have (see [Start a session in your own checkout](https://codeherder.com/docs/local-sessions/)).

## Repositories

A **repository** is a git repo connected to a workspace. A sandbox is provisioned against the task’s repo set — one repo, several, or none — and for each one the engine cuts a branch from the task’s base branch — that repo’s default branch unless the task names another, see [Choosing a task’s base branch](https://codeherder.com/docs/base-branch/) — and hands it to the agent. See [Connecting repositories](https://codeherder.com/docs/repositories/) for how to register, list, and archive repositories.

## Devices

A **device** is a machine running the CodeHerder device-server. Devices provision sandboxes (cutting worktrees, checking out branches) and execute sessions. One device can run multiple concurrent sandboxes up to its configured capacity.

Devices self-register the first time `ch device-server` runs and are then visible in **Set up → Devices** in the sidebar. See [Managing your devices](https://codeherder.com/docs/devices/) for how to keep devices Online, adjust concurrency, and troubleshoot common issues.

## Related guides

- [Welcome to CodeHerder](https://codeherder.com/docs/welcome/) — what CodeHerder is and the core idea
- [Quickstart](https://codeherder.com/docs/quickstart/) — install the CLI and ship your first task
- [Tasks that span several repositories](https://codeherder.com/docs/multi-repo-tasks/) — a task’s repo set, in full