D-102 Start
How it works
The agent runs in a sandbox on your machine. A policy decides what it can read, write, and reach. Boundlane writes that policy, starts the sandbox, and keeps the record.
The pieces
The sandbox is OpenShell, an open source runtime licensed under Apache 2.0. Boundlane does not replace any part of it. We pin a version and drive it through its own commands. The sandbox holds the agent process. It does not hold the model weights.
| Piece | Where it runs | What it does |
|---|---|---|
| Boundlane CLI | Your machine | Compiles the policy, checks it, starts the sandbox, copies the project in and out, files approvals, reads the log. |
| Gateway | Your machine | OpenShell's control process. Holds sandboxes, policies, and credentials for this machine. |
| Supervisor | Inside each sandbox | Applies the filesystem and process rules at start, and runs the proxy every network call goes through. |
| Agent | Inside the sandbox | Claude Code, Codex, or another agent, running as an unprivileged user. |
| Control plane | Our cloud, Team only | Holds the org policy, the approval queue, and the decision log. Never connects to your machine. |
What is inside the sandbox
- The agent's image. Built on your machine from a Dockerfile we publish, with the agent,
git, and common tools. We do not redistribute agent binaries. - A copy of your project. Uploaded at start, respecting
.gitignore. The agent edits the copy. You apply the changes when it exits. - Nothing else from your machine. Your home directory is not there, so
~/.aws,~/.ssh, and your shell history are not there either. Only what is uploaded or built into the image exists. - Placeholders instead of keys. The agent's environment holds a placeholder. The real key is added by the proxy, only on requests that the policy allows and only to the endpoints that key belongs to.
Inside, the project folder and /tmp are writable. System folders such as /usr and /etc are read-only. Anything not listed is not reachable at all. The cloud metadata address and other link-local and loopback destinations are never reachable through the network policy.
Walls and doors
Some parts of the policy are fixed when the sandbox starts. Others change while it runs. Boundlane always tells you which kind of change you are making.
| Change | Kind | What happens |
|---|---|---|
| A host added or removed | Door | Applied to the running sandbox as a new revision. The sandbox loads it on its next poll, within seconds. |
| An approved request | Door | Same as above. The agent retries and the call goes through. |
| A path made readable or writable | Wall | The current sandbox ends. The next run creates a new one with the new paths. |
| The user the agent runs as | Wall | Same as above. |
No running sandbox picks up a filesystem change. When a wall moves, Boundlane says the sandbox will be recreated before it does it. It never hides a restart behind a saved message.
When network rules change, open WebSocket connections in the sandbox are closed and clients must reconnect. Plain HTTP requests are not affected.
Keys and tokens
Model keys and GitHub tokens are stored by the gateway on your machine, as OpenShell providers. boundlane key set stores one, or boundlane run creates it from your environment the first time you run an agent. They are never sent to our cloud, on any plan.
Each key is bound to the endpoints it belongs to. A network rule that lets the agent reach a host does not let the key go there. If the agent sends the placeholder to a different host, the request is denied.
What reaches the model
The agent's calls to its model are allowed, because the agent cannot work without them. Whatever the agent puts in a prompt leaves the machine that way: the files it read, command output, and your instructions. The sandbox limits what the agent can read and where else it can connect. It does not read or filter prompts.
Claude Code's web search goes the same way. Anthropic runs the search, so the query travels inside a model call, and the sandbox cannot block it without blocking the model. Fetching a result page from the sandbox is still refused. See Web search.
The log
The sandbox records every network decision, and the gateway on your machine keeps a stream of them. boundlane log reads that stream while a sandbox runs. When the agent exits, Boundlane saves a copy before it asks whether to delete the sandbox. The save has to come first: deleting the sandbox deletes the gateway's copy.
Each line in the stream is one decision, as text: the time, allow or deny, the program, the destination, and the rule. A deny includes the sandbox's reason. Query strings are left out. The stream does not carry the full audit file the sandbox writes for itself, and that file cannot be read from outside the sandbox. boundlane log and a Team record are both built from these lines. A blocked file write is in neither. The agent sees Permission denied.
On Team, a program on the machine follows the same stream for every sandbox Boundlane started. It remembers its place. After a disconnect it asks for decisions after that place, so each one is uploaded once. If the gateway restarted, or its buffer no longer holds that place, the missed decisions are gone. The machine reports a gap, and the console shows it for that sandbox and that span of time. See what Team receives.
When our cloud is unreachable
The sandbox keeps enforcing the last policy it loaded. That does not depend on us. On Team, the CLI uses the last signed policy it verified. Decision records wait on the machine and upload when the connection returns. If the gateway still has the decisions from the gap, they upload once. If it does not, the console shows a gap instead of a continuous log. If the local queue fills, the CLI says how many records were dropped.
Requests for more access stay pending while the control plane is down. The blocked call stays blocked. An enrolled machine that has never received a policy refuses to start a sandbox instead of falling back to the Free default.
If the sandbox itself cannot load a new policy revision, the gateway's setting decides: fail_closed blocks network traffic, and retain_last_valid keeps the last valid policy. boundlane doctor shows which one is set.
What a laptop cannot enforce
You own your laptop and the gateway on it. You can run OpenShell directly, approve your own requests, or delete a sandbox. Boundlane cannot stop that on a machine the company does not control.
On laptops, Team makes the org policy the default path, records every decision and approval, and reports drift: a sandbox running something other than the published policy, or an approval that did not come from the console. Hard enforcement against the machine's owner needs a gateway the developer does not administer. That is the License plan, on your cluster.
If the sandbox has a bug
Then the bug is upstream, and we say so. We pin the OpenShell version, read its release notes before every bump, and move the pin when a fix ships. We do not add a second enforcement layer of our own on top of it.