Run and secure agents

Run an agent

Start an agent with the selected profile and pass its command after --:

stashbase agent run --profile coding -- codex

Use --profile-source directory to require the current directory's stashbase-agent.toml. The broker is short-lived and shared by the agent and all processes it launches.

Check compatibility

Run the local compatibility report before adding a tool to a profile:

stashbase agent doctor curl
stashbase agent doctor gh
stashbase agent doctor copilot
stashbase agent doctor codex

The report does not load a profile or secret. Most HTTP(S) clients work when they honor proxy and temporary CA settings. Some tools require temporary operating-system trust-store integration:

stashbase agent run --profile coding --trust-broker-ca -- codex

Security boundary

Profiles reduce accidental credential exposure in normal local workflows. They do not isolate a malicious or compromised same-user process, which may access local credentials or bypass proxy settings.

On macOS and systemd-based Linux, --sandbox denies direct network access while retaining the broker's loopback connection:

stashbase agent run --sandbox --profile coding --profile-source directory -- codex

The sandbox is network containment only; it is not filesystem, process-memory, administrator, or root isolation. Treat every repository profile as trusted policy.