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/agents/<profile>.toml. The local Agent Proxy is short-lived and shared by the agent and all processes it launches.

The default profile source is auto: Stashbase uses ./.stashbase/agents/<profile>.toml when it exists and otherwise falls back to the user-level configuration. Use --profile-source directory when a repository profile is required for the run. The CLI warns when a selected tracked repository profile has staged or unstaged changes; this is a review signal and --silent suppresses it.

Create a closed starter profile with stashbase agent init <profile>. For CI and automation, --policy-file path/to/profile.toml selects a direct profile file explicitly and cannot be combined with --profile-source.

Inspect command restrictions

Check how a profile treats an executable without starting an agent:

stashbase agent command --profile coding --command curl
stashbase agent command --profile coding --command curl --json

The report identifies whether the command is allowed, whether it is denied, and whether the restriction is enforced by the operating system or by a PATH wrapper. Use it when troubleshooting a command that cannot start. Shell built-ins are not checked by this command because they are handled by the shell rather than launched as executables.

Inspect and validate profiles

List available profiles without loading secrets, or inspect a configured policy and its resolved defaults:

stashbase agent profiles list
stashbase agent profiles list --profile-source directory
stashbase agent profiles show coding
stashbase agent profiles show coding --effective

show prints policy only; it never resolves or displays secret values. The effective view fills omitted binding fields and normalizes matcher values.

Validate before granting a profile secrets:

stashbase agent validate --profile coding
stashbase agent validate --profile coding --profile-source directory
stashbase agent validate --profile coding --json
stashbase agent validate --remote --profile coding

Validation does not read secret values or start a proxy. It checks profile selection, local-file availability, duplicate bindings, host and HTTP rules, headers, templates, command names, and filesystem paths. Intentional but risky settings such as broad or shadowed rules are reported as warnings. On platforms without a supported filesystem-enforcement backend, validation fails closed for profiles that request command or filesystem restrictions.

Check compatibility

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

stashbase agent doctor copilot
stashbase agent doctor codex
stashbase agent doctor --remote 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-proxy-ca -- codex

Run the compatibility report before adding a tool or destination to a profile. If a request is denied, use stashbase agent explain --verbose and the audit log to decide whether it needs a credential rule, a legacy binding hosts entry, or ordinary egress_hosts access.

Security boundary

Profiles reduce accidental credential exposure and can restrict selected commands and filesystem paths in normal local workflows. They do not isolate a malicious or compromised same-user process, which may access local credentials, already-open file descriptors, process memory, or bypass controls that are outside the configured policy.

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

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

The --sandbox option is network containment; profile filesystem restrictions add explicit path denies but are not general filesystem, process-memory, administrator, or root isolation. Treat every repository profile as trusted policy.