Manage sandbox capacity
Adjust concurrent workload limits, interpret infrastructure measurements and investigate work waiting for a sandbox.
5 min read
Open Settings > Sandboxes when agent work or crawling cannot obtain an execution environment. The page separates your organization’s workload limits from the deployment’s actual infrastructure. Owners and Admins can change limits; Developers can read limits and aggregate capacity, without the private workspace list.
Identify the limit that matters
| Workload | Default | What uses a slot |
|---|---|---|
| Project agent sessions | 2 | An agent workspace starting or doing work. The agent reuses its workspace across tasks. |
| Workflow sessions | 2 | A workflow run’s sandbox, shared by its sandbox work. Concurrent runs use separate slots. |
| Render sessions | 2 | A temporary sandbox rendering pages during website crawling. |
These are concurrency limits, not a count of tasks or a spending budget. An agent can work on several tasks in its one workspace. Limits do not reserve infrastructure for the organization; all organizations share the deployment capacity.
Change a workload limit
- Check the workload’s Allocated count and the infrastructure measurements below it.
- Enter a whole number from 1 to 500 for the relevant limit. Total organization sessions recalculates the sum of all three fields.
- Keep that total within deployment capacity, then select Save in the header. Discard restores the saved values.
- Reopen the page to confirm the saved limits and inspect whether new work can obtain an allocation.
For example, the defaults total 6. If deployment capacity is 8, a total of 8 is valid and 9 is refused. The server rechecks capacity when saving, so another observation may differ from the one you first saw. Your organization's connected devices add the sandboxes they run to the ceiling: with one device that runs 4, the total may reach 12.
Lowering a limit affects future admissions; it does not interrupt active work. If infrastructure data is unavailable, reductions remain possible but increases need a fresh capacity observation. If the operator lowered capacity below your existing total, reduce your limits before saving again. If organization allocation data itself cannot load, the fields remain unavailable instead of showing editable defaults.
Read the infrastructure measurements
| Measurement | What it means |
|---|---|
| Deployment sandboxes | Running and starting environments across all organizations, compared with shared capacity. Kubernetes reports the namespace boundary. |
| Your organization's sandboxes | This organization’s running and starting environments, including idle ones kept for reuse. This is a count, not another organization limit. |
| Host CPU usage | Recently used and total CPU cores for the host, including its other services. |
| Host memory usage | Used and total host memory, including other services and allowing for reclaimable cache. |
Measurements refresh every 15 seconds; Refresh requests a new observation. Check its timestamp before interpreting it. CPU usage is the change between two samples; a first observation after a long gap takes about a second longer. Remote hosts may expose totals without usage. Kubernetes namespace access does not expose host measurements. Unavailable means unknown, not zero.
Explain an allocated or idle workspace
Owners and Admins can inspect Workspaces. A row identifies its agent or workflow run, runtime state, allocation state and running tasks. These states answer different questions: a container may remain running for reuse after it has released its organization slot. A project agent’s workspace stays listed while the agent is idle, as Stopped with Quota released, and leaves the list only when you destroy it; once the agent itself is deleted, the row reads Deleted agent until you destroy it. A workflow run’s workspace is reclaimed shortly after the run ends.
Spend adds the metered cost of finished turns. A turn still running is included when it ends. Temporary crawler environments appear in capacity counts even without a standing workspace row.
When deployment capacity is full, Tale may reclaim an unpinned idle environment whose allocation is released and which confirms it has no ongoing work. Its persistent workspace files remain for the next start. Busy, pinned or unresponsive environments are not candidates. If there is no safe candidate, new work must wait for capacity.
Manage an existing workspace
Owners and Admins can use a workspace’s row menu:
| Action | Effect |
|---|---|
| Stop task | Cancels all currently running operations in that workspace. Check the listed tasks first; one agent may have several. |
| Pin / Unpin | Keeps the workspace exempt from automatic idle and expiry cleanup, or restores normal cleanup. A pinned allocation can continue holding capacity. If a pinned workspace’s environment disappears, for example after a host restart, Tale starts it again with its workspace files, and the workspace stays pinned. |
| Destroy | Asks for confirmation, cancels running work and removes the sandbox and its workspace files. It unpins the workspace first. If destruction fails, the workspace remains listed, unpinned, and you can retry Destroy to finish removing it. The next agent start creates a fresh environment. |
Use stop when the current work should end but its files should remain. Before destruction, preserve outputs you still need and read the confirmation. Idle capacity reclamation preserves workspace files; explicit destruction does not.
Resolve a blocked start
Raise a workload limit only when its allocations are full and the new total fits shared capacity. If the deployment itself is full, increasing an organization limit cannot create infrastructure. To add capacity of your own, connect a device: new workspaces start on it. Otherwise, ask the operator to inspect capacity and host resources; a free container slot alone does not guarantee enough CPU or memory.
For a credential or model refusal, use AI providers. For a spending refusal, use Policies and limits. Self-hosted operators can inspect the deployment setting in the environment reference.