limits.md
Limits & errors
Every number the platform enforces, in one place, so you never have to hunt for a cap in a guide.
Runtime
| What | Limit |
|---|---|
| Wake from sleep | About a second, automatic on any message, trigger, or request |
| Chat reply budget (custom agents) | Reply within 30 seconds. If the response is lost after submission, Maritime reports uncertain delivery and does not resend the turn. Run longer work in the background and deliver it on the next message |
| exec (run a command) | 60s attached default, 3,600s detached default; null or omission selects the default. Positive finite timeouts can exceed 120s. Each separate output stream retains 262,144 characters plus a truncation marker. Results are temporary and can be lost on restart or agent replacement. Older agents support attached commands only, capped at 120s, with combined output and no execution ID. |
| File transfers | 100 MB per file; any file call wakes a sleeping agent |
Build & deploy
| What | Limit |
|---|---|
| Typical repo build + ship | 1 to 3 minutes (an idle builder cold-starts first, adding about a minute) |
| Silent build kill | A build that prints nothing for 5 minutes is killed |
| ZIP upload | 500 MB compressed, 2 GB unpacked |
| Template capture | Usually 1 to 10 minutes (snapshots the image and volume) |
| Registries | Pre-built images from public registries only; private code goes through repo builds |
Resources & plans
| What | Limit |
|---|---|
| Base allocation per machine | 2 GB RAM, 5 GB SSD |
| Self-serve ceilings per machine | 8 GB RAM, 100 GB SSD. Create and resize return 400 outside 512 MB to 8 GB RAM or 1 to 100 GB SSD |
| Sandbox and swarm sandbox sizes | Any size instead of the allocation above: vcpu 1 to 16, memoryMib 1,024 to 65,536 (whole GiB), diskGib 5 to 500. Presets: small 2 vCPU, 4 GB, 12 GB disk (default) · medium 4 vCPU, 8 GB, 50 GB · large 8 vCPU, 16 GB, 125 GB · xlarge 16 vCPU, 32 GB, 250 GB. A swarm sandbox runs at exactly the vcpus and memoryGb of its run, with 12 GB of disk |
| Sandbox idle time and time limit | idleMinutes 1 to 60, default 5 · timeLimitMinutes 5 to 1,440, default 1,440. It ends with its disk at whichever comes first |
| Machines awake at once | Starter and the free trial 5 · Growth 25 · Scale 60 · Dedicated 500 · Enterprise by contract. Agents and computers count alike; sleeping machines do not count. Waking an agent past the limit answers 429 awake_limit_reached with a 15 second retry hint; creating or waking a computer past it answers 429 concurrency with retryAfterS 15, and creating an agent past it answers 429 concurrency |
| Sandboxes per swarm run | Starter and the free trial 100 · Growth 1,000 · Scale 5,000 · Dedicated 10,000. A larger run answers 403 swarm_too_large; sandboxes running at once still count toward the awake limit |
| Free trial | Up to $20 of usage. At the cap machines are put to sleep and new starts answer 402 trial_cap_reached; agent boxes keep running and can wake for 3 more days |
| Windows desktops | Growth, Scale and Dedicated, once the plan is paid. Not on Starter or the free trial |
| Earlier seat plans | Accounts on an earlier seat plan keep its included-machine counts and limits |
Sizing details in Env vars & sizing, prices in Billing & plans.
Read your own limits
GET /api/v1/account/limits returns the numbers your account runs under now: your plan, included machines, the awake cap, how many machines are awake, the size ceilings, and the agent create and duplicate rate limits. On the current plans billingModel is usage, plan is starter (also during the free trial), growth, scale, or none with no plan (before the free trial starts, or after cancelling), and includedMachines is null, since there is no machine-count cap. Earlier seat plans report seats or wallet with their own plan names and caps. It reads the same code that enforces the limits, so an operator override shows here too. Any API key works. In the SDKs, call maritime.account.limits() (TypeScript) or client.account.limits() (Python). A null cap means no limit applies. Size your concurrency from maxAwakeMachines minus awakeMachines instead of a fixed number.
HTTP errors
| Status | Meaning |
|---|---|
401 |
Missing, invalid, revoked, or expired API key |
402 |
Billing refused the start: no free trial or plan yet (trial_required), the free trial's $20 is used (trial_cap_reached), a payment failed (payment_required), or the plan ended (plan_required). Also a seat-plan limit, or an add-on that needs a paid plan |
403 |
API key lacks the required scope for this endpoint, or this deployment has no host for the machine type (machine_unavailable), or a swarm run is larger than the plan allows (swarm_too_large) |
404 |
No such agent, or it belongs to a different account |
409 |
Conflict: agent name taken, deploy already in progress, or a file-move destination exists |
429 |
Rate limited (back off and retry), or the plan's awake limit is reached (awake_limit_reached or concurrency) |
503 |
No capacity right now, or the agent could not be woken yet; retry after Retry-After |
Error codes
Some error bodies carry a code next to detail. Branch on code, not on the detail text. A response with a retry hint also sets the Retry-After header and retryAfterSeconds in the body. Computers endpoints (/api/v1/computers) answer { "error", "message", "retryAfterS"} instead: the code is in error, and retryAfterS is the hint in seconds or null.
code |
Status | Meaning | Retry hint |
|---|---|---|---|
capacity_unavailable |
503 |
No host has room for the agent's memory right now | 30 s |
awake_limit_reached |
429 |
Waking an agent while the account has its plan's number of machines awake. The body includes awake and maxAwake |
15 s |
concurrency |
429 |
Creating a machine, or waking a computer, while the account has its plan's number of machines awake | 15 s for computers |
trial_required |
402 |
No free trial or plan yet. Start the free trial with a card on the Billing page | None |
trial_cap_reached |
402 |
The free trial's $20 of usage is used. Start the plan on the Billing page | None |
payment_required |
402 |
A payment failed or a charge is disputed. Pay the open invoice on the Billing page | None |
plan_required |
402 |
The plan has ended. Choose a plan on the Billing page | None |
machine_unavailable |
403 |
This deployment has no host for the machine type | None |
always_on_not_sold |
400 |
Always on was requested on a usage plan; machines run on demand | None |
wake_transient |
503 |
A sleeping agent could not be woken yet. It is still asleep and intact | 30 s |
insufficient_balance |
402 |
The wallet cannot cover the agent creation fee | None |
seat_limit |
402 |
The plan does not include this agent, size, or add-on | None |
A request for more than 8 GB RAM or 100 GB SSD, or less than 512 MB RAM or 1 GB SSD, returns 400 on create and on resize.
Failed deployments
A failed deployment has a failureKind. The agent.error webhook for a failed deploy carries the same value as data.failure_kind.
failureKind |
Meaning | What to do |
|---|---|---|
build |
A step in your source's build failed, for example a Dockerfile RUN |
Fix the source, then deploy again |
build_infrastructure |
Maritime's build system failed before your build could finish | Deploy again. Report it if it repeats |
deploy |
The image exists, but the agent did not start | Read the deploy log and the agent logs |