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 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, 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 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.

Inspect MCP servers

For an HTTP MCP server configured under [mcp_servers.<name>], inspect the server's advertised tools and how the profile treats them:

stashbase agent mcp tools --profile coding --server linear
stashbase agent mcp check --profile coding --server linear --tool search_issues
stashbase agent mcp verify --profile coding --server linear

tools performs the MCP handshake and tools/list, then reports allowed and denied tools. check evaluates one tool locally without contacting the server or invoking it. verify contacts the server and exits unsuccessfully when a configured tool is missing. Use --remote with tools or verify to resolve the binding through a remote Agent Proxy session.

To fetch a server's tools and save an allowlist interactively in a writable repository profile, run:

stashbase agent mcp configure --profile coding --server linear

MCP policy decisions are also included in Agent Proxy audit metadata, including the MCP server and tool where available. See HTTP MCP servers for the complete MCP guide.

Security boundary

Profiles reduce accidental credential exposure and can restrict selected 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 supported macOS and systemd-based Linux, stashbase agent run denies direct network access by default while retaining the Agent Proxy's loopback connection:

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

This network containment is distinct from profile filesystem restrictions, which add explicit path denies but are not general filesystem, process-memory, administrator, or root isolation. Treat every repository profile as trusted policy.