> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Sandbox quotas and limits

> Learn which limit each sandbox quota governs, how to check current values and usage in the console or the SDK, and how to request a higher limit for a team.

Agent Sandbox applies quota limits to a team. The quotas cap how many sandboxes run at once, how long a sandbox can live, and the vCPU, memory and local storage a single sandbox can have. The current values are on the [**AGENT SANDBOX › Quotas & Limits**](https://console.ppio.ai/sandbox/quotas) page of the console.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Quota items

> [card] Maximum Concurrent Sandboxes
>
> The number of sandboxes that run at the same time.

> [card] Sandbox Maximum Lifetime
>
> The maximum timeout one sandbox can have; [long-running mode](https://docs.ppio.ai/sandbox/lifecycle.md#long-running-sandboxes) lifts the cap.

> [card] Maximum vCPU per Sandbox
>
> The vCPU cores a single sandbox can use.

> [card] Maximum Memory per Sandbox
>
> The memory a single sandbox can have.

> [card] Maximum Local Storage per Sandbox
>
> The runtime storage available to a single sandbox.

Total vCPU and memory in use across running sandboxes are also limited (`concurrentVcpu`, `concurrentRamMb`).

## Tiers

The quotas depend on the tier of the team.

> [card] Free
>
> The default tier for a new team.

> [card] Paid
>
> Available after adding balance or enabling a credit line.

> [card] Enterprise
>
> For teams that need custom limits and dedicated support.

## Configuration rules

CPU and memory are set when the template is built, and the configuration must meet these requirements:

* vCPU must not exceed the maximum vCPU of the tier.
* vCPU must be a whole number.
* Memory must not exceed the maximum memory of the tier.
* Memory is configured in fixed increments, within a range of memory allowed per vCPU.
* The final configuration is set by both the tier maximums and the allowed memory per vCPU.

> [!WARNING]
>
> If the requested resource configuration exceeds the quota of the tier, the request fails. If a region has no available capacity, sandbox creation can fail even when the team quota is not used up.

> [!TIP]
>
> Choose CPU and memory for the workload to avoid running out of memory or using resources unnecessarily.

## Check limits and request an increase

**1. Read the current limits**

Open the [**AGENT SANDBOX › Quotas & Limits**](https://console.ppio.ai/sandbox/quotas) page of the console. Each quota appears as a row with its **Current Limit**.

**2. Request a higher limit**

In the row to raise, select **Increase Limit**.
\[!NOTE] The control appears only for a team member with permission to change quotas, and only on rows that can be adjusted; the other rows show a dash in the **Actions** column.

**3. Submit the request**

In the **Request Rate Limit Increase** dialog, enter the requested limit, a reason and a contact email, then select **Submit**.

> [!NOTE]
>
> Higher limits can also be requested from PPIO support. Enterprise quotas can be customized.

## Query the current quota with the SDK

The SDK returns the limits that apply to the team and the resources in use. Run it before launching a large batch of sandboxes, or when a create call fails on quota.

```python Python theme={null}
from ppio_sandbox.core import Sandbox

quota = Sandbox.get_quota()

print('Quota limit:', quota.limit)  # concurrent_instances, concurrent_vcpu, concurrent_ram_mb, ...
print('Current usage:', quota.usage)
```

```javascript Node.js theme={null}
import { Sandbox } from 'ppio-sandbox'

const quota = await Sandbox.getQuota()

console.log('Quota limit:', quota.limit) // concurrentInstances, concurrentVcpu, concurrentRamMb, ...
console.log('Current usage:', quota.usage)
```

### Quota response fields

The quota response includes `limit` and `usage` objects.

**limit** `object`

Limits that apply to the team.

**properties**

**concurrentInstances** `number`

Maximum number of sandboxes that can run concurrently.

**concurrentVcpu** `number`

Maximum total vCPU cores that can be used concurrently.

**concurrentRamMb** `number`

Maximum total memory that can be used concurrently, in MiB.

**maxLengthHours** `number`

Maximum lifetime for a single sandbox, in hours.

**diskMb** `number`

Available runtime storage for a single sandbox, in MB.

**maxVcpu** `number`

Maximum vCPU cores for a single sandbox. Applies after the template is built.

**maxRamMb** `number`

Maximum memory for a single sandbox, in MB. Applies after the template is built.

**usage** `object`

Resources currently in use.

**properties**

**concurrentInstances** `number`

Current number of running sandboxes.

**concurrentVcpu** `number`

Current total vCPU cores in use.

**concurrentRamMb** `number`

Current total memory in use, in MB.

`usage.concurrent_instances` (Python) / `usage.concurrentInstances` (Node.js) shows how many sandboxes currently count toward the concurrency limit.

> [!NOTE]
>
> Quota usage is intended for capacity planning and troubleshooting. Usage data can arrive with a short delay that depends on the backend reporting path.


## Related topics

- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)
- [Manage sandboxes in the PPIO console](https://docs.ppio.ai/sandbox/console.md)
- [Pause and resume a sandbox](https://docs.ppio.ai/sandbox/pause-resume.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.