# LumiCloud > Sandboxes for AI agents, compatible with E2B's SDKs: set E2B_DOMAIN=lumicloud.dev and E2B_API_KEY to a LumiCloud key; the code stays the same. ## Docs - [Quick start](https://lumicloud.ai/docs/quickstart.md): Create a sandbox and run a command in it, with E2B's Python or JavaScript SDK. - [Migrating from E2B](https://lumicloud.ai/docs/migrate-from-e2b.md): LumiCloud serves the E2B API: the same SDKs and the same code, with another domain and key. - [Agent frameworks](https://lumicloud.ai/docs/agent-frameworks.md): Agent frameworks that create sandboxes with E2B's SDK run them on LumiCloud with the same two environment variables. - [MCP server](https://lumicloud.ai/docs/mcp.md): Give Claude, Cursor or any MCP client tools to create sandboxes, run commands and code, and move files, with a LumiCloud API key. - [Templates](https://lumicloud.ai/docs/templates.md): A template is the image a sandbox starts from. Use a public one, or build your own. - [Network](https://lumicloud.ai/docs/network.md): What a sandbox can reach, and how to reach a sandbox. - [Egress rules](https://lumicloud.ai/docs/egress-rules.md): Limit which destinations your sandboxes may connect to: default rules for the whole account, and rules of each sandbox. - [Webhooks](https://lumicloud.ai/docs/webhooks.md): Receive the lifecycle events of your sandboxes as HTTPS requests, signed with Standard Webhooks. - [Limits and billing](https://lumicloud.ai/docs/limits-and-billing.md): Prices, limits, and what happens when the balance runs out. ## Examples - [lumibox-examples](https://github.com/LumiCloudOrg/lumibox-examples): runnable Python and JavaScript examples, run against LumiCloud every day ## Status - [Status page](https://status.lumicloud.uk): whether the sandbox API, the MCP server, the console and the website are up, incidents and maintenance - [https://status.lumicloud.uk/api/v2/summary.json](https://status.lumicloud.uk/api/v2/summary.json): the same as JSON (Atlassian Statuspage's format); `status.indicator` is `none` when all is well ## Quick start Create a sandbox and run a command in it, with E2B's Python or JavaScript SDK. ### 1. Open the service Sign up for a Lumi account, then open https://console.lumicloud.ai/sandbox/ and verify a card: $1 is charged and given back at once. New customers get $20 of credit after verifying a card, to use within 30 days. ### 2. Create an API key On the console's API keys page, create a key. It is shown once; keep it. ### 3. Install the SDK and set the domain and the key ```sh pip install e2b # or: npm install e2b ``` ```sh export E2B_DOMAIN=lumicloud.dev export E2B_API_KEY= ``` ### 4. Create a sandbox ```python from e2b import Sandbox sandbox = Sandbox.create("base", timeout=300) # seconds before it ends by itself result = sandbox.commands.run("python3 -c 'print(6 * 7)'") print(result.stdout) # 42 sandbox.kill() ``` ```javascript import { Sandbox } from "e2b" const sandbox = await Sandbox.create("base", { timeoutMs: 300_000 }) const result = await sandbox.commands.run("python3 -c 'print(6 * 7)'") console.log(result.stdout) // 42 await sandbox.kill() ``` ### Pause and resume A paused sandbox keeps its memory, files and processes until you delete it, and is not charged for running. Resume it by its ID. ```python sandbox_id = sandbox.sandbox_id sandbox.pause() sandbox = Sandbox.connect(sandbox_id) # resumes it print(sandbox.commands.run("uptime").stdout) ``` ### Code interpreter E2B's code interpreter SDK works too; it uses the public template code-interpreter-v1. ```sh pip install e2b-code-interpreter ``` ```python from e2b_code_interpreter import Sandbox with Sandbox.create() as sandbox: print(sandbox.run_code("sum(range(10))").text) # 45 ``` ### A sandbox's ports A server listening on a port of a sandbox is reachable at https://-.lumicloud.dev. ```python sandbox.commands.run("python3 -m http.server 8000", background=True) print("https://" + sandbox.get_host(8000)) ``` ### More examples [lumibox-examples](https://github.com/LumiCloudOrg/lumibox-examples) has runnable examples in Python and JavaScript: Claude and OpenAI tool calling with a code interpreter, Claude Code in a sandbox, a browser driven with Playwright, a desktop for computer use, and a parallel evaluation. They run against LumiCloud every day. ## Migrating from E2B LumiCloud serves the E2B API: the same SDKs and the same code, with another domain and key. ### Change two environment variables ```sh export E2B_DOMAIN=lumicloud.dev export E2B_API_KEY= ``` Or pass them in code: ```python Sandbox.create("base", domain="lumicloud.dev", api_key="") ``` ### What to do again in LumiCloud - Templates of your own: build them again with the same definition on Pro (see Templates). Their names are your account's. - Public templates: base, code-interpreter-v1, browser, browser-2g, desktop, desktop-2g are there for every account. - API keys: create them in the LumiCloud console; E2B keys do not work here. - Agent frameworks that use E2B (CrewAI, OpenAI Agents SDK, Mastra and others) need the same two variables; see [Agent frameworks](/docs/agent-frameworks). ### Differences - One region, Singapore. - Billing in US dollars from a prepaid balance. - Limits differ: see Limits and billing. - Outbound mail ports and UDP other than DNS are blocked. ## Agent frameworks Agent frameworks that create sandboxes with E2B's SDK run them on LumiCloud with the same two environment variables. ### Set the domain and the key ```sh export E2B_DOMAIN=lumicloud.dev export E2B_API_KEY= ``` The frameworks below create sandboxes with E2B's SDK and set no domain of their own, so the SDK takes it from E2B_DOMAIN. Set E2B_DOMAIN, not only E2B_API_URL: E2B_API_URL moves the API calls but not the traffic to the sandboxes. Some frameworks also take a `domain` option. ### Frameworks | Framework | Package | Notes | | --- | --- | --- | | [CrewAI](https://github.com/crewAIInc/crewAI/blob/main/lib/crewai-tools/src/crewai_tools/tools/e2b_sandbox_tool/e2b_base_tool.py) | `crewai-tools[e2b]` | Takes `domain=`. `E2BPythonTool` uses code-interpreter-v1. | | [LangChain Deep Agents](https://github.com/e2b-dev/langchain-e2b) | `langchain-e2b` | Pass your own `Sandbox.create(...)`, or let the provider create one; it reads `E2B_TEMPLATE`. | | [OpenAI Agents SDK](https://github.com/openai/openai-agents-python/blob/main/src/agents/extensions/sandbox/e2b/sandbox.py) | `openai-agents[e2b]`, `@openai/agents-extensions` | Pauses sandboxes at their timeout by default; they resume when used again. | | [Agno](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/e2b.py) | `agno`, `e2b_code_interpreter` | `sandbox_options` passes `domain`. | | [smolagents](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py) | `smolagents[e2b]` | `executor_type="e2b"`; `executor_kwargs` passes `domain`. | | [Mastra](https://github.com/mastra-ai/mastra/tree/main/workspaces/e2b) | `@mastra/e2b`, `@mastra/e2b-desktop` | Set `template: 'base'`: without one it builds a template of its own, which needs Pro. The desktop one uses the desktop template. | | [Vercel AI SDK](https://github.com/e2b-dev/ai-sdk-sandbox) | `@e2b/ai-sdk-sandbox` | Takes `domain`. | | [Pydantic AI](https://github.com/pydantic/pydantic-ai/tree/main/src/pydantic_ai_harness/pydantic_ai_harness/e2b_sandbox) | `pydantic-ai-harness[e2b]` | Pauses sandboxes at their timeout. Takes `client=E2B(domain=...)`. | | [Google ADK](https://github.com/google/adk-python/tree/main/src/google/adk/integrations/e2b) | `google-adk[e2b]` | Uses base by default. | | [Haystack](https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/e2b) | `e2b-haystack` | Uses base by default. | | [AG2](https://github.com/ag2ai/ag2/tree/main/ag2/extensions/e2b) | `ag2` | `create_options` passes `domain`. | | [TanStack AI](https://github.com/TanStack/ai/tree/main/packages/ai-sandbox-e2b) | `@tanstack/ai-sandbox-e2b` | Takes `domain`. | Most of them use the public template base or code-interpreter-v1 unless you name another. Read each framework's own docs for its tools and options. ### What they use from the SDK Beyond creating sandboxes and running code, these frameworks use the features below. Each was checked against LumiCloud with E2B's Python SDK 2.64.0. - Pause at the timeout instead of ending (`lifecycle={"on_timeout": "pause"}`), and resume with `Sandbox.connect`, files and memory kept. - Resume when a request reaches a paused sandbox's port (`auto_resume`). - Metadata on create, and listing sandboxes by metadata and state. - Snapshots: `create_snapshot`, and new sandboxes from a snapshot. - Sandboxes without internet access (`allow_internet_access=False`). ## MCP server Give Claude, Cursor or any MCP client tools to create sandboxes, run commands and code, and move files, with a LumiCloud API key. ### Connect The server is https://mcp.lumicloud.dev/mcp (Streamable HTTP). Authenticate with a LumiCloud API key as a bearer token; the console's API keys page makes one. Sandboxes made through it are billed like any other, and the SDK sees them too. Claude Code: ```sh claude mcp add --transport http lumicloud https://mcp.lumicloud.dev/mcp \ --header "Authorization: Bearer $E2B_API_KEY" ``` Cursor (`~/.cursor/mcp.json`): ```json { "mcpServers": { "lumicloud": { "url": "https://mcp.lumicloud.dev/mcp", "headers": { "Authorization": "Bearer " } } } } ``` Other clients: the server's URL, transport Streamable HTTP (or "http"), and the header `Authorization: Bearer `. ### Tools | Tool | What it does | | --- | --- | | sandbox_create | Create a sandbox from a template (base by default) and return its ID. Options: timeout, pause or kill at the timeout, internet on or off, allowed destinations, environment variables, metadata. | | sandbox_exec | Run a shell command and wait for it, or start it in the background with its output in a log file. | | sandbox_run_code | Run Python or JavaScript in the kernel of code-interpreter-v1; variables stay between calls, charts come back as images. | | sandbox_read_file | Read a text file, or an image to look at. | | sandbox_write_file | Write a file, text or base64, up to 4 MiB. | | sandbox_file_link | A signed URL to download a file or upload one, for big or binary files. | | sandbox_port_link | The HTTPS URL of a port, and whether something listens on it. | | sandbox_list | The account's sandboxes, running and paused, by state and metadata. | | sandbox_pause | Pause a sandbox: files and memory kept, running no longer billed. | | sandbox_kill | Delete a sandbox and its files. | | sandbox_templates | The public templates and the account's own. | ### How sandboxes live - A sandbox lives 15 minutes unless sandbox_create asks for another time, within the plan's longest run. Each call on it keeps it alive for at least 10 more minutes. - At the end of its time a sandbox is paused unless it was created to be killed. A paused sandbox resumes on the next call on it, or when its port link is opened. - Commands return at most 32 KiB of output, the start and the end kept; redirect bigger output to a file. A command or code runs at most 10 minutes; longer jobs go in the background. ### Limits Per API key: 120 tool calls a minute, 10 sandboxes created a minute, 8 calls at once. The plan's limits apply as with the SDK. ## Templates A template is the image a sandbox starts from. Use a public one, or build your own. ### Public templates Public templates are the same for every account, are never charged for storage, and are used by name. The console's templates page lists the ones the platform offers now, with their sizes; these are always there. | Template | Size | Contents | | --- | --- | --- | | base | 2 vCPU, 1 GiB | E2B's base image (e2bdev/base); the default | | code-interpreter-v1 | 2 vCPU, 1 GiB | The template of E2B's code interpreter SDK | | browser | 2 vCPU, 1 GiB | Headless Chromium, already running, with its DevTools (CDP) on port 9222 | | browser-2g | 2 vCPU, 2 GiB | The same with more memory, for many tabs or heavy pages | | desktop | 2 vCPU, 1 GiB | A Linux desktop for E2B's desktop SDK: screenshots, mouse, keyboard, a live view, and Chromium | | desktop-2g | 2 vCPU, 2 GiB | The same with more memory | A template's size is the size of its sandboxes, so a template bigger than the plan's size of a sandbox cannot be used on that plan (Base: 4 vCPU and 8 GiB). ```python sandbox = Sandbox.create("base") ``` ### A browser for agents The browser template starts with Chromium running. Connect to it over CDP at https://9222-.lumicloud.dev with Playwright, Puppeteer or any CDP client; nothing is installed on your machine but the client. The User-Agent says HeadlessChrome; set your own if a site refuses it. ```python from e2b import Sandbox from playwright.sync_api import sync_playwright with Sandbox.create("browser", timeout=300) as sandbox, sync_playwright() as p: browser = p.chromium.connect_over_cdp("https://" + sandbox.get_host(9222)) page = browser.contexts[0].new_page() page.goto("https://example.com") print(page.title()) ``` ### A desktop for computer use E2B's desktop SDK uses the desktop template by default: set the domain and the key, and leave the template out. ```sh pip install e2b-desktop # or: npm install @e2b/desktop ``` ```python from e2b_desktop import Sandbox desktop = Sandbox.create() desktop.stream.start() print(desktop.stream.get_url()) # watch it in your browser desktop.launch("google-chrome") png = desktop.screenshot() desktop.left_click(500, 300) desktop.write("hello") desktop.kill() ``` ### Your own templates Templates of your own are built with the SDK's template builder, from a container image or a Dockerfile, and used by name. A template belongs to the account that built it and is visible to that account only; its name is unique within the account. Building comes with Pro (2 builds at a time); Base uses the public templates. ### Build from a base image ```python from e2b import Template, Sandbox template = ( Template() .from_python_image("3.12") .pip_install(["requests", "pandas"]) ) Template.build(template, "my-template", cpu_count=2, memory_mb=2048) sandbox = Sandbox.create("my-template") ``` ### Build from a Dockerfile ```python template = Template().from_dockerfile("Dockerfile") Template.build(template, "my-app", cpu_count=2, memory_mb=2048) ``` The same builder is in the JavaScript SDK; the build runs on LumiCloud and its output is streamed back to the SDK. ### Size A template's cpu_count and memory_mb are the size of the sandboxes made from it, within the plan's size of a sandbox (Base: up to 4 vCPU and 8 GiB; Pro: up to 8 vCPU and 16 GiB). Creating a sandbox from a bigger template is refused with the reason (400). ### Storage and cost A template of your own is stored once, whatever the number of sandboxes made from it, and is charged by the hour at $0.080 per GiB per month beyond the plan's free storage (5 GiB on Base, 20 GiB on Pro), together with the snapshots of paused sandboxes. Data that a sandbox shares with its template counts once. Running a sandbox from a template is charged as any sandbox: by vCPU and memory, for the running time. ### The console's templates page - Lists the public templates and your own, as the cluster has them. For each: its name and ID, the size of a sandbox made from it (vCPU and memory), the disk (its whole size, and the free space of it that the build asked for), the status of its latest build (ready, building, failed), when a sandbox was last started from it and how many have been, and, for your own, the size stored and the storage cost per month. - Deletes a template of your own. It is refused while a sandbox, running or paused, is made from it: delete those first. A deleted template is no longer stored or charged. The public templates cannot be deleted. - On a plan without builds, shows the plan that has them and its upgrade. - Does not build templates: that is done with the SDK. ### Errors - A template bigger than the plan's size of a sandbox: 400, with the reason. - Deleting a template that a sandbox, running or paused, is made from: 400, with the reason. ## Network What a sandbox can reach, and how to reach a sandbox. ### Outbound - Any address on the internet. - Outbound mail ports (25, 465, 587, 2525) and UDP other than DNS are blocked. - Each connection is recorded with its time, ends and bytes, for abuse reports. - Your own rules narrow this further; see Egress rules. ### Inbound: a sandbox's ports A server on a port of a sandbox is reachable at https://-.lumicloud.dev; sandbox.get_host(port) gives the host. ## Egress rules Limit which destinations your sandboxes may connect to: default rules for the whole account, and rules of each sandbox. ### How rules apply A connection leaves a sandbox only if it passes three layers, each judged on its own: - Platform rules: fixed by LumiCloud, the same for every account (see Platform limits). - Default rules: yours, set in the console, applied to every sandbox of the account, running or created later. - Sandbox rules: given to one sandbox when it is created (the SDK's network option) or changed while it runs. Rules can only narrow. A sandbox's rules cannot open what your default rules close, and your default rules cannot open what the platform closes. A destination allowed by one layer is not allowed until all three allow it. ### Rule lists Each set of rules has two lists, in the form of E2B's network option. | List | Entries | | --- | --- | | allow_out | An IP address, a CIDR range, a domain name (api.example.com) or a wildcard name (*.example.com) | | deny_out | An IP address or a CIDR range; domain names cannot be denied | - In the console, one entry per line. - A destination in allow_out is allowed even if deny_out also matches it: allow wins over deny. - A destination that matches neither list is allowed. - Names in allow_out are matched on the name the connection asks for (the Host header on port 80, the server name on port 443) and connected by name, so a connection to an allowed name cannot be pointed at another address. - Because a name cannot be denied, allowing only some names takes two steps: allow them, and deny 0.0.0.0/0. ### Allow only some destinations Allow the names, then deny everything else. The deny entry 0.0.0.0/0 is required whenever allow_out holds a name. In the console, write the names under Allow and 0.0.0.0/0 under Deny: ```text Allow api.example.com *.example.org 203.0.113.0/24 Deny 0.0.0.0/0 ``` On a sandbox, with the SDK: ```python from e2b import Sandbox sandbox = Sandbox.create( "base", network={ "allow_out": ["api.example.com", "*.example.org"], "deny_out": ["0.0.0.0/0"], }, ) ``` ```javascript import { Sandbox } from "e2b" const sandbox = await Sandbox.create("base", { network: { allowOut: ["api.example.com", "*.example.org"], denyOut: ["0.0.0.0/0"], }, }) ``` ### Deny some destinations Deny an address or range and leave allow_out empty; everything else stays open. ```python sandbox = Sandbox.create("base", network={"deny_out": ["198.51.100.0/24"]}) ``` ### No internet access A sandbox created with allow_internet_access=False has no outbound network at all, whatever the rules say. ### Change rules while a sandbox runs Changing a sandbox's network settings while it runs, or saving the default rules, takes effect at once. Connections that are open and no longer allowed are closed; loosening rules leaves open connections alone. A paused sandbox keeps its own rules and gets them back when it resumes, and the default rules are the account's current ones at that time. ### Default rules in the console - Egress rules page: two boxes, Allow and Deny, one entry per line, with the number of entries used and the plan's limit. - Save rules applies them to all sandboxes of the account. Remove all clears both lists. - A sandbox's detail page shows the rules in effect, layer by layer: the platform's, your default rules, the sandbox's own. ### Limits of a plan Each set of rules (your default rules, and the rules of each sandbox) holds a limited number of entries, allow and deny together: Base 10, Pro 100. The entry 0.0.0.0/0 in deny_out is not counted. A list over the limit is refused with the limit in the reason. A paused sandbox whose rules are over a lowered limit still resumes. ### Platform limits These hold on every plan, whatever the rules say, and cannot be opened: - Outbound mail ports 25, 465, 587 and 2525 are closed. - Private and internal networks are closed. - The platform's own hosts are reachable on ports 80 and 443 only. - UDP is allowed to the DNS resolver only. An account whose plan allows only a list of destinations reaches those destinations only; your rules narrow that list and do not extend it. The console shows the tier on a sandbox's rules in effect. ### Errors - An entry that is not an address, a range, a name or a wildcard name, or a name in deny_out: refused, naming the entry. - A name in allow_out without 0.0.0.0/0 in deny_out: refused. - More entries than the plan allows: refused, with the limit. ## Webhooks Receive the lifecycle events of your sandboxes as HTTPS requests, signed with Standard Webhooks. ### Overview An endpoint is an HTTPS address of yours that LumiCloud calls with a POST request for each event it subscribes to. Endpoints belong to the account. They are managed in the console (Webhooks) or through the REST API at https://api.lumicloud.ai/v1/webhooks/. Deliveries are signed with Standard Webhooks (standardwebhooks.com), so the official libraries verify them. E2B's webhook API (/events/webhooks) is not provided, and requests carry no e2b-signature. The body of a sandbox event keeps E2B's form, so code that reads E2B's lifecycle payload reads it unchanged; only the verification differs. E2B's events API (/events/sandboxes on api.lumicloud.dev) answers with your LumiBox API key. ### Events | Event | When | | --- | --- | | sandbox.lifecycle.created | A sandbox was created and started. | | sandbox.lifecycle.paused | A sandbox was paused: its run ended and it can be resumed (event_data.pause_mode: full, or filesystem). | | sandbox.lifecycle.resumed | A paused sandbox was resumed (event_data.resume_mode: restore, or reboot from its file system). | | sandbox.lifecycle.killed | A sandbox was killed, timed out or lost: its run ended and it is gone (event_data.kill_reason says why). | | sandbox.lifecycle.updated | A running sandbox's timeout or network was changed (event_data.set_timeout, network_egress); several in a run. | | sandbox.lifecycle.checkpointed | A snapshot of a running sandbox was taken and it went on running; several in a run. | An endpoint subscribes to event types or to a prefix ending in .* (sandbox.lifecycle.*, sandbox.*). Each type's example is under Examples, the schema of the body under JSON Schema. ### Delivery - An event is sent about a second after it happens. If the cluster's real-time record misses it, the platform's reconciliation sends it within about two minutes. - Each event is delivered at least once. webhook-id is the event's ID, the same for every attempt and resend: a receiver drops what it has seen. - Order between events is not guaranteed; a retry can arrive after a later event. The timestamp in the body orders them. - A response with a status 2xx is a success. Anything else is a failure: another status, a redirect (not followed), no answer within 15 seconds, a failed connection or TLS handshake, a name that does not resolve. - A failed delivery is retried after 5 seconds, 5 minutes, 30 minutes, 2, 5, 10, 14, 20 and 24 hours (each wait ±10%): 10 attempts over about three days. Retry-After on a failed answer lengthens the next wait, up to an hour. - After 5 failures in a row the endpoint rests: nothing is sent for a minute, then one delivery is tried; each further failure doubles the rest, up to an hour. Resting uses no attempts. - 410 Gone disables the endpoint at once; its pending deliveries are canceled. - A paused endpoint keeps its events and receives them when it is active again, within a delivery's deadline (about three days). A disabled endpoint receives nothing. - A delivery that used all its attempts is marked failed; Resend sends it again with the same event ID. - A new endpoint receives the events that happen after it is made, not earlier ones. ### Request headers | Header | Value | | --- | --- | | content-type | application/json | | user-agent | LumiCloud-Webhooks/1 | | webhook-id | The event's ID, the same for every attempt and resend. | | webhook-timestamp | When the request was signed, in Unix seconds. | | webhook-signature | v1,, one for each secret that signs now, separated by spaces. | | lumi-delivery-id | The delivery (this event to this endpoint). | | lumi-attempt | The attempt's number, from 1. | | lumi-test | true on an example sent from the console or the API. | ### Verifying a delivery Use the raw body exactly as received, not a re-serialised one. The signature is the base64 of HMAC-SHA256, keyed with the secret's key, of webhook-id, a dot, webhook-timestamp, a dot and the body. The official libraries check it and refuse a timestamp more than five minutes away. ```python # pip install standardwebhooks from standardwebhooks.webhooks import Webhook wh = Webhook("whsec_...") # the endpoint's signing secret def handle(raw_body: bytes, headers: dict): event = wh.verify(raw_body, headers) # raises on a bad signature or an old timestamp if seen(headers["webhook-id"]): return 200 ... ``` ```js // npm install standardwebhooks import { Webhook } from "standardwebhooks" const wh = new Webhook("whsec_...") // the endpoint's signing secret app.post("/hooks", express.raw({ type: "application/json" }), (req, res) => { const event = wh.verify(req.body, req.headers) // throws on a bad signature or an old timestamp res.sendStatus(200) }) ``` Libraries for Go, Ruby, PHP, Java, Rust, C# and Elixir are listed on standardwebhooks.com. ### Payload The body of a sandbox event is JSON in the form of E2B's lifecycle webhooks (version v2, snake_case). event_data is the cluster's own: what it holds depends on the type. ```json { "version": "v2", "id": "5b2c8e0e-8f0e-4a39-9c47-0d6a4c1f2a10", "type": "sandbox.lifecycle.killed", "timestamp": "2026-11-22T10:15:30.123456Z", "event_category": "lifecycle", "event_label": "kill", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e", "sandbox_template_id": "base", "sandbox_build_id": "7e3f1a52-4c1d-4e8a-b5a0-9f2b6c1d3e44", "sandbox_team_id": "3a1f0c52-6b7e-5d3a-8f10-2c4e9b7a1d05", "events_ttl_days": 30, "event_data": { "sandbox_metadata": { "user": "42" }, "execution": { "started_at": "2026-11-22T10:10:00Z", "vcpu_count": 2, "memory_mb": 1024, "execution_time": 330123 }, "kill_reason": "request" } } ``` | Field | Meaning | | --- | --- | | id | The event's ID (also webhook-id). | | type, event_category, event_label | The event type; lifecycle; create, pause, resume, kill, update or checkpoint. | | timestamp | When the event happened (UTC, RFC 3339). | | sandbox_id, sandbox_execution_id | The sandbox, and the run it was in (a resume starts a new run). | | sandbox_template_id, sandbox_build_id, sandbox_team_id | The template and build the sandbox started from, and your account's team ID. | | events_ttl_days | How many days the event is kept and available from the events API. | | event_data.sandbox_metadata | The metadata given when the sandbox was created, as given. | | event_data.execution | On paused and killed events: started_at, vcpu_count, memory_mb of the run, and execution_time in milliseconds. | | event_data.kill_reason | On killed events, see below. | | event_data.pause_mode, resume_mode | On paused and resumed events: how the sandbox was paused or resumed. | | event_data.set_timeout, network_egress | On updated events: the new timeout or network settings. | | event_data.platformSuspended | On paused and killed events while the platform had stopped the account: arrears, freeze, operator, account or risk. | ### Examples One example of each type, as delivered. event_data holds only what the cluster tells for that type. sandbox.lifecycle.created ```json { "version": "v2", "id": "a99ed186-49dc-5ea6-ab62-94369212e3da", "type": "sandbox.lifecycle.created", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "create", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "sandbox_metadata": { "user": "example" } } } ``` sandbox.lifecycle.paused ```json { "version": "v2", "id": "6b706076-11b4-5adf-a119-ad785f370045", "type": "sandbox.lifecycle.paused", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "pause", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "execution": { "execution_time": 60000, "memory_mb": 1024, "started_at": "2026-11-22T03:03:05Z", "vcpu_count": 2 }, "pause_mode": "full", "sandbox_metadata": { "user": "example" } } } ``` sandbox.lifecycle.resumed ```json { "version": "v2", "id": "6054f537-006b-5f84-8001-3792d9c4b390", "type": "sandbox.lifecycle.resumed", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "resume", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "7a41c2e8-93b5-4f06-a1d7-2e6c9b0f4d83", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "resume_mode": "restore", "sandbox_metadata": { "user": "example" } } } ``` sandbox.lifecycle.killed ```json { "version": "v2", "id": "15ec9fd1-ebb0-58f7-8a6c-b72c63f435dd", "type": "sandbox.lifecycle.killed", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "kill", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "7a41c2e8-93b5-4f06-a1d7-2e6c9b0f4d83", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "execution": { "execution_time": 60000, "memory_mb": 1024, "started_at": "2026-11-22T03:03:05Z", "vcpu_count": 2 }, "kill_reason": "request", "sandbox_metadata": { "user": "example" } } } ``` sandbox.lifecycle.updated ```json { "version": "v2", "id": "41d213e4-7798-5565-9064-0fc0599be5bf", "type": "sandbox.lifecycle.updated", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "update", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "sandbox_metadata": { "user": "example" }, "set_timeout": "2026-11-22T03:14:05Z" } } ``` sandbox.lifecycle.checkpointed ```json { "version": "v2", "id": "83dc9783-d088-5a8a-996c-925f639df4a0", "type": "sandbox.lifecycle.checkpointed", "timestamp": "2026-11-22T03:04:05Z", "event_category": "lifecycle", "event_label": "checkpoint", "sandbox_id": "ixyz1234abcd", "sandbox_execution_id": "0d9d6a4c-1f2a-4b10-8c47-5b2c8e0e8f0e", "sandbox_template_id": "base", "sandbox_build_id": "b1d2e3f4-0000-4000-8000-000000000001", "sandbox_team_id": "d5740fb5-7a7f-58ea-88d0-93a5cdafcf3b", "events_ttl_days": 30, "event_data": { "sandbox_metadata": { "user": "example" } } } ``` ### JSON Schema The body of every sandbox event (JSON Schema 2020-12). Fields may be added; a receiver ignores the ones it does not know. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "version", "id", "type", "timestamp", "event_category", "event_label", "sandbox_id", "sandbox_execution_id", "sandbox_template_id", "sandbox_build_id", "sandbox_team_id", "events_ttl_days" ], "properties": { "version": { "const": "v2", "type": "string" }, "id": { "description": "the event's id, the same on every attempt", "format": "uuid", "type": "string" }, "type": { "type": "string" }, "timestamp": { "format": "date-time", "type": "string" }, "event_category": { "const": "lifecycle", "type": "string" }, "event_label": { "enum": [ "create", "resume", "pause", "kill", "update", "checkpoint" ], "type": "string" }, "sandbox_id": { "type": "string" }, "sandbox_execution_id": { "description": "the run: from a start (created, resumed) to its end (paused, killed)", "type": "string" }, "sandbox_template_id": { "type": "string" }, "sandbox_build_id": { "type": "string" }, "sandbox_team_id": { "format": "uuid", "type": "string" }, "events_ttl_days": { "description": "how many days the events API keeps the event", "type": "integer" }, "event_data": { "properties": { "execution": { "properties": { "execution_time": { "description": "milliseconds the run took (paused, killed)", "type": "integer" }, "memory_mb": { "type": "integer" }, "started_at": { "format": "date-time", "type": "string" }, "vcpu_count": { "type": "integer" } }, "type": "object" }, "kill_reason": { "description": "killed: why, as the orchestrator tells it (request, timeout, admin, orphaned, unknown, …); orphaned when the cluster lost the end", "type": "string" }, "network_egress": { "description": "updated: the sandbox's new egress rules", "type": "object" }, "pause_mode": { "description": "paused: full (memory and file system) or filesystem", "type": "string" }, "platformSuspended": { "description": "why the platform had stopped the customer when the run ended (a hint)", "type": "string" }, "reason": { "description": "lost: the cluster has no record of the end", "type": "string" }, "resume_mode": { "description": "resumed: restore (memory restored) or reboot (booted from the file system)", "type": "string" }, "sandbox_metadata": { "additionalProperties": { "type": "string" }, "type": "object" }, "set_timeout": { "description": "updated: the sandbox's new end", "format": "date-time", "type": "string" } }, "type": "object" } } } ``` ### Kill reasons | kill_reason | When | | --- | --- | | request | The sandbox was killed through the API or the console. | | timeout | The sandbox reached its timeout. | | orphaned | The cluster lost the end of the run (its node went away); event_data.reason is lost. | | admin | The run ended while the platform had stopped the account (see platformSuspended). | | unknown | The reconciliation sent the event and the reason is not in its records. | The cluster can send other values; treat an unknown value as unknown. ### Signing secret - Each endpoint has a secret (whsec_ followed by base64), made by the platform and shown when the endpoint is created. - Reveal shows the secrets that sign now. It asks for a recent sign-in, and each reveal is recorded. - Rotate makes a new secret. The previous one keeps signing for the time chosen (now, 24 hours or 7 days), so receivers can switch over: during that time each request carries both signatures. ### Address rules - https only, port 443 or none, no user information in the address. - A domain name, not an IP address in any form. - Local names and the platform's own domains are refused. - Redirects are not followed. - The address is checked again when a request is sent: a name that now leads to a private or internal address is not connected to. ### In the console - Endpoints: create, edit, pause, disable, delete; send an example of any type; reveal and rotate the secret; health and attempts by hour. - Deliveries: every delivery with its attempts' requests and responses (signatures hidden), filtered by endpoint, status and type; Resend. - Events: the account's events, with the deliveries of each. ### REST API https://api.lumicloud.ai/v1/webhooks/ does everything the console does. Its OpenAPI description is at https://api.lumicloud.ai/v1/webhooks/openapi.yaml. - Authentication: Authorization: Bearer lumi_sk_..., an account API key made on the account page. Scope webhooks:read reads; webhooks also creates, changes, deletes and reveals secrets. - Paths: /event-types, /endpoints, /endpoints/{id}, /endpoints/{id}/secret, /endpoints/{id}/secret/rotate, /endpoints/{id}/test, /endpoints/{id}/stats, /deliveries, /deliveries/{id}, /deliveries/{id}/resend, /events. - Idempotency-Key on creating an endpoint, rotating a secret and resending: a repeat within 24 hours gets the first answer. - Lists are {"data": [...], "next_cursor": ...}; limit is 1 to 100. Errors are {"error": {"code", "message"}}. - 20 requests a second per key. ```bash curl https://api.lumicloud.ai/v1/webhooks/endpoints \ -H "Authorization: Bearer $LUMI_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://example.com/hooks", "filters": ["sandbox.lifecycle.*"]}' ``` ### Limits and retention An account can have 10 endpoints, active or not; creating one more is refused (409 endpoint_limit). Events, deliveries and attempts are kept for 30 days, then deleted. ### Errors - 400 invalid_request, bad_url (an address the rules refuse), unknown_event_type. - 401 unauthenticated; 403 forbidden, insufficient_scope. - 404 not_found; 409 endpoint_limit, endpoint_disabled. - 429 rate_limited, too_often (examples and resends have their own limit). ## Limits and billing Prices, limits, and what happens when the balance runs out. ### Prices | Resource | Price | | --- | --- | | vCPU | $0.035 per hour | | Memory | $0.012 per GiB per hour | A sandbox is charged for its running time, measured to the millisecond, at the vCPU and memory of its template. Paused sandboxes are not charged for running. Usage is charged to the account's balance once a day, at midnight Singapore time. ### Storage Paused sandboxes are kept until you delete them (in the console, or with the SDK's kill). The storage of your paused sandboxes' snapshots and of your own templates is charged by the hour at $0.080 per GiB per month, beyond the plan's free storage; data that a sandbox shares with your template, or a forked sandbox with its parent, counts once. Public templates are never charged. The console's usage page shows what you store and what it costs. ### Plans Both plans have the same prices and open outbound network (outbound mail and UDP other than DNS blocked). | | Base | Pro | | --- | --- | --- | | Monthly fee | None | $29, including $29 of usage | | Sandboxes at once | 10 | 50, more on request | | Size of a sandbox | Up to 4 vCPU, 8 GiB | Up to 8 vCPU, 16 GiB | | Longest run | 1 hour | 24 hours | | Disk | 5 GiB | 20 GiB | | Free storage | 5 GiB | 20 GiB | | Templates of your own | Public templates only | 2 builds at once | Pro is billed monthly from your balance; cancel any time. Its fee includes $29 of usage each month; usage beyond it is charged at the same prices. ### Opening the service - Verify a card in the console: $1 is charged and given back at once. The account starts on Base. - New customers get $20 of credit after verifying a card, to use within 30 days. - Usage is charged to the prepaid balance; top it up on the console's billing page. ### When the balance runs out Running sandboxes are paused and none can be created or resumed; nothing new is charged meanwhile, storage included. Paused sandboxes are kept for 7 days, with reminders 3 days and 1 day before they are deleted. A top-up resumes the service. ### Errors - More sandboxes than the plan's limit at once: 429. - A template bigger than the plan's size of a sandbox: 400, with the reason. ### Service status [status.lumicloud.uk](https://status.lumicloud.uk) shows whether the sandbox API, the MCP server, the console and the website are up, checked every minute from outside our platform, with incidents and scheduled maintenance as we post them. - Follow it: [Atom feed](https://status.lumicloud.uk/feed.atom). - For monitoring tools and agents: [https://status.lumicloud.uk/api/v2/summary.json](https://status.lumicloud.uk/api/v2/summary.json), in Atlassian Statuspage's format (`status.indicator` is `none` when all is well).