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, memory — 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, memory, task types, 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, reproduction steps, depending on type).

Tasks can be nested into a hierarchy: initiatives contain epics, epics contain stories, features, and tasks, and stories can contain bugs, features, and tasks. The hierarchy is enforced by the type system — for example, bugs attach under stories, not directly under epics. See Task hierarchy for the full nesting rules and how to navigate the tree.

Task types

Every workspace starts with the same six 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

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.

Workspace admins can customise these types — changing the pipeline, required fields, and stage gates — via Settings → Task types or the ch workspace task-schema commands. See Customising task types and 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 AI worker templates (see below). They appear in the member list alongside humans.

Agents

An agent is a reusable worker template, not a long-lived process. It holds 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 (a separate checkout of the repo),
• a dedicated branch (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 only its task brief, the codebase, and any durable workspace memory. 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 — see Interactive dev sessions.

Repositories

A repository is a git repo connected to a workspace. Sandboxes are provisioned against a specific repo; the engine cuts a branch from that repo’s default 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