From 6c10cb0b4e268a39223d192956878a820d4db96e Mon Sep 17 00:00:00 2001 From: dcruzeneil2 <247271309+dcruzeneil2@users.noreply.github.com> Date: Thu, 27 Aug 2026 15:29:18 +0000 Subject: [PATCH 1/5] Document spending cap behavior --- docs.json | 1 + info/pricing.mdx | 2 + info/projects.mdx | 2 + info/spending-caps.mdx | 151 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 156 insertions(+) create mode 100644 info/spending-caps.mdx diff --git a/docs.json b/docs.json index 60e88ff..0dec9f8 100644 --- a/docs.json +++ b/docs.json @@ -274,6 +274,7 @@ "browsers/faq", "info/concepts", "info/pricing", + "info/spending-caps", "info/support", "info/unikernels", "info/zero-data-retention" diff --git a/info/pricing.mdx b/info/pricing.mdx index 7ee71cd..33db41e 100644 --- a/info/pricing.mdx +++ b/info/pricing.mdx @@ -4,6 +4,8 @@ title: "Pricing & Limits" With Kernel, you only pay for what you use and nothing more. You don't pay for idle time thanks to [Standby Mode](/browsers/standby), idle browsers in a browser pool incur no usage charges, and you're never charged for proxies. +Use [Spending Caps](/info/spending-caps) to warn at 80% of a monthly usage limit and pause new browser sessions and app invocations at 100%. You can set one cap across your organization or isolate individual workloads with project caps. + ## Pricing | Browser type | Price ($/sec) | diff --git a/info/projects.mdx b/info/projects.mdx index 46f9b85..22b61ac 100644 --- a/info/projects.mdx +++ b/info/projects.mdx @@ -317,6 +317,8 @@ A project's effective cap resolves in this order: A per-project cap never lets a project exceed your organization's concurrency limit. +Concurrency limits control how many browsers can run at once. To control monthly usage cost instead, see [Spending Caps](/info/spending-caps). + | Method | Path | Description | | --- | --- | --- | | `GET` | `/org/limits` | Get the org concurrency limit and the default per-project cap | diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx new file mode 100644 index 0000000..893ce98 --- /dev/null +++ b/info/spending-caps.mdx @@ -0,0 +1,151 @@ +--- +title: "Spending Caps" +description: "Choose a monthly spending guardrail for your organization, a project, or both" +--- + +A retry loop, traffic spike, or long-running agent can raise usage faster than you expect. Spending caps let you decide how much new usage KERNEL can admit each month before it pauses the affected workload. + +KERNEL sends a warning when usage reaches 80% of a cap, then pauses new browser sessions and app invocations at 100%. Already-running work continues, and you can still inspect resources, clean them up, or raise the cap. + + + Project spending caps are in limited preview. [Contact support](/info/support) if you don't see the project option on your billing page. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. + + +## Choose a cap + + + + Bound your organization's total out-of-pocket usage spend after monthly credits. When it is reached, new usage pauses across every project. + + Use this as the final guardrail for your KERNEL bill. + + + Bound gross usage for one project before organization credits. When it is reached, that project pauses while sibling projects continue. + + Use this to isolate teams, environments, customers, or experiments. + + + +For most multi-project production setups, use both: an organization cap for the total bill and lower project limits for workloads that need tighter control. + +| Behavior | Organization cap | Project cap | +| --- | --- | --- | +| Spend measured | Out-of-pocket usage after monthly credits | Gross usage before credits | +| Scope paused at 100% | Every project in the organization | Only the selected project | +| Best for | A final billing guardrail | Workload, team, or environment isolation | +| Quantity | One per organization | One per project | + +Subscription fees don't count toward either cap. Spending caps apply to usage charges. + +## How spend is counted + +### Organization caps + +An organization cap measures usage after KERNEL applies your included monthly credits: + +```text +out-of-pocket usage = gross usage - included monthly credits +``` + +For example, an organization with \$50 in monthly usage credits sets a \$100 organization cap: + +- KERNEL sends the 80% warning at \$130 in gross usage: \$50 in credits plus \$80 in out-of-pocket usage. +- KERNEL pauses new usage at \$150 in gross usage: \$50 in credits plus the \$100 cap. +- The plan's subscription fee remains separate. + +Choose an organization cap when your main requirement is a predictable maximum for monthly usage charges, regardless of which project creates the spend. + +### Project caps + +A project cap measures that project's gross usage. Organization credits aren't divided or assigned to individual projects. + +For example, a \$25 project cap warns at \$20 and pauses new usage for that project at \$25. Other projects can continue until they reach their own caps or the organization cap is reached. + +Requests without an explicit project resolve to your [default project](/info/projects#the-default-project) and count toward that project's cap. + +Choose project caps when one workload must not consume an open-ended share of the organization's budget. Common examples include staging, customer-specific automations, and experiments with uncertain retry behavior. + +## How enforcement works + + + + KERNEL evaluates each cap from the first day of the month at 00:00 utc. Organization and project usage accumulate independently. + + + KERNEL sends a warning email for the cap that entered the warning range. Existing and new work continue. + + + New browser sessions and app invocations return a `403` for the affected scope. An organization cap pauses every project; a project cap pauses only that project. + + + New work resumes when the next monthly period starts. An organization admin can also increase or remove the cap from the billing page. + + + +When a cap is reached: + +- Already-running browser sessions and app invocations continue until they end. +- Read and delete requests remain available, along with selected non-billable administrative operations such as managing projects, limits, and api keys. +- Browser pools can maintain idle capacity, but you can't acquire a new browser for a capped scope. +- Organization members can view cap status. Only organization admins can set, edit, or remove caps. + + + A spending cap is an admission guardrail, not a transactional hard ceiling. Usage is evaluated through billing events, and already-running work can continue adding usage after the threshold is reached. Leave headroom below any budget that must not be exceeded. + + +## Layer organization and project caps + +Organization and project caps are independent. KERNEL doesn't allocate the organization cap among projects, and project caps don't have to add up to the organization cap. + + + + KERNEL pauses new work for that project. Other projects continue. + + + KERNEL pauses new work across every project, even if their individual caps have room left. + + + The organization cap takes precedence because it applies to the full organization. + + + +If a project cap is higher than the organization cap plus monthly credits, the organization cap can trigger first. The dashboard warns you when you enter that configuration, but it still lets you save it because a later change to credits or the organization cap can change which threshold comes first. + +## Recommended setups + +### One production workload + +Set an organization cap above your normal monthly usage and below the point where an unexpected retry loop becomes expensive. Add a project cap only if you need a tighter boundary for a separate test or staging project. + +### Multiple teams or environments + +Set one organization cap for the total bill, then give staging, experiments, and each team their own project caps. A noisy project pauses without taking production down with it. + +### Customer-specific workloads + +Place each customer's resources in a [project](/info/projects), then set project caps according to the workload's expected usage. Keep an organization cap as the final boundary across all customers. + +### High-volume production + +Use a spending cap for cost and [concurrency limits](/info/pricing#concurrency-limits) for simultaneous capacity. A spending cap doesn't reserve throughput, and a concurrency limit doesn't bound monthly spend. + +## Set or update a cap + + + + Go to the [KERNEL billing page](https://dashboard.onkernel.com/billing) as an organization admin. + + + In **Spending Cap**, select **Organization** or **Project**. For a project cap, select the project you want to control. + + + Enter the usage amount in usd and save. If current month-to-date usage already exceeds a new or reduced cap, the scope can enter the reached state as soon as billing data finishes evaluating. + + + The card shows month-to-date progress and reached state. Increase, lower, or remove the cap at any time. + + + + + Set an organization spending cap or manage the project caps available to your organization. + From ab833825c683af7f525d11a24100711f42d07c34 Mon Sep 17 00:00:00 2001 From: dcruzeneil2 <247271309+dcruzeneil2@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:09:06 +0000 Subject: [PATCH 2/5] Reorganize spending cap guide --- info/spending-caps.mdx | 175 ++++++++++++++++++++--------------------- 1 file changed, 85 insertions(+), 90 deletions(-) diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx index 893ce98..6f7e554 100644 --- a/info/spending-caps.mdx +++ b/info/spending-caps.mdx @@ -3,149 +3,144 @@ title: "Spending Caps" description: "Choose a monthly spending guardrail for your organization, a project, or both" --- -A retry loop, traffic spike, or long-running agent can raise usage faster than you expect. Spending caps let you decide how much new usage KERNEL can admit each month before it pauses the affected workload. +A retry loop, traffic spike, or long-running agent can raise usage faster than you expect. Spending caps warn you before that usage reaches the amount you choose, then pause new work for the affected scope. -KERNEL sends a warning when usage reaches 80% of a cap, then pauses new browser sessions and app invocations at 100%. Already-running work continues, and you can still inspect resources, clean them up, or raise the cap. +If you only set one cap, start with an organization cap. It protects the total bill. Add project caps when a team, environment, customer, or experiment needs a tighter boundary. - - Project spending caps are in limited preview. [Contact support](/info/support) if you don't see the project option on your billing page. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. - - -## Choose a cap +## Which cap should you use? - Bound your organization's total out-of-pocket usage spend after monthly credits. When it is reached, new usage pauses across every project. + Counts out-of-pocket usage after monthly credits. At 100%, new usage pauses across every project. - Use this as the final guardrail for your KERNEL bill. + Use it as the final guardrail for your KERNEL bill. - Bound gross usage for one project before organization credits. When it is reached, that project pauses while sibling projects continue. + Counts one project's gross usage before organization credits. At 100%, only that project pauses. - Use this to isolate teams, environments, customers, or experiments. + Use it to isolate a workload, team, environment, or customer. -For most multi-project production setups, use both: an organization cap for the total bill and lower project limits for workloads that need tighter control. - -| Behavior | Organization cap | Project cap | -| --- | --- | --- | -| Spend measured | Out-of-pocket usage after monthly credits | Gross usage before credits | -| Scope paused at 100% | Every project in the organization | Only the selected project | -| Best for | A final billing guardrail | Workload, team, or environment isolation | -| Quantity | One per organization | One per project | +Use both for a multi-project production setup: one organization cap for the total bill, plus lower project caps where a single workload needs tighter control. Subscription fees don't count toward either cap. Spending caps apply to usage charges. -## How spend is counted - -### Organization caps - -An organization cap measures usage after KERNEL applies your included monthly credits: - -```text -out-of-pocket usage = gross usage - included monthly credits -``` +## Set a cap -For example, an organization with \$50 in monthly usage credits sets a \$100 organization cap: - -- KERNEL sends the 80% warning at \$130 in gross usage: \$50 in credits plus \$80 in out-of-pocket usage. -- KERNEL pauses new usage at \$150 in gross usage: \$50 in credits plus the \$100 cap. -- The plan's subscription fee remains separate. - -Choose an organization cap when your main requirement is a predictable maximum for monthly usage charges, regardless of which project creates the spend. - -### Project caps - -A project cap measures that project's gross usage. Organization credits aren't divided or assigned to individual projects. - -For example, a \$25 project cap warns at \$20 and pauses new usage for that project at \$25. Other projects can continue until they reach their own caps or the organization cap is reached. + + + Go to the [KERNEL billing page](https://dashboard.onkernel.com/billing) as an organization admin. + + + In **Spending Cap**, select **Organization** or **Project**. For a project cap, select the project you want to control. + + + Enter the usage amount in usd and save. The card shows month-to-date progress against the limit. + + -Requests without an explicit project resolve to your [default project](/info/projects#the-default-project) and count toward that project's cap. + + Project spending caps are in limited preview. [Contact support](/info/support) if you don't see the project option. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. + -Choose project caps when one workload must not consume an open-ended share of the organization's budget. Common examples include staging, customer-specific automations, and experiments with uncertain retry behavior. + + Set an organization spending cap or manage the project caps available to your organization. + -## How enforcement works +## What happens during the month - + KERNEL evaluates each cap from the first day of the month at 00:00 utc. Organization and project usage accumulate independently. - KERNEL sends a warning email for the cap that entered the warning range. Existing and new work continue. + KERNEL sends a warning email. Existing and new work continue. - New browser sessions and app invocations return a `403` for the affected scope. An organization cap pauses every project; a project cap pauses only that project. + New browser sessions and app invocations return a `403` for the affected scope. Running work continues until it ends. - New work resumes when the next monthly period starts. An organization admin can also increase or remove the cap from the billing page. + New work resumes when the next monthly period starts. An organization admin can also increase or remove the cap at any time. -When a cap is reached: - -- Already-running browser sessions and app invocations continue until they end. -- Read and delete requests remain available, along with selected non-billable administrative operations such as managing projects, limits, and api keys. -- Browser pools can maintain idle capacity, but you can't acquire a new browser for a capped scope. -- Organization members can view cap status. Only organization admins can set, edit, or remove caps. - - A spending cap is an admission guardrail, not a transactional hard ceiling. Usage is evaluated through billing events, and already-running work can continue adding usage after the threshold is reached. Leave headroom below any budget that must not be exceeded. + A spending cap is an admission guardrail, not a transactional hard ceiling. Billing events take time to evaluate, and already-running work can continue adding usage after the threshold is reached. Leave headroom below any budget that must not be exceeded. +## How spend is counted + + + + An organization cap measures usage after KERNEL applies your included monthly credits: + + ```text + out-of-pocket usage = gross usage - included monthly credits + ``` + + For example, an organization with \$50 in monthly usage credits sets a \$100 cap: + + - KERNEL sends the 80% warning at \$130 in gross usage: \$50 in credits plus \$80 in out-of-pocket usage. + - KERNEL pauses new usage at \$150 in gross usage: \$50 in credits plus the \$100 cap. + - The plan's subscription fee remains separate. + + Choose this cap when your main requirement is a predictable maximum for monthly usage charges, regardless of which project creates the spend. + + + A project cap measures that project's gross usage. Organization credits aren't divided or assigned to individual projects. + + For example, a \$25 project cap warns at \$20 and pauses new usage for that project at \$25. Other projects continue until they reach their own caps or the organization cap. + + Requests without an explicit project resolve to your [default project](/info/projects#the-default-project) and count toward that project's cap. + + Choose this cap when one workload must not consume an open-ended share of the organization's budget. + + + ## Layer organization and project caps -Organization and project caps are independent. KERNEL doesn't allocate the organization cap among projects, and project caps don't have to add up to the organization cap. +Organization and project caps are independent. KERNEL doesn't allocate the organization cap among projects, and project caps don't have to add up to it. KERNEL pauses new work for that project. Other projects continue. - KERNEL pauses new work across every project, even if their individual caps have room left. + KERNEL pauses new work across every project, even if individual project caps have room left. The organization cap takes precedence because it applies to the full organization. -If a project cap is higher than the organization cap plus monthly credits, the organization cap can trigger first. The dashboard warns you when you enter that configuration, but it still lets you save it because a later change to credits or the organization cap can change which threshold comes first. - -## Recommended setups +If a project cap is higher than the organization cap plus monthly credits, the organization cap can trigger first. The dashboard warns you about this configuration but still lets you save it because later changes to credits or either cap can change which threshold comes first. -### One production workload +## Common setups -Set an organization cap above your normal monthly usage and below the point where an unexpected retry loop becomes expensive. Add a project cap only if you need a tighter boundary for a separate test or staging project. +| Your setup | Recommended caps | +| --- | --- | +| One production workload | Start with an organization cap above normal monthly usage. | +| Production plus staging or experiments | Use an organization cap, then lower project caps for non-production work. | +| Multiple teams | Use an organization cap, then project caps to isolate each team's usage. | +| Customer-specific workloads | Put each customer in a [project](/info/projects), cap each project, and keep an organization cap as the final boundary. | -### Multiple teams or environments +## Operational details -Set one organization cap for the total bill, then give staging, experiments, and each team their own project caps. A noisy project pauses without taking production down with it. + + Already-running browser sessions and app invocations continue until they end. Read and delete requests remain available, along with selected non-billable administrative operations such as managing projects, limits, and api keys. -### Customer-specific workloads + Browser pools can maintain idle capacity, but you can't acquire a new browser for a capped scope. + -Place each customer's resources in a [project](/info/projects), then set project caps according to the workload's expected usage. Keep an organization cap as the final boundary across all customers. + + The scope can enter the reached state as soon as billing data finishes evaluating. Raise or remove the cap if you need to resume new work before the next monthly period. + -### High-volume production + + Organization members can view cap status. Only organization admins can set, edit, or remove caps. + -Use a spending cap for cost and [concurrency limits](/info/pricing#concurrency-limits) for simultaneous capacity. A spending cap doesn't reserve throughput, and a concurrency limit doesn't bound monthly spend. - -## Set or update a cap - - - - Go to the [KERNEL billing page](https://dashboard.onkernel.com/billing) as an organization admin. - - - In **Spending Cap**, select **Organization** or **Project**. For a project cap, select the project you want to control. - - - Enter the usage amount in usd and save. If current month-to-date usage already exceeds a new or reduced cap, the scope can enter the reached state as soon as billing data finishes evaluating. - - - The card shows month-to-date progress and reached state. Increase, lower, or remove the cap at any time. - - - - - Set an organization spending cap or manage the project caps available to your organization. - + + Spending caps bound monthly usage cost. [Concurrency limits](/info/pricing#concurrency-limits) bound simultaneous browser capacity. A spending cap doesn't reserve throughput, and a concurrency limit doesn't bound monthly spend. + From 14d820cfedf414f24648fb11edbdce4a4eae2dfa Mon Sep 17 00:00:00 2001 From: dcruzeneil2 <247271309+dcruzeneil2@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:21:44 +0000 Subject: [PATCH 3/5] Link project cap access to email --- info/spending-caps.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx index 6f7e554..1f973db 100644 --- a/info/spending-caps.mdx +++ b/info/spending-caps.mdx @@ -41,7 +41,7 @@ Subscription fees don't count toward either cap. Spending caps apply to usage ch - Project spending caps are in limited preview. [Contact support](/info/support) if you don't see the project option. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. + Project spending caps are in limited preview. [Email support@kernel.sh](mailto:support@kernel.sh?subject=Project%20spending%20cap%20access) to request access if you don't see the project option. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. From eb4fc5004587506375650143ad17c034b6db2b2c Mon Sep 17 00:00:00 2001 From: dcruzeneil2 <247271309+dcruzeneil2@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:34:13 +0000 Subject: [PATCH 4/5] Clarify spending cap availability --- info/spending-caps.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx index 1f973db..61c835b 100644 --- a/info/spending-caps.mdx +++ b/info/spending-caps.mdx @@ -41,7 +41,12 @@ Subscription fees don't count toward either cap. Spending caps apply to usage ch - Project spending caps are in limited preview. [Email support@kernel.sh](mailto:support@kernel.sh?subject=Project%20spending%20cap%20access) to request access if you don't see the project option. Organization caps are available to self-serve organizations with a payment method. Enterprise availability is limited. + Availability varies by scope: + + - **Organization caps:** Available to eligible self-serve organizations. Enterprise access is in limited preview. + - **Project caps:** In limited preview for all organizations. + + [Email support@kernel.sh](mailto:support@kernel.sh?subject=Spending%20cap%20preview%20access) to request preview access. From b639f53e9dcd64fa4252f802650cb57ab0ab2ea2 Mon Sep 17 00:00:00 2001 From: dcruzeneil2 <247271309+dcruzeneil2@users.noreply.github.com> Date: Thu, 27 Aug 2026 17:38:30 +0000 Subject: [PATCH 5/5] Match spending cap scope icons --- info/spending-caps.mdx | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/info/spending-caps.mdx b/info/spending-caps.mdx index 61c835b..89a3550 100644 --- a/info/spending-caps.mdx +++ b/info/spending-caps.mdx @@ -10,12 +10,33 @@ If you only set one cap, start with an organization cap. It protects the total b ## Which cap should you use? - + - +