Managing workspaces

A workspace is the top-level container for a team or project. Everything in CodeHerder — tasks, members, agents, repositories, and the wiki — 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 the wiki 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" [--kind workspace|group] [--description "<text>"] [--parent <parentId>]

The workspace is created immediately. The caller automatically becomes its owner. --kind defaults to workspace (a leaf); pass --kind group to create a group instead:

ch workspace create --name "Platform" --kind group

Omit --parent to create a root workspace. On a self-hosted server only an instance operator can do this; anyone else gets a 403. Pass --parent with the ID of an existing group workspace to nest the new one beneath it (unlike most workspace arguments, --parent doesn’t accept a name or slug — it takes an ID only):

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

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

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

Listing workspaces

ch workspace list [--active|--all|--archived] [--limit <n>] [--cursor <token>]

This prints every workspace you can access — the ones you’re a member of, plus every workspace nested beneath them — with its ID, name, path, kind, status, parent ID (if nested), and root ID. --active (the default) narrows to non-archived rows; --all includes archived rows; --archived shows archived rows only. The list is paged — pass --limit to change the page size and --cursor to fetch the next page.

To see the full tree rooted at a workspace:

ch workspace tree [<ref>]

<ref> accepts a name, slug, slug path, or full UUID; omit it to default to your active workspace. The output is an ASCII tree of the workspace and all its descendants, with a [group] tag marking each group row.

Inspecting a workspace

ch workspace show [<ref>]

<ref> accepts a name, slug, slug path, or full UUID — see Referring to things on the command line. Omit it to inspect the currently active workspace.

show prints the workspace’s ID, name, path, status, kind, description, parent, and root, plus the default repo and any stall-timeout override when they’re set.

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 [<ref>]

For your account’s plan — usage against its limits, history retention, and the features it unlocks:

ch workspace plan [<ref>]

Since a plan is account-wide, this reports the same result no matter which workspace in the account you name. See Plans and limits for what the output means.

Editing a workspace

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

<ref> is required, and accepts a name, slug, slug path, or full UUID. 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 "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. ch runner configure and the rest of ch workspace edit’s microVM-runner flags cover automatic AWS runners — see MicroVM runners.

Nesting and reparenting

To nest an existing workspace under a new parent:

ch workspace set-parent <childRef> <parentRef>

Both accept a name, slug, slug path, or full UUID. 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 <childRef> --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. A workspace can turn an inherited device off for itself.
• Wiki — confirmed pages written in a group are readable from any descendant workspace, and — unlike the other resource types on this list — a page owned by a group can also be edited from a descendant that inherits it; see Workspace wiki for the full picture.
• Workflows — workflow schemas defined in a group (via Settings → Workflows) 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.
• Integrations — a connection a group owns is usable by every descendant workspace; a descendant can configure its own instead, which then takes over from the inherited one. See Integrations.
• Variables — a key/value pair set on a group merges into every descendant workspace’s own map; a descendant can override a single key without touching the rest. See Variables.
• Stage library — a custom stage defined in a group is usable by every descendant workspace’s workflows. See The stage library.

In the web app, inherited resources appear in each descendant workspace’s lists with an inherited chip. Other than editing a wiki page (see above), 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 <ref> flag passed directly to the command — accepted on every workspace-scoped verb, and <ref> may be a name, slug, slug path, or full UUID.
2. The CH_WORKSPACE_ID environment variable.
3. A committed project defaults file (.codeherder.env) — the lowest tier, used only when neither of the above is set.

ch device-server resolves its first-run self-registration from --workspace or CH_WORKSPACE_ID only, never from a project defaults file — whichever of those two names a workspace 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 an optional parent — both forms offer the same parent picker, narrowed to groups, since only a group can hold children. 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 to commit it. For Name and URL you can also press Enter. Description takes several lines, so Enter adds a new line there; use Save. 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

On a group, Settings → General has a Manage workspaces section listing every workspace and group nested under it. Filter it with the Live / Archived / All picker beside the table. To move a workspace to a different parent (or promote it to root level), 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 are available both in the web app, under Settings → General in the Danger zone section, and from the ch CLI.

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.

Web app: open the workspace, go to Settings → General, scroll to the Danger zone, and click Archive.

CLI:

ch workspace archive <ref>

<ref> accepts a name, slug, slug path, or full UUID — see Referring to things on the command line. Archiving is idempotent: archiving an already-archived workspace is a no-op, not an error.

Finding and restoring an archived workspace

Archived workspaces are hidden by default across all views.

Web app: navigate to the group that contains the archived workspace, go to Settings → General, scroll to Manage workspaces, pick Archived (or All) from the Live / Archived / All picker to reveal it in the list, then open it, go to Settings → General, scroll to the Danger zone, and click Restore.

CLI: first find it — its STATUS column reads archived:

ch workspace list --archived

Then restore it by name, slug, slug path, or id:

ch workspace restore <ref>

See Listing archived records for how the --archived flag works across CodeHerder.

Restoring brings the workspace back to active status and makes it visible in all views again. It’s also idempotent — restoring an already-active workspace is a no-op.

Who can restore: owners and admins.

Permanently deleting a workspace

Permanent deletion removes the workspace and all its data irreversibly.

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.

Web app: the Delete forever button, on the same Danger zone panel, is only enabled after the workspace has been archived. Archive the workspace first (see above), then type the exact workspace name into the confirmation field and click Delete forever.

CLI:

ch workspace delete <ref>

(alias rm.) The CLI has no separate --yes prompt or typed-name confirmation: the archive-first step is the confirmation gate. ch workspace delete refuses to run until the workspace is already archived, so archiving it first also doubles as your chance to make sure it’s the right one. It also refuses an agent’s own session credential — only a signed-in person can permanently delete a workspace this way, not a coding session running as one.

Who can permanently delete: workspace owners only, on both surfaces. 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 types and pipelines — workspace admins can customise these via Settings → Workflows. Custom branding covers setting your workspace’s own name on transactional email, on the Enterprise plan.