How blocks run
Understand the three execution models in Orbix and what each runtime isolates.
Orbix executes custom blocks using three different runtimes depending on how the project is authored. Knowing which runtime executes your code explains how imports resolve, what browser APIs are available, and what security boundaries apply.
The three runtimes
| Block kind | How Orbix detects it | Execution environment | How it talks to Orbix |
|---|---|---|---|
| SDK React block | Imports @orbixdocs/sdk (or calls SDK hooks / exports defineBlock) | Host JavaScript realm via VirtualBundler (new Function with shadowed globals and orbixEgressFirewall) | Direct React hooks (useOrbixState, useOrbixDocument, useBlockInput, etc.) inside OrbixBlockInstanceContext |
| Standard React app | Uses index.html or createRoot with no @orbixdocs/sdk imports or hook calls | Opaque-origin iframe (/\_\_orbix/sandbox.html without allow-same-origin) | Self-contained app; no @orbixdocs/sdk hook access |
| HTML / polyglot block | .html, .py, .svelte, .vue, or .sql entry | Cross-site runner iframe (rb-<hash>.orbixblocks.com/runner.html on HTTPS; opaque srcdoc on localhost) | window.Orbix and <orbix-*> custom elements over postMessage RPC (authorizeHostRpc) |
1. SDK React blocks (@orbixdocs/sdk)
Most interactive blocks authored with @orbixdocs/sdk fall into this category.
How it runs
VirtualBundlertranspiles TypeScript and JSX in the browser using Sucrase.- Before evaluation, static regex guards reject direct
eval,new Function,.constructor.constructor, and__proto__access. - Modules execute via
new Functionwith shadowed globals (window,document,globalThis,fetch,XMLHttpRequest,navigator). - Outbound network calls pass through
orbixEgressFirewall, and SDK hooks (useOrbixDocument,useOrbixWorkspace,useOrbixDatabase,usePersistentStorage,useOrbixAI,useOrbixWorker) checkcapabilityEngineagainst the mounted instance ID.
Why it runs in the host realm — and its limits
Running SDK React blocks inside the host React tree lets hooks read OrbixBlockInstanceContext, share synchronous layout and focus with the document editor, and update state without iframe serialization delay.
What it is not: VirtualBundler is not a separate V8 isolate or cross-origin browser process. Shadowed globals, static guards, capabilityEngine, and orbixEgressFirewall enforce permissions for cooperative and accidental misuse, while untrusted HTML, Python, Svelte, Vue, and SQL code is placed into the separate browser-origin iframe described below.
2. Standard React apps (/\_\_orbix/sandbox.html)
If you create a multi-file React project in Block Studio with index.html or ReactDOM.createRoot(...) and zero @orbixdocs/sdk imports, Orbix mounts it inside StandardAppBlock:
<iframe
src="/__orbix/sandbox.html"
sandbox="allow-scripts allow-forms allow-popups allow-pointer-lock allow-downloads"
/>Because allow-same-origin is omitted, the browser assigns the iframe a unique opaque origin (null). It cannot read app.orbix.so cookies, localStorage, or IndexedDB, and it cannot call @orbixdocs/sdk hooks.
3. HTML and polyglot blocks (orbixblocks.com)
Blocks written in .html, Python (.py), Svelte (.svelte), Vue (.vue), or SQL (.sql) run inside OrbixHtmlFrame.
Cross-site origin isolation in production
On production HTTPS (app.orbix.so), perBlockRunnerOrigin(blockId) derives a deterministic 32-hex-character SHA-256 subdomain on the separate orbixblocks.com eTLD+1 domain:
https://rb-<sha256("orbix-runner-origin:v1:" + blockId)[0..32]>.orbixblocks.com/runner.html- Because
orbixblocks.comis a separate site fromapp.orbix.so, browser Same-Origin Policy and Site Isolation prevent the frame from reading workspace cookies, storage, or DOM, and two different blocks do not share an origin with each other. public/_headersserves/runner.htmlwithOrigin-Agent-Cluster: ?1and a strict HTTP Content Security Policy (connect-src blob: data:; frame-src 'none').- On
localhostor when offline,OrbixHtmlFramefalls back to an inlinesrcdociframe withoutallow-same-origin(giving an opaque origin).
Host RPC and mediated network calls
Inside runner.html, code interacts with Orbix through postMessage RPC verified on the host:
- Every incoming
postMessagechecksevent.source === iframe.contentWindowand matches the expected runner origin. - Every RPC method passes through
authorizeHostRpc(method, params, blockId)before touching state, storage, documents, ports, or AI. Denied calls reply with{ error, code: 'CAPABILITY_DENIED', capability }. - Because
connect-src blob: data:blocks direct network access from the iframe,fetch,XMLHttpRequest, andsendBeaconare routed to the host'shostFetchbroker, which checksmanifest.capabilities.network.domainsand enforces a10 MBpayload limit,30 stimeout,8concurrent requests per block, andcredentials: 'omit'.