# Plans and limits Source: https://codeherder.com/docs/plans-and-limits/ What your plan covers, with resource limits, usage meters, unlocked features, history retention, and how the Plan page and over-limit prompts work. Every account is on a plan. Your plan sets how much of CodeHerder you can use at once — how many devices, members, and projects you can have, how many agents can run concurrently, how long your history sticks around, and which features are turned on. ## Your plan is account-wide A plan attaches to your whole account, not to an individual workspace. If your account contains several workspaces or nested groups, they all share the same plan, and usage is counted across all of them together — adding a device in one workspace counts toward the same account-wide device limit as a device added in another. ## Finding your plan Open **Settings → Plan**. It’s visible only to people with access to your account’s top-level workspace — the same account plan no matter which of that workspace’s descendants you have open, since there’s only one plan per account. If your own access starts lower down the tree, you won’t see this page. See [Managing workspaces](https://codeherder.com/docs/workspaces/) for how workspaces and groups nest under an account. The **Plan & usage** section shows: - **Account** — the account this plan and these counts belong to. - **Plan tier** — your plan’s name. - **Deployment edition** — which build of CodeHerder this installation runs. On the hosted service this isn’t something you manage; it matters if your organisation runs a self-hosted deployment instead. - A licence line, shown only on a deployment that holds one (self-hosted, licensed deployments). It names the licensee, the expiry date, and the licence’s state, with the days left. It shows a warning when 30 days or fewer remain. See [Self-hosted licence expiry and renewal](https://codeherder.com/docs/self-host-licence/). The hosted service and unlicensed self-hosted deployments don’t show this line at all. - **Usage meters** — Concurrent agents, Devices, Members, and Repositories, each shown as how much you’re using out of your plan’s limit (or “Unlimited” if your plan doesn’t cap that resource). A meter that’s reached its limit is highlighted. See [What each limit counts](https://codeherder.com/docs/plans-and-limits/#what-each-limit-counts) below for exactly what’s being measured. - **History retention** — the window of task and cost history your plan includes (or “Full” if your plan doesn’t limit it). On a plan with a limited window, don’t expect history to vanish the moment that window is crossed — treat the number as what your plan includes, not a precise deletion date. - **Features included** — the capabilities your plan unlocks; see [What your plan unlocks](https://codeherder.com/docs/plans-and-limits/#what-your-plan-unlocks) below. - A **Contact sales to upgrade** link. It shows only when a higher plan is available — a fully unlimited account on the top plan tier never sees it. An **Overridden** badge on the **Plan & usage** heading means your account’s limits have been customised — either limits arranged with us, or a spend cap you’ve set yourself. It can stay on even after you clear your own spend caps back to unlimited. The numbers shown are the ones that apply to you, not your plan’s usual defaults. An enterprise licence on its own doesn’t set this badge. ## Check your plan from the CLI `ch workspace plan` prints the same information as the Plan page: your account, plan, edition, licence, usage against every limit, history retention, override state, the feature keys your plan has unlocked, and whether an upgrade is available. ``` $ ch workspace plan Account: Acme (acme) Plan: Enterprise (enterprise) Edition: community Licence: none Usage: concurrent agents 11 / unlimited devices 7 / unlimited members 2 / unlimited repositories 2 / unlimited History retention: full Overridden: false Over limit: false (concurrentAgents=false devices=false members=false projects=false) Entitlements: branding, budgets_spend_caps, capability_routing, cost_dashboards, rest_api_cli, scim, self_host, sso_saml, webhooks, workflow_rigor Upgrade: none available ``` The `Over limit` line names the repositories meter `projects`, an older name for the same thing kept there for compatibility. `Upgrade` names the next plan tier when one is available, or reads “none available” on your account’s top plan tier. Since a plan is account-wide (see above), this always reports your account’s plan — no matter which workspace you’re scoped to when you run it. Add `--json` for the same data as one JSON object; see [JSON output and scripting](https://codeherder.com/docs/using-the-cli/#json-output-and-scripting) for the shared conventions. ## What each limit counts - **Concurrent agents** — harness sessions running right now, pooled across your whole account’s workspaces and groups together. At the limit, nothing fails: new work simply waits and starts as soon as a running session frees up capacity. A device’s own capacity can also throttle how many sessions actually run at once — see [Managing your devices](https://codeherder.com/docs/devices/). - **Devices** — registered, non-archived devices granted to your account, counted once even if you’ve shared one across several workspaces. - **Members** — every person whose home workspace is in your account, including anyone disabled or archived. Someone whose home is in another account but who has been granted access to yours doesn’t use a seat here, and agents never count toward this limit. - **Repositories** — repositories registered in your account that aren’t archived. Archiving a repository frees up a slot. ## What happens at a limit If you try to add a device, a member, or a repository beyond your plan’s limit, CodeHerder blocks the addition with “You’ve hit your plan’s limit. Upgrade your plan or contact sales to raise it.” Concurrent agents work differently: your plan caps how many can run at once, but hitting that cap doesn’t fail anything — tasks simply wait to be picked up until a running session frees up capacity. If a plan change ever leaves your account over one of its new limits — for example, after a downgrade — a **Plan limit exceeded** banner appears on the Plan page, for any meter including concurrent agents. While it’s showing, new additions of the over-limit resource stay blocked until your account is back within the limit; nothing existing is deleted. Try a plan-gated feature (see [What your plan unlocks](https://codeherder.com/docs/plans-and-limits/#what-your-plan-unlocks) below) without the plan it needs, and CodeHerder shows an upgrade prompt instead — one line naming the feature and the plan tier that includes it, next to a **Contact sales to upgrade** link, for example “Webhooks — available on the Starter plan.” ## What your plan unlocks A handful of capabilities need a specific plan. Try to use one without it, and CodeHerder blocks the action and shows the upgrade prompt described above. | Feature | Feature key | Starts on | What it affects | | --- | --- | --- | --- | | Capability routing | `capability_routing` | Starter | Requiring specific capabilities on a task, and the capabilities an agent’s launch config offers. If you never set a required capability, this never comes up — every task and agent works the same on every plan. See [Capabilities](https://codeherder.com/docs/capabilities/). | | Custom workflows | `workflow_rigor` | Starter | Creating, editing, or restoring a version of one of your workspace’s workflows; going back to a workflow’s built-in version; migrating a workflow’s stages; creating, editing, or deleting a stage in your stage library; setting a per-task workflow override by hand. Viewing workflows is open on every plan. So are submitting a proposal, disabling or deleting a workflow, and clearing a per-task override. See [Customising workflows](https://codeherder.com/docs/task-types/) and [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/). | | Cost dashboards | `cost_dashboards` | Starter | Workspace-wide cost views — the Costs page and `ch costs workspace` and its related workspace reports. Your own costs and an agent’s costs stay visible on every plan; a single task’s cost (`ch costs task`) does too. `ch task show` ’s own cost line is the exception: it reads that same gated view, so it can disappear on a plan without this feature. See [Understanding costs](https://codeherder.com/docs/costs/). | | Webhooks | `webhooks` | Starter | Creating a new webhook subscription. Listing, editing, deleting, and testing an existing one stay open on every plan — an existing subscription keeps working even if you never upgrade. See [Webhooks](https://codeherder.com/docs/webhooks/). | | Spend caps | `budgets_spend_caps` | Pro | Setting the agent daily spend cap and the default task spend cap. See [Spend limits](https://codeherder.com/docs/spend-limits/). | | API keys for people | `rest_api_cli` | Pro | Minting an API key for a person. Signing in with your browser is unaffected, and agents keep running regardless of plan. See [Members, teams, and roles](https://codeherder.com/docs/members-and-teams/). | | Single sign-on (SAML) | `sso_saml` | Enterprise | Connecting your own SAML identity provider so people sign in to CodeHerder through it. See [Single sign-on (SAML)](https://codeherder.com/docs/sso/). | | SCIM user provisioning | `scim` | Enterprise | Provisioning and de-provisioning user accounts automatically through your identity provider, using the SCIM standard. See [Automatic user provisioning (SCIM)](https://codeherder.com/docs/scim/). | | Custom branding | `branding` | Enterprise | Saving a brand profile for a workspace or group — its own product name, wordmark, colours, and the sender name on its transactional email — and uploading the images that go with it. Reading a profile isn’t plan-gated. See [Custom branding](https://codeherder.com/docs/branding/). | | Self-hosted deployment | `self_host` | Enterprise | Downloading a server release to run CodeHerder on your own infrastructure. See [Self-hosted deployment](https://codeherder.com/docs/self-hosting/). | The **Entitlements** line in `ch workspace plan` ’s output (see [Check your plan from the CLI](https://codeherder.com/docs/plans-and-limits/#check-your-plan-from-the-cli) above) lists your plan’s unlocked feature keys from this table. ## Changing your plan There’s no self-serve plan switch in the app today. To upgrade, use the Plan page’s own **Contact sales to upgrade** link, when it’s showing (see [Finding your plan](https://codeherder.com/docs/plans-and-limits/#finding-your-plan) above), or the same link on any upgrade prompt you hit. ## Spend caps The Plan page also has a **Spend caps** section, capping how much an agent spends per day and how much an individual task can spend by default. Setting these caps needs the Pro plan and the owner or admin role on your account’s top-level workspace. Without that role, the section reads read-only; without the plan, it shows the “Budget spend caps — available on the Pro plan.” prompt regardless of your role. See [Spend limits](https://codeherder.com/docs/spend-limits/) for how these caps work and what happens when one is reached. ## Related guides - [Spend limits](https://codeherder.com/docs/spend-limits/) — cap per-agent daily and per-task total model spend - [Understanding costs](https://codeherder.com/docs/costs/) — how spend is tracked and how to view it - [Managing your devices](https://codeherder.com/docs/devices/) — register and manage devices, which count toward your plan’s device limit - [Members, teams, and roles](https://codeherder.com/docs/members-and-teams/) — invite people, who count toward your plan’s member limit - [Connecting repositories](https://codeherder.com/docs/repositories/) — register repositories, which count toward your plan’s project limit - [Managing workspaces](https://codeherder.com/docs/workspaces/) — how workspaces and groups nest under an account - [Capabilities](https://codeherder.com/docs/capabilities/) — capability labels, and which one is plan-gated - [Customising workflows](https://codeherder.com/docs/task-types/) — create and edit your workspace’s workflows - [Customising a task’s workflow](https://codeherder.com/docs/workflow-overrides/) — give one task its own pipeline, which needs the same plan as editing a workflow - [Webhooks](https://codeherder.com/docs/webhooks/) — subscribe to workspace events - [Using the ch CLI](https://codeherder.com/docs/using-the-cli/) — the CLI conventions used throughout this guide - [Single sign-on (SAML)](https://codeherder.com/docs/sso/) — connect your own identity provider, on the Enterprise plan - [Custom branding](https://codeherder.com/docs/branding/) — set your own product name, wordmark, and colours, on the Enterprise plan - [Self-hosted deployment](https://codeherder.com/docs/self-hosting/) — download and run a CodeHerder server release, on the Enterprise plan