plimsoll trainer · 09 / private api lab
When a language model asks which warehouses are short on stock, which process calls which? This page follows the actual messages from the model to the application hosting it, which speaks MCP (Model Context Protocol, the open standard an AI application uses to offer tools to a model), then through a Node gateway (the company's web server) and a Go dataplane (the service that does the real work), into plimsoll, and back out to a private inventory API. Stockroom is a worked example, not a product. Every process boundary and every message on the wire below is real; only the company is invented.
The one sentence. run_javascript is the MCP tool.
inventory.warehouses.list() is a global function inside the
guest, the isolated process that runs the JavaScript the model wrote.
GET /v1/warehouses is a route in the Node gateway. They are three different things, and confusing them is
how a private API accidentally becomes a public one.
Every card is a process, an external service, or a named layer inside a process. Every line between cards is a message. Two ways to ask for the same stock data end at the same system of record, the vendor system that holds the real stock counts, and pass through different processes on the way. In code mode the model writes a short program that calls the inventory API, and plimsoll runs it in a sandbox; the program's API calls go through the broker, the part of plimsoll outside the sandbox that makes each call and holds the credential. With a direct tool, the model calls one ready-made tool and plimsoll is not involved.
For code mode, also pick where plimsoll runs: embedded as a Go package, or as plimsolld, the plimsoll daemon, reached over Connect (an RPC framework that serves typed procedure calls over ordinary HTTP). Then pick the provider, the backend that runs the code. Each provider reports an isolation tier, how strong the wall around the run is, from process (weakest) through container and kernel to vm:
docker / runc: a container under runc, Docker's default
runtime, which shares the host's kernel (container tier).docker / runsc: a container under runsc, the runtime of
gVisor, a layer that answers the container's requests to the kernel itself
(kernel tier).wasm: a JavaScript engine compiled to WebAssembly, a
portable bytecode format, running inside the plimsoll process (process tier).e2b: a small virtual machine on E2B, a hosted service
(vm tier). When the run has a grant, permission to call listed routes of
one API, the VM's only network exit is plimsoll's guard, an HTTPS address
on the plimsoll daemon that hands each call to the broker.The path
Where plimsoll runs
The provider
Not drawn: dockercloud, the other vm-tier provider. Its grant path is the E2B picture with one difference: the guest holds its own run’s short-lived guard credential, because Docker’s proxy cannot inject one for plimsoll’s guard. The API key still stays outside the VM. Nor openshell, whose guest reaches the broker through a relay in the sandbox that plimsoll dials into, so its sandbox keeps no network rules at all.
caller infrastructure Stockroom code plimsoll untrusted guest
MCP is the protocol the application hosting the model uses to call an operation registered on a server. The guest global is JavaScript that exists only after plimsoll has started the isolated guest. The REST route is a private endpoint in the gateway.
Pick one.
A protocol is the contract between two sides: where the bytes go, what shape they have, who answers, and what the receiver does next. Pick a hop, one step from one process to the next. "stdio" means the host starts the MCP server as a child process and talks to it over its standard input and output. The Connect hops carry protobuf messages, in Google's schema-defined binary format.
The model, the MCP connection, the guest and the private API each see a different part of the same call.
run_javascript with an input schema: code, timeoutMs.stockroom://sandbox-api.d.ts, the TypeScript declarations of those globals.tools/call request (JSON-RPC is the request format MCP uses) with the code as a string argument, over Streamable HTTP (MCP's HTTP transport) or stdio.inventory.* (the preamble, a small library placed before the model's code) built on host.* (the generic client that calls the broker).GET /v1/warehouses with a per-run JWT (a signed token) whose subject is the principal, the authenticated caller.Stockroom keeps its own inventory API and its MCP server. plimsoll adds the controlled middle: a place where code an agent wrote can loop over, filter and combine private data, while the API's address, the list of allowed routes, the caller's identity, the token, the network boundary and the audit line all stay outside the guest.
inventory.items.counts(id) can sit inside a loop or a condition. The model does not need one MCP round trip per item, and the efficiency advisor tells it when the loop should have been one call.
The guest sees typed helper functions. plimsoll holds the private API's address and the per-run credential, and allows only the listed routes.
The MCP description and stockroom://sandbox-api.d.ts explain what the model can call. This page explains what each process sends to the next.