Account quotas
Quotas are per account. mat whoami and GET /v1/me show yours and what you use of them. A new account has a quota of zero until it subscribes or we enable it.
| Limit | Value | Details |
|---|---|---|
| Sandboxes | 50 | Every sandbox not deleted counts, paused and stopped ones included. |
| Sandbox memory | 200 GiB (204800 MiB) | The memory of every sandbox not deleted, running or paused. |
| Running at once | 10 | Sandboxes creating, running, resuming or pausing. Checked on every create and every resume, including a resume caused by exec, files or a connection. |
Rates and waiting
| Limit | Value | Details |
|---|---|---|
| Creates | 60 per account per minute | Forks count too. Every attempt counts, including retries with the same Idempotency-Key. |
| Waiting for room | Up to 1 minute | When no host has room, a create or resume waits for some before it answers 503. |
| Idempotency-Key | 1 to 128 visible ASCII characters |
Sandboxes
| Limit | Value | Details |
|---|---|---|
| Idle timeout | 1 to 1440 minutes | 10 by default. |
| Disk throughput | 100 MiB/s and 4000 operations/s per vCPU | With a burst of 1 GiB, so package installs and image pulls stay fast. |
| Network bandwidth | 100 Mbit/s each way per vCPU | With a burst of 256 MiB. |
Commands and files
| Limit | Value | Details |
|---|---|---|
| Command output kept | The last 1 MiB per command | Older output is dropped; a stream says from which byte it continues. |
| File transfer | One file, up to 1 GiB | The path is absolute, up to 4096 bytes. No directories. |
| Terminal size | 1 to 1000 columns and rows |
Network
| Limit | Value | Details |
|---|---|---|
| Allowed domains | 256 per sandbox | Under restricted, besides the essentials. |
| Outbound mail | Port 25 is blocked | Send mail through a provider on port 465 or 587. |
| Open connections | 1024 per sandbox | |
| New connections | 20 per second, bursts of 400 | A quarter of that for accounts without an active subscription. Far above what installs, git, model APIs and browsing need. |
| Failed destinations | 200 distinct within a minute | Looks like a port scan: the sandbox is paused and held for review. |
| Egress log | The last 1000 connections per sandbox | Kept in memory on the host; lost if the host agent restarts. |
Secrets
| Limit | Value | Details |
|---|---|---|
| Name | Up to 128 characters | Letters, digits and _, not starting with a digit. |
| Value | 1 to 8192 bytes of printable ASCII | |
| Domains per secret | 1 to 16 | |
| Secrets per sandbox | 64 |
Snapshots
| Limit | Value | Details |
|---|---|---|
| Snapshots per sandbox | 10 | Snapshots being taken count too. |
| Snapshot storage per account | 200 GiB by default for a subscribed account | Each snapshot counts its sandbox's disk plus memory: 12 GiB small, 24 GiB medium, 48 GiB large. `mat whoami` shows yours. |
| Host disk | Checked before each snapshot | A host refuses a snapshot it could not hold if the sandbox rewrote its whole disk; retry later. |
| Name | 1 to 64 characters | No control characters. |
Sign-in and connections
| Limit | Value | Details |
|---|---|---|
| Session | 7 days | Then sign in again. API keys do not expire; revoke them when you are done. |
| mat login code | 10 minutes | |
| Connect and preview tokens | Single use, 60 seconds | |
| API key label | Up to 64 printable characters |
Account quotas are the defaults for a subscribed account. Yours may differ; mat whoami is the authority.
Error codes
Every error body has a code and a message. The message names the limit or the reason.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_request | The request is malformed or a value is out of range. Unknown JSON fields are refused too. |
| 401 | unauthorized | Missing, invalid or expired credentials. The message is always: missing, invalid or expired credentials; sign in again. |
| 403 | forbidden | Signed in, but not allowed this way, such as an API key managing API keys. |
| 404 | not_found | No such sandbox, exec, secret, key or route in your account. |
| 409 | conflict | The sandbox is not in a state that allows this, e.g. deleting a sandbox while it is being created. |
| 429 | quota_exceeded | An account limit or the create rate limit. The message names the limit. |
| 503 | unavailable | No capacity right now, a host is busy or unreachable, or the sandbox reported it is out of room. Usually worth retrying shortly. |
| 500 | internal | Something failed on our side. The message is just internal error. |
Retrying
503 unavailableis usually worth retrying after a short wait: a host was busy, full or slow to answer.- When a host does not confirm a change, the message says to check the sandbox's status. We settle it in the background; read the sandbox before you retry.
- For
429 quota_exceeded, read the message. The create rate limit says how many seconds to wait; the other quotas need you to pause or delete a sandbox, or a higher quota. - Retry creates with the same
Idempotency-Key, so a retry returns the sandbox the first attempt made.
CLI exit codes
| Code | Meaning |
|---|---|
0 | Success. |
1 | The API refused the request, or could not be reached. The message says why. |
2 | Bad arguments or missing setup, such as not being signed in. |
N | mat exec, mat logs and mat shell exit with the remote command's own code, or 128 + the signal that ended it. |
130 | You detached from mat exec with a second Ctrl-C. The command keeps running. |