Remote sessions

Use a remote session when an agent profile is backed by a Stashbase project and environment. With --remote, Stashbase resolves the configured credentials in its control plane instead of loading them into the local CLI process.

stashbase agent run --remote --profile coding -- codex

The child receives only configured opaque placeholders. It connects to a temporary localhost relay through HTTP_PROXY and HTTPS_PROXY; the relay sends the session token to the remote Agent Proxy. Neither resolved secret values nor the session token are placed in the child's environment.

coding agent (placeholder)
        → localhost relay (memory-only session token)
        → remote Agent Proxy (resolved secret)
        → approved API destination

Requirements

Remote sessions require a profile with all of the following:

• project and environment set to the Stashbase environment that holds the secrets.
• At least one configured secret binding.
• An authenticated Stashbase CLI.

Local-file and egress-only profiles cannot create remote sessions. Use a normal stashbase agent run session for those profiles.

project = "project"
environment = "environment"
egress_hosts = ["registry.npmjs.org"]

[secrets.GH_TOKEN]
from = "GITHUB_TOKEN"

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

Validate the profile before starting a session:

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

Remote validation checks that the profile is eligible for a remote session and inspects the cached public Agent Proxy CA. It does not fetch secret values or create a session.

Start a remote session

Use a directory profile explicitly when the repository policy is the intended source:

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

The same profile settings apply in local and remote mode. --remote changes where Stashbase resolves and retains credentials; it does not broaden a secret binding's legacy hosts list, scoped credential rules, or ordinary egress policy.

Remote sessions are available only for workspaces on paid plans.

Session lifecycle

The CLI creates one short-lived, scoped remote session when the child starts. It rotates the session when necessary and revokes it when the child exits, including graceful shutdown. The session token is memory-only.

The remote Agent Proxy injects a secret only when the child sends that binding's placeholder in the configured request header and its request matches the binding's allowed hosts or scoped HTTP rules. egress_hosts continues to control connectivity, and deny_hosts continues to take precedence.

TLS and supported traffic

Remote sessions supply the remote Agent Proxy's public CA to the child so supported tools can use standard HTTP(S) proxy settings. If a client needs the operating-system trust store, add --trust-proxy-ca:

stashbase agent run --remote --profile coding --trust-proxy-ca -- codex

The remote Agent Proxy supports HTTP(S), CONNECT, and HTTP/1 WebSocket upgrades used by supported coding agents. It is not a general network sandbox: SSH, databases, raw TCP, browser traffic, HTTP/2 proxying, and tools that deliberately bypass proxy settings are outside its scope. Use --sandbox on supported platforms when direct network bypass must be blocked.