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

# Mosaic sandboxes

> Run CostGraph workflows and CI jobs in Mosaic sandboxes: the key to create, its permissions, and its limits

Mosaic Sandbox is a Firecracker/KVM execution API for AI agents that runs Linux sandboxes with exec, files, previews, snapshots and forks.

The following table shows what CostGraph runs on this provider.

| Workflows | CI runners | Connect with |
| - | - | - |
| Yes | Yes | Integrations or your own dispatcher |

## Connect

Connect Mosaic on Integrations, and CostGraph starts sandboxes in your Mosaic account. You don't run anything yourself.

1. In CostGraph, go to **Integrations > Sandbox > Mosaic**.

2. Enter these fields:

   * **API key** (`MOSAIC_API_TOKEN`, required): A Mosaic organization API key.

3. Click **Connect**.

For CI runners, CostGraph sets CPU and memory.

### Your own dispatcher

To keep the key out of CostGraph or reach a private network, run your own dispatcher instead.
Set `provider` to `mosaic` and the preceding fields as environment variables, as described in [Run your own dispatcher](https://docs.costgraph.ai/costgraph/workflows/managed-sandboxes.md#run-your-own-dispatcher).

## Key and permissions

MOSAIC\_API\_TOKEN is an organization-scoped Mosaic API key (msk\_live\_...). Get it from "mos login" or signup, then mint a narrower one with POST /v1/api-keys and a scopes array.

Documented: sandboxes:write (create POST /v1/sandboxes, delete DELETE /v1/sandboxes/\{id}), sandboxes:exec (POST /v1/sandboxes/\{id}/exec) and sandboxes:read (list GET /v1/sandboxes). A self-serve signup key also carries billing, audit and identity scopes, so mint a CI key with only these three.

Sources: [sandbox.mosaicos.com: llms.txt](https://sandbox.mosaicos.com/llms.txt), [sandbox.mosaicos.com: keys](https://sandbox.mosaicos.com/keys/), [sandbox.mosaicos.com: openapi.json](https://sandbox.mosaicos.com/openapi.json), [sandbox.mosaicos.com: docs](https://sandbox.mosaicos.com/docs/).

## Limits

* Synchronous exec timeout\_ms defaults to 30000 and may not exceed 900000 (15 min). Streaming exec has no ceiling. ([source](https://sandbox.mosaicos.com/llms.txt))
* Automatic hibernation begins after three quiet seconds. A sandbox has an inactivity deadline (ttl\_seconds; 0 removes it); with persist:true it is archived at the deadline instead of destroyed. ([source](https://sandbox.mosaicos.com/llms.txt))
* Self-serve shapes go up to 16 vCPU/32768 MiB. Every template serves 1, 2 and 4 vCPU; 8 and 16 vCPU need base or a custom environment. ([source](https://sandbox.mosaicos.com/llms.txt))
* Regions: Silicon Valley and Northern Virginia, no EU region. Sandboxes are Linux only; Windows is a prototype. ([source](https://sandbox.mosaicos.com/llms.txt))

## Related

* [Supported sandbox providers](https://docs.costgraph.ai/costgraph/workflows/sandbox-providers.md)
* [Run workflows on a managed sandbox provider](https://docs.costgraph.ai/costgraph/workflows/managed-sandboxes.md)
* [Run CI jobs in sandboxes](https://docs.costgraph.ai/costgraph/autopilot/ci-sandboxes.md)


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