Plimsoll: Enforcing Isolation Tiers for Untrusted AI Agent Code

Overview

A new open-source project called plimsoll aims to bring rigorous isolation guarantees to the execution of untrusted AI agent code. By treating computational boundaries like a ship’s load line, the system ensures that software generated by autonomous agents can run safely without exposing host systems or sensitive credentials.

The tool is designed for developers who need to trust the output of AI agents without trusting the underlying execution environment. It addresses a growing security concern: as AI agents gain the ability to write and execute their own code, the risk of malicious or buggy scripts compromising production infrastructure increases significantly.

Plimsoll operates as a sandboxing layer that not only contains code but also provides verifiable evidence of the isolation tier used during execution. This approach allows organizations to set minimum security thresholds and reject requests that do not meet them before any code runs.

Enforcing Isolation Tiers

The project derives its name from the Plimsoll line, a marking on a ship’s hull that indicates the maximum safe draft. Similarly, plimsoll assigns an isolation tier to every code execution, representing the strength of the barrier around the running process.

There are four distinct tiers, listed here from weakest to strongest:

• Process: Basic operating system process isolation.
• Container: Container-level separation, typically using namespaces and cgroups.
• Kernel: Deeper kernel-level isolation mechanisms.
• VM: Full virtual machine isolation, offering the highest degree of separation.

Every result returned by the system explicitly states the isolation tier that was actually used. This is not vague documentation but a structured value attached to the execution response. Consequently, callers can set a minimum isolation floor in their requests.

If the backend provider cannot meet this threshold, the request is refused immediately with an ErrInsufficientIsolation error. No code is executed in such cases, ensuring that sensitive operations never happen in environments deemed too weak.

res, err := provider.Sandbox.RunJavaScript(ctx, sandbox.Request{
    Code: "console.log(6 * 7)",
    MinimumIsolation: sandbox.IsolationVM,
})
// If err is ErrInsufficientIsolation, nothing ran.

Errors are categorized with specific marks, such as request, permission, protocol, unsupported, isolation, environment, and capacity. A client can use the sandbox.NotDispatchedReason function to distinguish between errors that occurred before execution started and those that happened during it. This distinction is critical for implementing safe retry logic, as automatic retries are only safe when no code has been dispatched.

It is important to note that the tier reporting is based on configuration and startup checks, not cryptographic attestation. The system does not currently offer hardware-backed proof of the software state, but it does provide a clear, auditable record of the isolation boundary used.

Verifiable Execution and Testing

Beyond simple containment, plimsoll allows for rigorous testing of agent-written code. It includes a trial runner within the simulation image that executes agent programs against predefined scenarios. These scenarios are delivered via files that are deleted before the program starts, ensuring the agent cannot cheat by reading the test cases directly.

To prevent tampering and ensure reproducibility, every run generates SHA-256 hashes for both the incoming request and the resulting output. Official Go clients recompute these hashes to verify integrity. A separate utility, plimsoll-attest, can sign these checked results, creating a verifiable chain of evidence.

This capability is demonstrated through a real-world example involving a cart-pole control problem. In this standard control engineering simulation, an AI agent wrote a controller program responsible for keeping a pole upright on a moving cart.

The controller was executed inside a sandbox at the container tier. The simulator, compiled to WebAssembly, was embedded within the sandbox image. The agent’s code was the only external input provided.

The system recorded the trajectory of the cart and pole at every tick—10 milliseconds in this setup—and hashed the entire sequence into a fingerprint. When the same accepted controller was run twice, the fingerprints matched perfectly, confirming deterministic behavior.

Conversely, the agent’s initial draft, which contained sign errors in its control gains, failed to balance the pole. Its resulting trajectory produced a different fingerprint, providing objective proof that the code was flawed. Users can replay these runs in a browser to inspect the controller code and observe the divergence between successful and unsuccessful executions.

Secure API Integration

A significant vulnerability in AI agent systems is the exposure of API credentials. If an agent writes code that directly calls external services, it may inadvertently or intentionally leak secrets, access unauthorized endpoints, or make unrestricted network requests.

Plimsoll solves this through a grant and broker architecture. A grant gives a specific run permission to call only a listed set of API routes. The agent’s code interacts with a small, restricted client provided by plimsoll within the sandbox.

The actual network call is made by the broker, a component of plimsoll that resides outside the sandbox. The broker validates the caller and the exact route against the grant before proceeding. It then attaches the necessary credentials itself.

This design ensures that the sandboxed code never holds the credential, never knows the API address, and has no open network access. Furthermore, credentials are minted per run, meaning plimsoll requests a fresh, short-lived token for each execution. This limits the blast radius of any potential compromise.

Code that attempts to bypass the provided client and reach out directly is blocked by the sandbox environment. This architecture allows organizations to empower AI agents with API access while maintaining strict control over what they can call and how they authenticate, effectively sealing off sensitive infrastructure from untrusted generated code.