Overview

Run AI coding agents in a sandbox with governed access to credentials, network, files, and tools

Stashbase runs coding agents inside a sandbox, either a native OS sandbox or an isolated Docker container. The agent gets governed access to the credentials, network destinations, files, dependencies, and tools it needs, and never sees secret values. Agent profiles define those capabilities, and Stashbase enforces them at the Agent Proxy boundary, resolving short-lived placeholders only for approved requests.

How it works

Your shell → stashbase agent run → coding agent
                                      │
                                      │ placeholder in a supported request header
                                      ▼
                              Stashbase Agent Proxy
                                      │
                                      ▼
                              approved API destination

You define the secrets and destinations a workflow may use in an agent profile. The profile can read configured source names from a Stashbase environment, a local secrets file, or both. The Agent Proxy applies that policy to the agent and every process it starts.

Remote profiles can also bind account-owned Personal Credentials under [personal_credentials.<binding>]. These credentials are private to the authenticated user, work only with --remote, and can be combined with shared [secrets.<binding>] bindings. See profile configuration for the syntax and migration notes.

Choose a session type

Session	Use it when	Where resolved secrets live
Local	Your profile uses a local file, has local overrides, or you need the simplest setup.	In the short-lived local Agent Proxy process.
Remote	Your profile is backed by a Stashbase project and environment and you want credentials resolved in Stashbase.	On Stashbase infrastructure.

Both modes give the child only placeholders and enforce the same host policy. Add --remote when starting an eligible remote session. Remote sessions are available only for workspaces on paid plans.

Quick start

Create a closed repository-local starter profile in a trusted project directory:

stashbase agent init local_agent

Then configure .stashbase/agents/local_agent.toml:

.stashbase/agents/local_agent.toml

[secrets]
project = "project"
environment = "environment"
egress_hosts = ["api.anthropic.com", "registry.npmjs.org"]

[secrets.GH_TOKEN]
env = "GITHUB_TOKEN"

[[secrets.GH_TOKEN.rules]]
effect = "allow"
hosts = ["api.github.com"]
methods = ["GET", "POST"]
paths = ["/repos/*/*/issues*"]

Validate the policy before it is granted secrets, then launch your agent:

stashbase agent validate --profile local_agent --profile-source directory
stashbase agent run --remote --profile local_agent --profile-source directory -- codex

The child process gets a placeholder named GH_TOKEN, never the real value. It may use that placeholder only for the configured GitHub issue requests; package-registry traffic is permitted without receiving a credential. Omit --remote to run the same profile through a local Agent Proxy.

How it works

Choose a session type

Quick start

Continue in the guide

On this page