plimsoll

plimsoll runs untrusted code, reminiscent of code an AI agent wrote, inside a sandbox, and
each end result says how sturdy that sandbox was. A request can demand a minimal energy;
if the sandbox is weaker, nothing runs.

The identify comes from the Plimsoll line, the load restrict painted on the skin
of a ship’s hull the place anybody can examine it. plimsoll does the identical for the
isolation tier: how sturdy the wall round a run is, said as one among 4
ranges, weakest first: course of, container, kernel, vm. The tier is a price on each
end result, not a sentence in a datasheet. A request can set a flooring, the weakest
tier it is going to settle for, and the official Go shopper checks the tier once more when the end result
comes again.

The identical equipment lets plimsoll run an examination on code an agent wrote, not solely comprise
it. A trial runner constructed into the simulation picture runs the agent’s program in opposition to
situations that program can not learn: every one reaches the runner in a file deleted earlier than
this system begins. Every run returns SHA-256 hashes of the request as despatched and the
end result as returned, which the official shoppers recompute (how). A
separate program outdoors the daemon, plimsoll-attest, indicators
the checked outcomes, refuses a sequence of calls with one lacking, and replays a run. The
examination itself (the simulated system, the situations, the cross mark) stays yours: plimsoll
provides the boundary and the proof.

An AI agent wrote a controller: a program that reads a system’s state at
each tick (right here, one 10 ms step of the simulation) and decides the way to push it. plimsoll
ran it in opposition to a simulated cart-pole, a cart on a rail with a pole hinged on
high, which the controller retains upright by pushing the cart left and proper. The simulator
is compiled to WebAssembly, a transportable bytecode that runs inside a bunch program,
and constructed into the sandbox picture. The controller was the one file the caller despatched, by way of
the atypical mission API, and it ran on the container tier.

The cart-pole is the usual instructing drawback in management engineering. The runner, a
program constructed into the picture that runs the controller in opposition to the simulator, information
the run’s trajectory, each state at each tick, and hashes it right into a
fingerprint: a SHA-256 hash, so equal fingerprints imply equivalent numbers. Run
the accepted controller twice and the 2 fingerprints match. The agent’s first draft had
two good points (multipliers in its formulation) with the incorrect signal: it drops the pole at 5.96
seconds, and its fingerprint differs.

Open the live run report ↗
to replay each runs within the browser, learn the controller the agent wrote, and see what the
web page intentionally doesn’t declare. One execution of the instance makes three sandbox runs: the accepted
controller twice and the draft as soon as. Reproduce them with
make docker-images && go run ./examples/oracle.

It studies the wall. Every end result states the isolation tier the run truly bought.
Every request can set a flooring, and a request whose flooring the daemon can not meet is refused
earlier than any code runs: ErrInsufficientIsolation means nothing ran.

res, err := supplier.Sandbox.RunJavaScript(ctx, sandbox.Request{
    Code:             "console.log(6 * 7)",
    MinimalIsolation: sandbox.IsolationVM, // ErrInsufficientIsolation means nothing ran
})
// res.Isolation studies the boundary that really ran.

Every refusal that ran nothing is marked as one, with a purpose (request, permission,
protocol, unsupported, isolation, setting, capability). sandbox.NotDispatchedReason(err)
reads the mark, whether or not the supplier (the backend that runs the code) is in
your individual course of or behind the daemon. An error with out the mark might have come after the
code began, so it’s by no means protected to retry robotically. A mark counts solely on a solution
that carries the shopper’s request ID again, so a proxy that serves one request’s reply
for one more can not make a name that ran learn “nothing ran”
(what comes back, and what it means).

The tier is proof the daemon collected: its configuration and its personal startup checks.
It will not be attestation, cryptographic proof from the {hardware} of what software program
is working, and no supplier right here affords that.
docs/isolation-tiers.md lists what every tier rests on.

It lets agent-written code name your API with out ever holding your credential, your
API’s handle, or open community entry. A grant offers one run permission to
name listed routes of 1 API. The code calls by way of a small shopper plimsoll places within the
sandbox, and the dealer, the a part of plimsoll outdoors the sandbox that makes
the true name, checks the caller and the precise route, then attaches the credential itself.
The credential is minted per run: plimsoll asks for it as soon as per run, so it may possibly
be a contemporary short-lived token, and it by no means enters the sandbox. Code that skips the shopper
and calls out by hand will get no additional, as a result of the dealer, not the shopper, enforces the
guidelines. See docs/capability-grants.md.

These agent frameworks can hand their mannequin’s code to plimsoll by way of a software or code
executor of their very own (Trigger.dev, one among them, is a hosted TypeScript job
runner). Each row names what to put in, the information, and a web page that replays recorded calls
from that framework’s software to a sandbox and again, refusals included.

The TypeScript add-on offers an
executeCode software to a chat agent on Trigger.dev. On a daemon with a session, one sandbox stored
for a number of calls, every name is a cell, code run contained in the
interpreter stored for that dialog:
variables and recordsdata can survive the following name. Each software end result says whether or not
they’ll survive, whether or not this name began contemporary, the isolation tier it ran
behind, and the SHA-256 of the run report, a receipt for what was
despatched and returned that the shopper checked earlier than returning. The caller units a
minimal tier, so a weaker supplier refuses earlier than working code.

See the feature and deployment guide for the precise
ensures and manufacturing flooring. The
deployable Trigger.dev starter
has a chat agent and a job that proves two cells share one interpreter by way of
an actual daemon, with out making an AI mannequin name.

The instance wants no daemon, no docker, no credentials and no community: it makes use of the wasm
supplier, which runs JavaScript on QuickJS, a small JavaScript engine
compiled to WebAssembly, inside your individual course of. Cloning and fetching Go modules do use
the community.

git clone https://github.com/plimsollmark/plimsoll && cd plimsoll
go run ./examples/minimal

supplier   wasm
isolation  course of
exit code  0
timed out  false
truncated  stdout=false stderr=false
length   304ms
stdout     {"Engineering":59000000,"Sales":20300000,"Operations":9800000}

The isolation line comes from the run’s end result, not from the instance’s personal textual content.
course of means there isn’t any operating-system wall in any respect: don’t use it for hostile
code. The identical snippet runs on the kernel tier as soon as gVisor is put in.
gVisor is a layer between a container and your machine’s kernel that handles the
container’s requests to the working system itself, so the code by no means talks to your
kernel instantly. sudo ./docker/install-gvisor.sh installs a pinned gVisor
launch (one precise model, modified solely by modifying this repository) and registers its
runtime, runsc, with docker. Nothing else about this system modifications:

make docker-images   # builds the mission picture (plimsoll/sandbox) the docker supplier checks for
SANDBOX_PROVIDER=docker SANDBOX_DOCKER_RUNTIME=runsc go run ./examples/minimal

With SANDBOX_PROVIDER unset, plimsoll makes use of the Disabled supplier, which runs nothing, so
code execution isn’t on by chance.

Next: docs/getting-started.md walks by way of the identical items
on one machine: begin the daemon, create a caller credential, write your individual shopper, watch
a flooring refuse a run, then transfer the daemon from course of to kernel with out altering the
shopper. It additionally covers embedding the Go package deal as an alternative of working the daemon.

flowchart LR
  A["Agent or MCP gateway (MCP: how an AI app offers tools to a model)"] -->|"Run: one payload, a protocol quantity, minimum_isolation"| AU

  subgraph D["plimsolld"]
    AU["authenticate the caller"] --> FL["compare the floor with current provider evidence"]
    FL --> DI["dispatch"]
    BR["broker: holds the minted credential, matches the exact route, counts every call"]
  finish

  DI --> W["wasm: QuickJS on wazero (process tier)"]
  DI --> Ok["docker with runsc (kernel tier)"]
  DI --> V["e2b Firecracker (VM tier)"]

  W -. "host.get / host.publish" .-> BR
  Ok -. "per-run Unix socket" .-> BR
  V -. "authenticated guard" .-> BR
  BR ==> |"your credential, connected host-side"| API["Your API"]

The code contained in the sandbox, the visitor, by no means holds the credential and by no means
reaches the community instantly. A run with no grant has no community in any respect.

plimsolld is the plimsoll server. Each one runs precisely one supplier, chosen by
SANDBOX_PROVIDER:

Each tier rests on the daemon’s configuration, what the supplier studies, and an actual take a look at
run at startup; none is attestation. docs/isolation-tiers.md
lists the proof for every tier and reveals how a request units its flooring. A session trades
the contemporary sandbox of each name for velocity and stored state: code an earlier name ran can
change what later calls see, and a name with API entry wants a grant that permits periods
(docs/sessions.md). A session is one belief
area, and plimsoll ties it to the authenticated caller, to not that caller’s clients:
a service that runs many shoppers’ code by way of one credential should preserve every buyer
in a session of their very own
(who may share a session). The docker
supplier also can apply the shipped seccomp profile, an inventory of the one
system calls (requests to the kernel, reminiscent of opening a file) its containers
might make (docs/seccomp.md).

• Pre-1.0, single writer, no exterior customers but. Breaking modifications land and not using a
  deprecation path, on goal.
• No third-party safety audit has ever been carried out, and the writer’s personal
  self-review ledgers should not revealed both. SECURITY.md says what
  exists, what it’s price, and what you possibly can examine your self as an alternative.
• CI runs the gate, within the open, and every examine means what it ran. The
  audit workflow has three jobs. audit runs plain
  make audit on each push to essential and each pull request: construct, vet, race exams, lint,
  buf lint, a generated-code drift examine, and govulncheck. After audit, shoppers
  runs make clients-suite: npm ci in shoppers/typescript and
  examples/trigger-chat, then the Python and TypeScript Go take a look at packages in
  required mode. A lacking runtime, dependency or skipped Go take a look at fails that job.
  audit-docker additionally follows audit and
  runs make docker-suite with the photographs ready, in required mode: a lacking
  daemon, a lacking picture or a skipped take a look at fails the job. A inexperienced audit-docker
  due to this fact means the docker suite ran below runc with the shipped seccomp profile
  and proved a read-only root, sized noexec writable mounts, and the dealer’s
  refusals. The gvisor workflow runs the identical suite
  below runsc, the kernel tier, from the pinned installer. The race detector runs in
  the plain audit job and each docker-suite jobs; the shopper job runs with out it.
  No examine workouts E2B or Docker Cloud Sandboxes: these suites drive dwell paid companies and are
  intentionally by no means wired to a runner. See CONTRIBUTING.md.

The interactive lessons are the
quickest approach in in the event you would reasonably learn than clone. Start with
Plain English
for the concept earlier than the API, or
Quick start to run
one thing. Every time period these docs use has a one-sentence definition within the
glossary. The classes
dwell in docs/trainers/ and work offline: open any file from a clone in a
browser. GitHub reveals .html recordsdata as supply as an alternative of rendering them, which is why the
hyperlinks above level on the revealed copy.

Each of those solutions one query, finish to finish.

Apache-2.0.