Quickstart

Give your agent a Linux workspace through the HTTP API. This walkthrough creates one container, runs foreground and managed commands, verifies binary transfer and cancellation, and stops the container it created.

1. Get access and an API key

Sign in, choose a plan or redeem a valid trial code, then create a named key in API Keys. Copy it once and provision MAINBRELLA_API_KEY in your environment through your secret manager. Keep it out of source code, chat, and logs.

2. Check your setup

Use Node.js 22 or later on your local computer. Download and inspect these dependency-free scripts before running them. The doctor reads public deployment capabilities and authenticated account access, allowance, and available images; it does not start a container.

curl --fail --silent --show-error https://mainbrella.com/mainbrella-doctor.mjs -o mainbrella-doctor.mjs
curl --fail --silent --show-error https://mainbrella.com/mainbrella-verify.mjs -o mainbrella-verify.mjs
node mainbrella-doctor.mjs

3. Create, execute, and clean up

After the doctor passes, run the verification script from the same directory. This consumes one monthly start, including if startup fails.

node mainbrella-verify.mjs

A pass reports ok: true, stdout: "hello from mainbrella", exitCode: 0, files: "verified", managed: "verified", cancellation: "verified", and cleanup: "completed". The script uses an idempotency key, checks the returned creation identity, transfers a binary file, verifies managed streaming and cancellation, and cleans up in finally. Existing containers are preserved. Managed admission keys and the execution ID are retained in the report if that stage needs reconciliation.

If startup is ambiguous, keep the reported creationKey and repeat the same creation request with that key within 24 hours to recover its identity. If cleanup failed, stop the exact reported ID and generation. Resolve either condition before running again.

4. Integrate with your agent

Use native HTTP requests in your application's existing language and conventions. Start with Containers, Execute, and Files, or give your coding agent the Mainbrella skill.

Local SDKs are implemented but unpublished. If you have the backend checkout, follow the JavaScript SDK reference or Python SDK reference for local installation. These instructions require the local source paths; no npm or PyPI registry release is available.

All plans offer five sizes from 256 MiB to 12 GiB RAM. Send a size when creating a container; Lite is the default. Export files before stopping. See limits before launching in parallel.