Command Execution Trust Boundaries

Gas City intentionally runs operator-configured commands. Those commands are a feature, not a sandbox. Treat city config, imported packs, exec provider scripts, and agent startup commands as trusted code with the same review expectations as shell scripts committed to the repository.

Trust Model

Input	Trust level	Rule
Maintainer-authored city config and local site config	Trusted operator code	May define shell commands and explicit env. Review before use.
Imported packs and rig configs	Trusted dependency code	Pin/review packs before importing into a privileged city.
Bead titles, descriptions, mail, formula vars, PR text, and API request fields	Untrusted data	Do not concatenate into shell commands. Pass as env, JSON, stdin, or argv.
GitHub Actions `pull_request_target` payloads	Untrusted data in a privileged workflow	Do not checkout or execute contributor code. Use metadata-only operations.
Ambient process environment	Untrusted for secret propagation	Orchestrator-side shell helpers strip inherited secret-looking env keys by default.

Execution Surfaces

Surface	Command source	Actor	Working directory	Env behavior	Log behavior
`work_query` via `gc hook` and orchestrator probes	Agent config	Trusted operator or pack	Agent’s canonical city or rig repo	Inherited secrets are stripped; Gas City projects explicit store/session env.	Errors are diagnostic only. Avoid placing secrets in command literals.
`scale_check`	Agent config	Trusted operator or pack	Agent’s canonical city or rig repo	Inherited secrets are stripped; Gas City projects explicit store env.	Parse failures include command context; command literals must not contain secrets.
`on_boot` and `on_death`	Agent pool config	Trusted operator or pack	City or rig repo	Inherited secrets are stripped; explicit store env may be provided when needed.	Hook failures are logged; output should not include secrets.
Order `check` triggers	Order config	Trusted operator or pack	Order target scope	Inherited secrets are stripped; explicit condition env may be provided.	Failure reason records exit status, not command output.
Order `exec`	Order config	Trusted operator or pack	Order target scope	Inherited secrets are stripped; explicit order env may be provided.	Failure errors and output are redacted before logs/events.
`gc sling` and `/sling` command runner	Sling target config	Trusted operator or pack	City or rig repo	Inherited secrets are stripped; explicit routing/store env may be provided.	Returned command output is caller-visible. Do not route untrusted text into shell.
Agent `command`	Agent config	Trusted operator or pack	Session work directory	Session env is explicit runtime env plus configured env. Secrets may be passed only by intentional config.	Agent stdout/stderr is session output and may be visible to operators.
`pre_start`	Agent config	Trusted operator or pack	Session work directory	Provider-specific runtime env; intended for setup before session start.	Provider warnings should avoid secrets.
`session_setup`, `session_setup_script`, `session_live`	Agent config	Trusted operator or pack	Running session environment	Provider-specific runtime env; remote providers run inside the target container or pod.	Provider warnings should avoid secrets.
`exec:` session provider	User-supplied provider script	Trusted operator code	Provider-defined	Direct exec, not `sh -c`; start config is JSON on stdin.	Provider stderr may be surfaced in errors. Do not print secrets.
`exec:` beads, mail, and events providers	User-supplied provider script	Trusted operator code	Provider-defined	Direct exec, not `sh -c`; request data is stdin/argv.	Provider stderr may be surfaced in errors. Do not print secrets.
Pack fetch/include, Git probes, Docker, Dolt, tmux, kubectl, `bd` helpers	Gas City code plus configured paths/URLs	Maintainer-reviewed code paths	Command-specific	Direct exec with argv except provider setup scripts where documented.	Errors are surfaced for diagnosis; avoid embedding credentials in URLs.

Secret Propagation

Orchestrator-side shell helpers remove inherited environment variables whose keys look secret-bearing, including names containing TOKEN, PASSWORD, SECRET, PRIVATE_KEY, API_KEY, ACCESS_KEY, CREDENTIAL, OAUTH, or AUTH_JSON. This prevents ambient CI or maintainer shell secrets from reaching work_query, scale_check, hooks, order checks, order exec commands, and sling helpers by accident. If a command truly needs a secret, pass it explicitly through the relevant city, rig, provider, or workflow configuration. Explicit values are preserved because they represent an operator decision, and failure logs redact known secret values before writing order exec errors or events.

Rules For Authors

Do not put secrets directly in command strings. Use env variables or provider credential files.
Do not interpolate bead content, PR text, mail, formula vars, branch names, or other user-controlled values into sh -c commands.
When showing a command for a human to copy, build it from argv and quote each argument with Gas City’s shell quoting helper.
Keep pull_request_target workflows metadata-only. They may label or comment but must not checkout or run contributor code with privileged tokens.
Prefer direct exec.Command(..., args...) style boundaries for new provider contracts. Use sh -c only for explicitly operator-authored shell snippets.

Getting Started

Tutorials

Guides

Troubleshooting

Reference

Command Execution Trust Boundaries

Trust Model

Execution Surfaces

Secret Propagation

Rules For Authors

​Trust Model

​Execution Surfaces

​Secret Propagation

​Rules For Authors

Trust Model

Execution Surfaces

Secret Propagation

Rules For Authors