Core concepts

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 for what a plan covers. You can belong to more than one account, each with its own plan.

See Managing 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 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 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.

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. See Customising workflows 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.

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),
• 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. 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. 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), or in a checkout you already have (see Start a session in your own checkout).

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 — and hands it to the agent. See Connecting 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 for how to keep devices Online, adjust concurrency, and troubleshoot common issues.

Related guides

• Welcome to CodeHerder — what CodeHerder is and the core idea
• Quickstart — install the CLI and ship your first task
• Tasks that span several repositories — a task’s repo set, in full