Skip to Content
OrbixDocs
Block SDK · Concepts

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 kindHow Orbix detects itExecution environmentHow it talks to Orbix
SDK React blockImports @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 appUses index.html or createRoot with no @orbixdocs/sdk imports or hook callsOpaque-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 entryCross-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

  1. VirtualBundler transpiles TypeScript and JSX in the browser using Sucrase.
  2. Before evaluation, static regex guards reject direct eval, new Function, .constructor.constructor, and __proto__ access.
  3. Modules execute via new Function with shadowed globals (window, document, globalThis, fetch, XMLHttpRequest, navigator).
  4. Outbound network calls pass through orbixEgressFirewall, and SDK hooks (useOrbixDocument, useOrbixWorkspace, useOrbixDatabase, usePersistentStorage, useOrbixAI, useOrbixWorker) check capabilityEngine against 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.com is a separate site from app.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/_headers serves /runner.html with Origin-Agent-Cluster: ?1 and a strict HTTP Content Security Policy (connect-src blob: data:; frame-src 'none').
  • On localhost or when offline, OrbixHtmlFrame falls back to an inline srcdoc iframe without allow-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 postMessage checks event.source === iframe.contentWindow and 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, and sendBeacon are routed to the host's hostFetch broker, which checks manifest.capabilities.network.domains and enforces a 10 MB payload limit, 30 s timeout, 8 concurrent requests per block, and credentials: 'omit'.

On this page