Containers
Create with {"catalogId":"node","size":"medium"}. All plans offer lite, small, medium, large, and xl; Lite is the default. Size also participates in creation idempotency. Read compute allowances and deadlines before launching.
All browser sessions and API keys for an account share the same containers, concurrency, monthly compute-unit hours, and monthly start allowance. Base URL: https://api.mainbrella.com.
| Request | Behavior |
|---|---|
GET /containers | Returns containers, active access, plan, limits, usage, and the deployed image catalog. Reading status does not renew idle time. |
POST /containers | Reserves a start and launches a container. An omitted body selects the default Node image. Optional JSON selects catalogId or an owned, ready imageId. |
DELETE /containers?id=…&createdAt=… | Stops only the selected container generation. Stopping does not refund a start. |
Create safely
Send a unique Idempotency-Key header for each new launch. Repeating the same body and key resolves to the same reservation for 24 hours. Preserve the key until the response is reconciled.
POST /containers
Authorization: Bearer mb_<your-key>
Content-Type: application/json
Idempotency-Key: <unique-operation-key>
{"catalogId":"node"}
With an idempotency key, the response includes creation. Use its containerId and createdAt, matched to a running entry in containers, rather than selecting the first container in the list. A reservation can still be starting; repeat the same POST to reconcile it.
Keep the generation
A slot ID can be reused after a stop. The exact returned createdAt identifies that instance. Execution and file requests require it; supply it when stopping or issuing SSH access as well. URL-encode query values with your language's URL utilities.
Lifecycle
Containers end at their plan's hard deadline, the paid period recognized at creation, or their idle timeout. Renewals and upgrades do not extend existing sessions. Commands and terminal activity renew idle time only. Use Stop and save when filesystem stop/resume is available to preserve files through an explicit stop. Delete permanently removes the machine and its saved stop state. Automatic shutdown or an unexpected runtime restart can still lose changes made since the last save.
Check allowance before launching. Failed starts count toward monthly usage; requests rejected at concurrency capacity do not.
Saved workspaces
Save a running container’s filesystem from the dashboard’s Save control, optionally stopping it after save. Restore a saved workspace into a fresh container with its saved image, machine size, and internet policy. Restore consumes one normal start; it preserves files, permissions, symlinks, and timestamps, but not running processes or memory.
For API integrations, check capabilities.persistence.snapshots, then send POST /workspaces with {id, createdAt, name, stop?} and a persisted Idempotency-Key. Restore with POST /containers and {workspaceId} using a new creation key. Keep both keys to reconcile lost responses.
Saved workspaces have plan-specific storage quotas and retention. Export /workspace as a portable archive for independent backups. See the workspace API contract for limits, archive/delete behavior, and image compatibility.
Stop, resume, and fork
When persistence.filesystemAfterStop is true in GET /capabilities, the dashboard offers Stop and save, then Resume. Files remain available until the displayed snapshot expiry. Resume starts a new generation of the same machine and consumes a normal start. Running processes and memory are not preserved.
When persistence.filesystemFork is true, Fork copies a running machine’s filesystem into an independent new machine. Both machines use their normal runtime allowances. The API uses POST /containers/stop, POST /containers/resume, and POST /containers/fork with the exact id and createdAt plus an Idempotency-Key. Reuse the same key when retrying an uncertain request.
Outbound access and secrets
New container settings show available outbound policies. networking.internetControl enables internet-off launches; networking.egressPolicies enables domain and IP-range allow/deny lists for HTTP and HTTPS. Deny rules take precedence, and the policy is fixed for that machine’s generation. Features absent from discovery remain unavailable.
Use the Secrets tab to save a credential for one HTTPS hostname and request header when secrets.vault is enabled. Select it when launching with a policy that allows that hostname. Values are write-only and injected outside the guest. Use scoped credentials with trusted upstream services; a credentialed service can still disclose the value in its response. Existing secrets can be listed or deleted even while new issuance is disabled.
Server-managed prewarming pools
The source API and SDKs add persistent pools with automatic replenishment. Require pools.managed from GET /capabilities. Create with POST /pools, a saved Idempotency-Key, and {"name":"Agent workers","targetSize":2,"ttlSeconds":600,"catalogId":"python"}. Poll the returned pool until its ready count is positive, then acquire with POST /pools/{poolId}/acquire and a separate saved key.
Both SDKs expose client.pools for list, create, get, update, acquire and delete. Inventory is billed and keeps ordinary idle and hard deadlines; replacement consumes another start. A required 60–86400-second pool lifetime bounds automatic replenishment. Set the target to zero to pause and drain. Delete the pool to clean up unclaimed inventory; acquired machines remain yours to stop. Retry uncertain requests with their original keys. This source feature needs deployment and qualification; the separate client.pool() helper still keeps process-local inventory.
Private Services between machines
Connect a frontend to a backend using http://api.internal/users, without a public backend preview or a Mainbrella API key inside the guest. Private Services is a local HTTP prototype. Require networking.privateServices: true from GET /capabilities before use; absent or false means unavailable. Production support has not been qualified.
In the dashboard’s Private Services controls, create a named network and attach both running machines. Register the backend as api with its application port, such as 8080. Attach the frontend as web without a port for caller-only access. From the frontend, request http://api.internal/users; the platform routes it to the backend’s registered port. A browser preview for the frontend is a separate, opt-in grant.
POST /private-services/networks
{"name":"app"}
PUT /private-services/members?network=app
{"id":"<backend-id>","createdAt":"<backend-generation>","name":"api","port":8080}
PUT /private-services/members?network=app
{"id":"<frontend-id>","createdAt":"<frontend-generation>","name":"web"}
# Run inside the attached frontend:
curl http://api.internal/users
Authenticate management requests with your API key or browser session. Both machines must belong to the same account-owned network and remain current, running, paid generations. Stop or replacement prevents stale membership from routing; attach replacements explicitly. Attach or detach existing machines without recreating them. Each machine keeps its own deadlines and lifecycle; membership does not change internet policy or start machines.
Plain HTTP on port 80 to NAME.internal only, mapped to registered ports 1024–65535. Limits: 16 networks per account, 32 members per network, one network per generation, 1 MiB per request and response, and a 10-second timeout. HTTPS, WebSockets, CONNECT, arbitrary TCP/UDP, private IPs, and direct database protocols are unsupported. Put a database behind an HTTP service if needed.
List networks with GET /private-services/networks. Detach with DELETE /private-services/members?network=app and the exact member’s {id, createdAt, name}; then delete the empty network with DELETE /private-services/networks?network=app. Detach does not stop the machine or undo an already accepted request. See the complete API contract.
Protected application previews
Protected previews are enabled on the isolated mainbrella.dev gateway after live HTTP, WebSocket, browser, and account/generation isolation qualification. Check GET /capabilities; use it only when previews.supported is true. The dashboard then shows a Preview control beside each container. Start your HTTP server first, enter its port, and create a link. The dashboard shows expiration and lets you revoke access.
POST /containers/previews?id=<id>&createdAt=<generation>
Authorization: Bearer mb_<your-key>
Content-Type: application/json
{"port":3000,"ttlSeconds":900}
The response contains {id, port, createdAt, expiresAt, url}. The HTTPS URL gives anyone who has it access to the selected port. It is returned once; share deliberately and keep it out of logs and analytics. expiresAt is Unix milliseconds. Links last 60–3600 seconds, default to 15 minutes, and end no later than the container deadline. Ports 1024–65535 are eligible; eight grants can be active per generation.
List active metadata with GET /containers/previews?id=…&createdAt=…; URLs cannot be recovered after reload. Revoke with DELETE /containers/previews?id=…&createdAt=…&previewId=…. Revocation closes active connections. Stop, expiry, or generation replacement invalidates access. Listing and revocation remain available when new issuance is disabled.
Creating a link is not idempotent. After a lost response, list and revoke the unwanted grant before creating another. A preview_reconciliation_required error includes previewId; retry DELETE with that ID and the same generation. Requests never start or restart a container. Cookies and Authorization are stripped; cookie sessions, external Host semantics and absolute redirect rewriting are unsupported. See the full contract and local JavaScript / Python helpers.