# Managing workspaces Source: https://codeherder.com/docs/workspaces/ How to create, edit, nest, and manage a CodeHerder workspace. 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](https://codeherder.com/docs/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](https://codeherder.com/docs/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](https://codeherder.com/docs/tracking-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 ""] [--parent ] ``` 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 ] [--cursor ] ``` 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 [] ``` `` 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 [] ``` `` accepts a name, slug, slug path, or full UUID — see [Referring to things on the command line](https://codeherder.com/docs/using-the-cli/#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 [] ``` For your account’s plan — usage against its limits, history retention, and the features it unlocks: ``` ch workspace plan [] ``` Since a plan is account-wide, this reports the same result no matter which workspace in the account you name. See [Plans and limits](https://codeherder.com/docs/plans-and-limits/) for what the output means. ## Editing a workspace ``` ch workspace edit [--name ] [--description ] [--default-repo | --clear-default-repo] [--stall-timeout | --clear-stall-timeout] ``` `` 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](https://codeherder.com/docs/repositories/) for how that choice is made and what it takes to set one. `--stall-timeout ` 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](https://codeherder.com/docs/assigning-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](https://codeherder.com/docs/microvm-runners/). ## Nesting and reparenting To nest an existing workspace under a new parent: ``` ch workspace set-parent ``` 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 --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](https://codeherder.com/docs/devices/#turning-a-device-off-for-one-workspace). - **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](https://codeherder.com/docs/memory/) 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](https://codeherder.com/docs/integrations/#inherited-connections). - **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](https://codeherder.com/docs/variables/). - **Stage library** — a custom stage defined in a group is usable by every descendant workspace’s workflows. See [The stage library](https://codeherder.com/docs/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 ` flag passed directly to the command — accepted on every workspace-scoped verb, and `` may be a name, slug, slug path, or full UUID. 2. The `CH_WORKSPACE_ID` environment variable. 3. A committed [project defaults file](https://codeherder.com/docs/project-config/) (`.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](https://codeherder.com/docs/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= ``` 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](https://codeherder.com/docs/assigning-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 ``` `` accepts a name, slug, slug path, or full UUID — see [Referring to things on the command line](https://codeherder.com/docs/using-the-cli/#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 ``` See [Listing archived records](https://codeherder.com/docs/using-the-cli/#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 ``` (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](https://codeherder.com/docs/members-and-teams/). --- For next steps, see [Members, teams, and roles](https://codeherder.com/docs/members-and-teams/) to invite people and manage roles within a workspace. [Core concepts](https://codeherder.com/docs/concepts/) has the full object model. [Writing tasks an agent can build](https://codeherder.com/docs/writing-tasks/) covers types and pipelines — workspace admins can customise these via **Settings → Workflows**. [Custom branding](https://codeherder.com/docs/branding/) covers setting your workspace’s own name on transactional email, on the Enterprise plan.