Plans and limits

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 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. 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 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 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 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.
• 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 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.
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 and Customising a task’s workflow.
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.
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.
Spend caps	budgets_spend_caps	Pro	Setting the agent daily spend cap and the default task spend cap. See 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.
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).
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).
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.
Self-hosted deployment	self_host	Enterprise	Downloading a server release to run CodeHerder on your own infrastructure. See Self-hosted deployment.

The Entitlements line in ch workspace plan’s output (see 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 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 for how these caps work and what happens when one is reached.

Related guides

• Spend limits — cap per-agent daily and per-task total model spend
• Understanding costs — how spend is tracked and how to view it
• Managing your devices — register and manage devices, which count toward your plan’s device limit
• Members, teams, and roles — invite people, who count toward your plan’s member limit
• Connecting repositories — register repositories, which count toward your plan’s project limit
• Managing workspaces — how workspaces and groups nest under an account
• Capabilities — capability labels, and which one is plan-gated
• Customising workflows — create and edit your workspace’s workflows
• Customising a task’s workflow — give one task its own pipeline, which needs the same plan as editing a workflow
• Webhooks — subscribe to workspace events
• Using the ch CLI — the CLI conventions used throughout this guide
• Single sign-on (SAML) — connect your own identity provider, on the Enterprise plan
• Custom branding — set your own product name, wordmark, and colours, on the Enterprise plan
• Self-hosted deployment — download and run a CodeHerder server release, on the Enterprise plan