docs: Iron.sh and the Architecture of the Untrusted Root

How a network-level 'Secret Proxy' and egress-secured sandboxes are solving the AI agent security dilemma.

A transparent glass safe with a projection of an orb inside, while a robot hand reaches for it but grasps nothing. This illustrates the concept of a Secret Proxy where the agent never holds the actual key. — The agent uses the power without ever holding the substance.

Key Takeaways

Iron.sh prevents credential theft by swapping placeholder tokens for real API keys at the network bridge level.
The platform secures untrusted agents by moving egress enforcement from the guest operating system to the external hypervisor.
A specialized CLI manages the lifecycle of ephemeral sandboxes to ensure every agent task runs in a clean environment.
The documentation architecture utilizes OpenNext to deploy Next.js App Router features directly to Cloudflare Workers.

The Ghost in the Machine: Secret Proxying

The most counter-intuitive technical feat in the Iron.sh architecture is its approach to API keys. An autonomous agent can utilize an OpenAI key that does not exist in its environment variables or memory. This is achieved through a mechanism called the Secret Proxy.

Instead of injecting real credentials into the virtual machine, Iron.sh provides placeholder tokens prefixed with IRONSH_PROXY_. When the agent makes an outbound HTTP request, the network bridge intercepts it. The bridge identifies the placeholder, verifies the destination, and swaps in the actual secret before the packet leaves the host.

The network bridge intercepts and replaces proxy tokens with real secrets in-flight.

Security from the Outside In

Traditional sandboxing secures the boundary from within the operating system using tools like iptables. The flaw in this model is that if an AI agent gains root access, it can rewrite the rules. Iron.sh shifts the enforcement boundary to the hypervisor.

By placing the firewall at the network bridge level, the sandbox is secured from the outside in. Even a fully compromised, root-access virtual machine cannot bypass the egress rules because the enforcement mechanism is physically inaccessible to the guest operating system.

Feature	Standard Sandbox	Iron.sh Model
Secret Storage	Environment Variables	Network-Layer Injection
Egress Control	Internal OS (iptables)	External Bridge Enforcement
Identity	Static API Keys	Proxy Placeholders
Recovery	Standard Snapshotting	Native State Snapshots

Egress enforcement happens at the bridge ring, making it impossible for a compromised guest OS to bypass.

Engineering the Edge: Nextra and OpenNext

The documentation repository itself reflects a sophisticated engineering approach. Rather than relying on standard static site generators, the team built their docs using Nextra 4 and deployed them to Cloudflare Workers.

This is achieved through OpenNext, a transformer that allows Next.js App Router applications to run outside of Vercel. By deploying to the edge, the documentation maintains the benefits of React Server Components while avoiding vendor lock-in and ensuring high availability.

The Lifecycle of a Disposable Sandbox

The developer experience revolves around the irons CLI. Sandboxes are treated as entirely disposable infrastructure. They are spun up, utilized for a specific agent task, audited, and destroyed.

irons create agent-env
irons ssh agent-env
# Agent executes untrusted code
irons audit agent-env
irons destroy agent-env

To ensure absolute reliability during automated provisioning, Iron.sh bypasses standard Ubuntu package mirrors in favor of mirrors.kernel.org. This prevents a simple CDN 404 error from breaking an autonomous agent's workflow.

An assembly line producing identical mechanical birds. A giant claw drops one into a furnace while another is instantly calibrated, illustrating the disposable nature of the sandboxes. — Sandboxes are designed to be ephemeral, created and destroyed precisely when needed.