Skip to main content
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

InputTrust levelRule
Maintainer-authored city config and local site configTrusted operator codeMay define shell commands and explicit env. Review before use.
Imported packs and rig configsTrusted dependency codePin/review packs before importing into a privileged city.
Bead titles, descriptions, mail, formula vars, PR text, and API request fieldsUntrusted dataDo not concatenate into shell commands. Pass as env, JSON, stdin, or argv.
GitHub Actions pull_request_target payloadsUntrusted data in a privileged workflowDo not checkout or execute contributor code. Use metadata-only operations.
Ambient process environmentUntrusted for secret propagationController-side shell helpers strip inherited secret-looking env keys by default.

​
Execution Surfaces

SurfaceCommand sourceActorWorking directoryEnv behaviorLog behavior
work_query via gc hook and controller probesAgent configTrusted operator or packAgent’s canonical city or rig repoInherited secrets are stripped; Gas City projects explicit store/session env.Errors are diagnostic only. Avoid placing secrets in command literals.
scale_checkAgent configTrusted operator or packAgent’s canonical city or rig repoInherited secrets are stripped; Gas City projects explicit store env.Parse failures include command context; command literals must not contain secrets.
on_boot and on_deathAgent pool configTrusted operator or packCity or rig repoInherited secrets are stripped; explicit store env may be provided when needed.Hook failures are logged; output should not include secrets.
Order check triggersOrder configTrusted operator or packOrder target scopeInherited secrets are stripped; explicit condition env may be provided.Failure reason records exit status, not command output.
Order execOrder configTrusted operator or packOrder target scopeInherited secrets are stripped; explicit order env may be provided.Failure errors and output are redacted before logs/events.
gc sling and /sling command runnerSling target configTrusted operator or packCity or rig repoInherited secrets are stripped; explicit routing/store env may be provided.Returned command output is caller-visible. Do not route untrusted text into shell.
Agent commandAgent configTrusted operator or packSession work directorySession 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_startAgent configTrusted operator or packSession work directoryProvider-specific runtime env; intended for setup before session start.Provider warnings should avoid secrets.
session_setup, session_setup_script, session_liveAgent configTrusted operator or packRunning session environmentProvider-specific runtime env; remote providers run inside the target container or pod.Provider warnings should avoid secrets.
exec: session providerUser-supplied provider scriptTrusted operator codeProvider-definedDirect 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 providersUser-supplied provider scriptTrusted operator codeProvider-definedDirect 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 helpersGas City code plus configured paths/URLsMaintainer-reviewed code pathsCommand-specificDirect exec with argv except provider setup scripts where documented.Errors are surfaced for diagnosis; avoid embedding credentials in URLs.

​
Secret Propagation

Controller-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.
Last modified on April 28, 2026