D-401 Reference

CLI reference

Every boundlane command. Each one names the OpenShell commands it runs, so you can check what happened with OpenShell's own tools.

Commands

Set up

boundlane

With no command, in a terminal, it shows the current folder, the agent from setup, how many sandboxes are running, and whether changes are waiting to be applied. Then it offers the next steps: start the agent, review the changes, connect to a running sandbox, answer requests, check the machine, run setup again, or list every command. Before setup has finished once, it starts setup instead. Without a terminal it prints the list of commands.

boundlane setup

Asks questions in five steps: this machine, agent, model key, project folder, and agent image. Then it shows the policy the agent starts with and offers to run it. The installer starts it when a person is at the terminal, and so does boundlane with no command until setup has finished once. Answers are saved in ~/.config/boundlane/setup.json.

Every change asks first. If OpenShell is missing, it offers to install release 0.1.2 with the upstream installer and shows the command before it runs it. On a Mac with Homebrew, it offers to start a stopped gateway as a Homebrew service. It turns off automatic approval and the gateway-wide settings doctor --fix removes, only if you say yes. It stores the key as key set does and builds the image as agents build does. The build log is written to ~/.cache/boundlane/builds/.

Use the arrow keys or j and k, then Enter. Esc or the left arrow goes back to the previous question, as far as the agent step. Ctrl-C stops setup with exit code 130. Without a terminal, questions are numbered and read one line at a time; type b or < to go back from a choice, and < from a typed answer.

boundlane doctor [--fix]

Checks the runtime version against the pinned range, the gateway connection, the sandbox driver, the image builder, the approval mode, the sandbox settings Boundlane turns on, and the bad-revision setting. If the runtime is missing, it names the pinned version and stops.

Runs: openshell status, openshell gateway info, openshell settings get --global.

Fails if the gateway approves requests automatically for every sandbox, or if it turns off the audit log or agent requests for every sandbox. Those gateway-wide values override what run sets. --fix removes them with openshell settings delete --global. It changes nothing else, and says what it will change first. It does not configure colima; see colima on a Mac.

boundlane init

Writes boundlane.yaml in the current folder, with example hosts commented out. It does not read the project. Nothing is allowed until you uncomment a host.

boundlane key list | set <agent> | remove <agent>

list shows which agents have a key stored on this machine. It never prints a key. set asks for the key without showing it, or reads one line from a pipe, and stores it in the gateway's provider store; run it again to replace a key. New sandboxes use the new key. remove deletes the stored key, and refuses while a Boundlane sandbox is running. See Model keys.

Runs: openshell provider get, openshell provider create --from-existing or openshell provider update --from-existing, with the key passed in the environment of that one command, never as an argument. remove runs openshell provider delete.

Run an agent

boundlane run [flags] [agent] [-- agent args]

Without an agent name, it runs the agent chosen in setup, or Claude Code if setup has not run. boundlane run codex picks another one. Everything after -- goes to the agent: boundlane run -- --resume, or boundlane run claude -- --resume.

Compiles and checks the policy, builds the agent's image if needed, creates the sandbox, copies the project in, and starts the agent in your terminal. When the agent exits, it saves the log and stages the changes. In a terminal it then shows the changes and asks what to do with them, and only after that asks whether to keep the sandbox running. Keeping it leaves the session and its approvals in place. boundlane connect opens the agent again, and boundlane stop ends it. Deleting it does not touch staged or applied changes. Without a terminal, the sandbox is deleted and the changes stay staged.

Claude Code starts with --permission-mode manual, so Claude asks you before each command and the policy decides what the command can reach. Pass your own --permission-mode after -- to use another mode.

Runs, in order: openshell settings get --global, openshell-prover check, openshell profile import and openshell provider create on first use, openshell sandbox create --detach --policy --provider --approval-mode manual --no-auto-providers, openshell sandbox get --policy-only and the prover again, openshell settings set to turn on the JSON audit log, openshell sandbox upload, openshell sandbox exec --tty. On exit: openshell logs until the log stops growing, openshell sandbox download, and openshell sandbox delete when the sandbox is not kept.

The project is copied to /sandbox/<folder> and the agent starts there. .git is not copied.

The settings change reaches the sandbox on its next poll, and loading it closes open connections, so run waits for it before starting the agent. Settings the gateway already turns on for every sandbox are skipped. If the gateway turns one off for every sandbox, run stops before creating anything and points to doctor --fix.

For agents that support it, run adds a short guide to the agent's instructions: how to look up a refused connection and how to request access through OpenShell's policy API inside the sandbox. Claude Code gets it through --append-system-prompt, Codex through a setting on its command line, OpenCode as a file written inside the sandbox, outside the project, and Grok through --rules. Your project is not changed. See Agents.

Exits with the agent's exit code once the agent has started.

Sandboxes

boundlane ps [--all]

Lists the sandboxes Boundlane started that are still running. --all adds finished ones, whose logs and staged changes you can still read. Runs: openshell sandbox list --names --selector boundlane=1.

boundlane connect [name] [--shell] [-- agent args]

Starts the sandbox's agent again in your terminal, in the project folder inside the sandbox, with the same policy and the files as the agent left them. --shell opens a shell instead. Use it from a second terminal while the agent works, after run --keep, or when the terminal that ran the agent was closed and the sandbox is still running. Default: the latest running sandbox for the current folder; if several are running elsewhere, it asks which. Exiting leaves the sandbox running. boundlane stop ends it and brings the changes back. Runs: openshell sandbox exec --tty, as run does.

boundlane stop [name] [--yes]

Ends a sandbox: saves the log, copies the project out to staging, then deletes the sandbox. If the copy fails, the sandbox is kept. Default: the latest running sandbox for the current folder; if several are running elsewhere, it asks which. Asks first unless you pass --yes.

Requests

boundlane requests [--all] [--sandbox <name>]

Lists the pending requests the agent filed in your running sandbox, with the first eight characters of each id, the program, and the agent's reason. Drafts the sandbox made from refused connections are counted under the list, with their hosts; --all lists them too, under their own heading. A request counts as the agent's when the sandbox log marks it as filed by the agent, or when its reason is not the generated one. In a terminal it then asks about each one: approve, deny with a reason, or decide later. Without a terminal it prints the approve and deny commands instead. If several sandboxes are running and none is in the current folder, it asks which. Runs: openshell rule get <sandbox> --status pending and openshell logs. OpenShell prints that as text, not JSON; if its format changes, Boundlane shows the raw text instead of a list.

boundlane approve <id> [--sandbox <name>]

Approves a request. The id can be any start of the full id that matches one request. The sandbox loads the new rule on its next poll, about 10 seconds later. On Team, approve in the console. An approval made here still works, and the console shows it as drift.

boundlane deny <id> --reason "<text>"

Denies a request and keeps the reason with it. Runs: openshell rule reject --reason.

Log and changes

boundlane log [flags]

Reads the gateway's log stream for a running sandbox, and the copy saved at exit for a finished one. Boundlane writes that copy before it deletes the sandbox, because deleting the sandbox deletes the gateway's log. The table is network decisions only: time, allow or deny, program, destination, and rule. A deny's reason is in --deny. Query strings are left out. OpenShell does not log a blocked file write. A reset line is a connection closed because the policy changed; the program reconnects, and --deny leaves it out.

boundlane diff [--sandbox <name>] [--stat]

Lists staged changes against your working tree with line counts, including deleted files, then shows each file's changed lines. Long output goes through $PAGER, or less. --stat prints the list only.

boundlane apply [--sandbox <name>] [--yes]

Lists the staged changes, then asks: apply them, show them, or keep them for later. Without a terminal it asks [y/N] on one line. --yes applies without asking. It refuses if a file changed on your side since the agent started, and lists those files.

When an agent exits, or after boundlane stop, the same list and question appear in the terminal. Keeping the changes for later leaves your folder as it was. After an apply, a sandbox that keeps running is compared against what was applied, so the next stop brings back only what the agent changed since.

Policy

Both commands read ./boundlane.yaml merged over the built-in default unless you name a file. --agent picks the agent to compile for (default claude). --org treats the file as a complete policy instead of a project file.

boundlane policy compile [file] [-o out.yaml]

Prints the OpenShell policy the file compiles to. Needs no gateway.

boundlane policy check [file] [--boundary file]

Runs openshell-prover check and prints the result with a counterexample if there is one. Needs no gateway. Exits 2 unless the result is within_boundary.

Agents

boundlane agents

Lists the agents in the catalog, their pinned versions, and their test status.

boundlane agents build <agent>

Builds or rebuilds the agent's image with Docker or Podman, whichever the gateway uses. See Agent images.

Update

boundlane update [--check]

Reads https://boundlane.dev/dl/latest.txt. If it names a newer release, downloads the binary for this machine, checks it against that release's sha256 list, and replaces the running command. Nothing changes if the checksum does not match. --check only reports. Running sandboxes are not touched. Commands also mention a newer release on their own, at most once a day; see The update check.

Team account

boundlane server

Starts a team server on this machine, at http://127.0.0.1:8787. It listens on localhost only. The terminal stays open until you press Ctrl-C. Sign in from another terminal. The database is ~/.config/boundlane/server.db, with two starter users: dana@acme.dev (admin) and li@acme.dev. On first start it publishes developer-default if the prover accepts it.

boundlane login [--server URL]

Prints a code and a page to open. You pick a user and approve. The machine caches the signed policy. A later boundlane run uses that policy. boundlane.yaml in the project does not add hosts on top of it.

boundlane logout

Forgets the sign-in and the cached policy. A sandbox that is already running keeps the policy it started with.

boundlane status

Shows who is signed in, the team, and the cached revision. If the server cannot be reached, it says so and keeps the cached policy after checking the signature again.

boundlane policy publish <file>

Sends a complete org policy to the server. The server compiles it for every agent it names, runs the prover, and refuses it unless the result is within_boundary. Only an admin can publish. The new revision is cached on this machine. The same action is on http://127.0.0.1:8787/console.

boundlane sync

If the new revision only changes hosts, this loads it onto sandboxes that are already running and says when policy list shows Loaded. If it changes paths, workspace, or agents, those sandboxes keep the policy they started with. The next run creates a new sandbox.

boundlane forward [--once]

Reads the local gateway's decision stream and pending requests, and posts them to the team server. A review made in the console is applied here, with the same approve or deny the gateway already uses. The server does not connect to this machine. If the log read fails, a gap row is sent and the missing events stay missing. --every 30s changes how often it looks; the default is five seconds. See Forwarding decisions.

Exit codes

run and connect return the agent's own exit code after the agent has started. Ctrl-C at a question returns 130.

Files

Model keys are not in any of these. They are in the gateway's provider store.