Managing workspaces

A workspace is the top-level container for a team or project. Everything in CodeHerder — tasks, members, agents, repositories, and memory — belongs to exactly one workspace. For a full overview of the object model, see Core concepts.

Workspace hierarchy

Workspaces come in two kinds:

• A group is a container: it can hold child workspaces (other groups, or leaf workspaces) and acts as a shared source of resources for everything nested beneath it.
• A workspace (leaf) is where work happens: tasks, agents, repositories, and memory all live in a leaf workspace.

Only a group can act as a parent. If you attempt to nest a workspace under a leaf workspace — via ch workspace create --parent or the web app — the operation is rejected. Nesting is optional: a single flat workspace is perfectly fine for smaller teams.

Membership flows downward: being a member of a workspace gives you access to its descendant workspaces. Being a member of a child workspace does not grant access to its ancestors or siblings.

Accounts and the account home

An account is a root workspace (or group) and everything nested beneath it — the top of one workspace tree. Your plan and usage limits attach at the account level and are shared by everything inside it; see Plans and limits for what a plan covers. You can belong to more than one account, each with its own root and its own plan.

Every signed-in user sees their current account’s name in the topbar. If you belong to more than one account, that name becomes a switcher: click it to open a list of every account you belong to, each shown with its plan, with your current account highlighted. Pick one to jump straight into it, or choose View all accounts to go to the account home.

The account home is the Dashboard you land on at /, before entering any workspace — see Managing workspaces in the web app, below, for what it shows and how to use it. It’s a different screen from a workspace’s own Dashboard, which shows that workspace’s tiles and activity charts once you’re inside it — see Finding and tracking your work for that view.

There’s no separate command for switching accounts — from the CLI you scope every command to a workspace with --workspace or CH_WORKSPACE_ID; see Selecting your active workspace in the CLI, below.

Creating a workspace

ch workspace create --name "My Project" [--description "<text>"] [--parent <parentId>]

The workspace is created immediately. The caller automatically becomes its owner. Omit --parent to create a root workspace. Pass --parent with the ID of an existing group workspace to nest the new one beneath it:

ch workspace create --name "Platform" --parent 019e4c2c-b513-7be2-8c7b-8229c62e020b

If the specified parent is a leaf workspace rather than a group, the command returns an error.

Note: The CLI creates leaf workspaces only. To create a group, use the + New Group button in the web app (available on the Dashboard and on any group landing page) — see Managing workspaces in the web app below.

You can also create a leaf workspace in the web app — see Managing workspaces in the web app below.

Listing workspaces

ch workspace list

This prints every workspace you are a direct member of — its ID, name, status, parent ID (if nested), and root ID.

To see the full tree rooted at a workspace:

ch workspace tree [<rootWorkspaceId>]

Omitting the ID defaults to the workspace set in CH_WORKSPACE_ID. The output is an ASCII tree of the workspace and all its descendants.

Inspecting a workspace

ch workspace show [<workspaceId>]

Prints the workspace’s ID, name, path, status, description, parent, and root. Omit the ID to inspect the currently active workspace.

For a summary of task counts by status and priority, a member breakdown by kind (people vs. agents), and a 7-day created/completed trend:

ch workspace stats [<workspaceId>]

Editing a workspace

ch workspace edit <workspaceId> [--name <n>] [--description <d>] [--default-repo <name|id> | --clear-default-repo] [--stall-timeout <minutes> | --clear-stall-timeout]

<workspaceId> is required. This is a sparse update — only the flags you supply are changed; anything you omit is left as-is. At least one of --name, --description, --default-repo, --clear-default-repo, --stall-timeout, or --clear-stall-timeout is required, and the name cannot be empty.

ch workspace edit 019e4c2c-b513-7be2-8c7b-8229c62e020b --name "Platform Team" --description "Core platform work"

--default-repo sets which repository a leaf workspace’s tasks build in when it has more than one connected repo; --clear-default-repo removes it. See Which repository a task builds in in Connecting repositories for how that choice is made and what it takes to set one.

--stall-timeout <minutes> sets how long a task can go untouched before CodeHerder flags it as stalled, from 1 minute up to 10080 (7 days); --clear-stall-timeout removes the override and returns the workspace to the 60-minute default. This setting belongs to a leaf workspace — tasks never live in a group, so a group can’t take it. ch workspace show prints a stall timeout: row only when an override is set; if it’s absent, the workspace is on the 60-minute default. See Assigning and claiming work for what a stall means and how it clears.

Only a workspace owner or admin can edit these details.

The CLI doesn’t cover a workspace’s URL — set that from the web app, see Managing workspaces in the web app, below.

Nesting and reparenting

To nest an existing workspace under a new parent:

ch workspace set-parent <childWorkspaceId> <newParentWorkspaceId>

The target parent must be a group workspace. If it is a leaf workspace, the operation is rejected.

To promote a workspace back to root level:

ch workspace set-parent <childWorkspaceId> --clear

You can also move a workspace in the web app: open the group it belongs to, go to Settings → General, scroll to the Manage workspaces section, and click Move in that workspace’s row.

Resource inheritance

Resources defined on a group workspace are automatically available in every workspace nested beneath it. The following resource types inherit down the tree:

• Agents — agents created in a group appear in each descendant workspace’s agent list.
• Repositories — repositories connected to a group are usable in any descendant workspace.
• Devices — devices registered to a group are available for running tasks in descendant workspaces.
• Memory — confirmed memory entries written in a group are readable from any descendant workspace.
• Task types — task-type schemas defined in a group (via Settings → Task types) are usable in descendant workspaces; a descendant can override a type locally, in which case its local version takes precedence.
• Teams — teams created in a group appear in each descendant workspace’s team list.

In the web app, inherited resources appear in each descendant workspace’s lists with an inherited chip. They are read-only in the descendant — to edit or archive them, open the group workspace where they were defined.

Selecting your active workspace in the CLI

Most CLI commands are workspace-scoped. The CLI resolves the target workspace in this order:

1. A --workspace <id> flag passed directly to the command (available on commands such as member list, agent create, and others).
2. The CH_WORKSPACE_ID environment variable.

ch device-server follows the same precedence for its first-run self-registration: whichever workspace resolves from --workspace or CH_WORKSPACE_ID becomes the new device’s first link. Run it with neither set and the device self-registers unlinked to any workspace — see Managing your devices for linking a device after the fact.

Set CH_WORKSPACE_ID once in your shell profile so all commands target the right workspace without repeating the ID on every call:

export CH_WORKSPACE_ID=<your-workspace-id>

Find your workspace ID with ch workspace list or ch workspace show. To confirm which workspace the CLI is targeting:

ch workspace show

Managing workspaces in the web app

Creating groups and workspaces

The Dashboard (your account home, before entering any workspace) and every group landing page both have + New Group and + New Workspace buttons in the page header. Clicking either button opens a creation form where you fill in the name, optional description, and (for leaf workspaces) an optional parent group. The new item appears immediately.

• Use + New Group to create a group that will contain child workspaces.
• Use + New Workspace to create a leaf workspace — the kind where tasks, agents, and repositories actually live.

Switching to a workspace

On the Dashboard (your account home — see Accounts and the account home, above), the Workspaces section lists your root workspaces. Click a workspace name to enter it and make it the active workspace. Inside a group, the group landing page lists its direct children; click any name to navigate into it.

Editing workspace details

Open the workspace and go to Settings → General. The Name, Description, and URL rows are click-to-edit: click the value, type the new one, and click Save (or press Enter) to commit it; press Escape or click Cancel to discard your change and keep the current value.

The URL must be a valid http:// or https:// link — a good place for a project’s homepage, ticket tracker, or docs site. Once set, it appears as an external-link button next to the Dashboard title, so anyone in the workspace can jump straight to it.

Below that, on a leaf workspace, a Stall timeout field sets how many minutes a task can go untouched before CodeHerder flags it as stalled — from 1 to 10080 (7 days). Leave it blank to use the 60-minute server default; this section doesn’t appear on a group, since a group never holds tasks of its own. See Assigning and claiming work for what stalling means.

Only a workspace owner or admin can edit these details. From the CLI, ch workspace edit covers name, description, default repo, and the stall timeout — see Editing a workspace, above.

Moving a workspace

To move a workspace to a different parent (or promote it to root level), open the group it currently belongs to, go to Settings → General, scroll to the Manage workspaces section, and click Move in the row for the workspace you want to relocate. Choose the new parent group (or leave blank to promote to root) and confirm.

Archiving, restoring, and deleting a workspace

When a project wraps up, you can retire a workspace without losing the option to bring it back. All three lifecycle actions live in the web app under Settings → General, in the Danger zone section. There is no ch CLI command for archiving, restoring, or permanently deleting a workspace.

Archiving

Archiving hides the workspace from all views and removes it from navigation and lists. It is reversible — the workspace and all its data are preserved. Archiving is also a required step before you can permanently delete a workspace.

Who can archive: owners and admins.

To archive a workspace, open the workspace, go to Settings → General, scroll to the Danger zone, and click Archive.

Finding and restoring an archived workspace

Archived workspaces are hidden by default across all views. To find and restore one:

1. Navigate to the group that contains the archived workspace.
2. Go to Settings → General and scroll to the Manage workspaces section.
3. Tick Show archived to reveal archived child workspaces in the list.
4. Click the archived workspace to open it, go to Settings → General, scroll to the Danger zone, and click Restore.

Restoring brings the workspace back to active status and makes it visible in all views.

Who can restore: owners and admins.

Permanently deleting a workspace

Permanent deletion removes the workspace and all its data irreversibly. The Delete forever button is only enabled after the workspace has been archived.

Warning: Permanently deleting a workspace also permanently removes every workspace nested beneath it, along with all of their tasks and data. This cannot be undone.

To permanently delete a workspace:

1. Archive the workspace first (see above).
2. On Settings → General, scroll to the Danger zone. Type the exact workspace name into the confirmation field.
3. Click Delete forever.

Who can permanently delete: workspace owners only. Admins cannot permanently delete a workspace.

If you need to manage roles, see Members, teams, and roles.

---

For next steps, see Members, teams, and roles to invite people and manage roles within a workspace. Core concepts has the full object model. Writing tasks an agent can build covers task types and pipelines — workspace admins can customise these via Settings → Task types.