Introduction

Ever wanted to embed an interactive AI playground on your website so users can try out your model or app in real-time? The Sandbox AI Protocol (SAIP) makes this possible. SAIP powers Trialrun.dev, a platform that provides sandboxed, embeddable AI playgrounds. It enables developers to deploy AI apps in isolated containers and seamlessly embed them as widgets on any site, offering users a low-latency, safe trial run of the AI. Inspired by the handshake approach of WebRTC (where peers use a central server to find each other, then communicate directly (Signaling and video calling - Web APIs | MDN)), SAIP ensures that once the connection is set up, interactions are fast and direct between the user’s browser and the AI sandbox. This litepaper gives an accessible, product-focused overview of how SAIP works and why it matters for developers, users, and open-source contributors.

What is SAIP? In simple terms, SAIP is a protocol and system architecture for running AI apps in secure sandboxes and embedding them as interactive widgets on websites. Each sandbox is a Docker-powered container running an AI application (such as a Model Context Protocol server) in isolation. A central service coordinates all sandboxes and clients: it tracks sandbox configurations and acts as a broker for initial handshakes. Once handshakes are done, the user’s widget talks directly to the sandbox container’s API, eliminating middleman latency. The result: users get a responsive experience, and developers get peace of mind that their AI backend is contained and secure. In the sections below, we’ll dive into how SAIP works, its system architecture, a step-by-step example flow, and the future vision for this approach.

How It Works

At a high level, SAIP uses a handshake protocol between three parties: (1) the sandbox container that runs the AI app, (2) the central SAIP API (with its database), and (3) the embedded widget running in the user’s browser. The process is reminiscent of how WebRTC establishes peer-to-peer connections via a signaling server (Signaling and video calling - Web APIs | MDN). In SAIP’s case, the central API plays a role similar to a WebRTC signaling server – it doesn’t carry the ongoing data, but helps the two ends find each other and exchange configuration details for a secure connection.

Here’s the basic handshake sequence that makes the magic happen:

• Sandbox container deployment: When a new sandbox (Docker container) is spun up (for example, to host an AI model or application), it knows its unique Sandbox ID (usually as an environment variable set when deployed) and its own base API URL (the endpoint where it can be reached).
• Container → Central: On startup, the sandbox container calls home to the central SAIP API, identifying itself by its Sandbox ID and providing its base API URL. This registers the container’s presence. The central database then updates the stored configuration for that sandbox ID with the container’s endpoint (so it now knows where that sandbox lives).
• Client widget → Central: When a user visits a website with an embedded Trialrun.dev widget, the widget initializes and performs its own handshake. It contacts the central API with the sandbox’s ID (this ID would be embedded in the widget code on the site, referencing which sandboxed app to connect to). The central service looks up the sandbox’s configuration in its DB.
• Central → Widget: The central API responds with the sandbox config, which includes details on how the UI should behave and the sandbox container’s API endpoint (provided earlier by the container). Essentially, the widget is told “your sandbox is alive at URL X, and here are the parameters for how to talk to it and render the interface.”
• Direct connection established: Armed with this config, the widget now opens a direct channel to the sandbox container’s API endpoint (e.g. via REST calls or WebSocket, depending on the app). From this point on, the user’s browser communicates directly with the sandbox container, sending user inputs and receiving AI responses, without needing to relay through the central server. This is what makes the experience low-latency and efficient – much like a WebRTC peer-to-peer call after signaling (Signaling and video calling - Web APIs | MDN).

(image) Figure: In the SAIP handshake, the Sandbox Container and the Embedded Widget each communicate with the Central API briefly. The container registers itself (1), and the widget requests the config (2). The central server then provides the widget with the sandbox’s details (3). Finally, the widget and container talk directly via the sandbox’s API (4), enabling real-time interaction.

This handshake process ensures that every sandboxed AI environment is preconfigured and secure before any user interacts with it. The central API acts as a gatekeeper: it only hands out configuration for a valid sandbox ID to authorized widgets, and it only accepts a container handshake if it has a matching pending sandbox ID. Because the actual AI computations happen inside an isolated Docker container, the user can play with the AI model freely without affecting the host website or any other system. For developers, this means you can let users experiment with your AI model (e.g. an NLP tool, a generative art model, or an agent following the Model Context Protocol) in a sandbox that’s fenced off from your production data. For users, it means a safe, sandboxed trial of an AI app with snappy performance.

System Architecture

Let’s break down the key components of the Sandbox AI Protocol architecture and how they work together:

• Central API & Database (SAIP Coordinator): This is the heart of SAIP. It stores all sandbox configurations and states. Think of it as the signaling server in WebRTC terms – it doesn’t handle the heavy load of AI inference, but it coordinates who’s where. The central DB holds records for each sandbox: configuration data (such as UI settings, allowed model parameters, etc.), the Sandbox ID, and (once a container is running) the container’s endpoint URL. The Central API exposes endpoints for containers to register (handshake) and for clients to request configs. It also often triggers the deployment of sandbox containers when new configs are added (more on that soon). Notably, the central server doesn’t need to know the content of AI interactions – just like a WebRTC signaling server only channels connection info, not the actual video stream (Signaling and video calling - Web APIs | MDN) (Signaling and video calling - Web APIs | MDN). This keeps the architecture scalable and focused: heavy AI lifting is offloaded to the containers.
• Sandbox Containers (Docker-powered Sandboxes): Each sandbox is a Docker container running an AI application instance. For example, if you’re offering an AI image generator demo, the container might run a lightweight API serving a model. If it’s an AI agent that follows the Model Context Protocol (MCP), the container runs an MCP Client and several MCP servers specified in the config. (MCP servers are lightweight programs that expose specific AI tool capabilities via a standardized protocol (Introduction - Model Context Protocol).) These containers are launched on demand when an admin creates a sandbox config. They run isolated from each other, providing security (one sandbox can’t interfere with another or with the host system). Upon launch, a container runs a small SAIP client script that performs the registration handshake with the central API, as described earlier. The sandbox continues running, listening for incoming requests from client widgets. Because the sandbox is preconfigured exactly for the intended AI app (with the right model, code, and initial settings), users get a curated, controlled environment to play in.
• Embedded Widget (Client Application): This is the front-end piece that end users interact with. Trialrun.dev provides a snippet or component that developers can embed into any web page. The widget knows which sandbox ID it should connect to (usually specified in the embed code). When loaded in a user’s browser, it calls the central API to fetch the sandbox config (handshake step), then builds the UI according to that config. For example, the config might specify what input fields or examples to show, or any branding for the sandbox UI. Once configured, the widget establishes a direct connection to the sandbox container’s endpoint for all further communication. From the user’s perspective, the widget is like a little app on the webpage where they can type queries or click buttons and get responses from the AI – all powered by the remote sandbox container. The widget handles things like displaying responses, streaming data if needed, and gracefully dealing with errors (e.g., if a sandbox is temporarily unavailable, it might show a message or retry).