Environment variables
Onebox owns the ONEBOX_ prefix. Everything it injects or reads lives there,
which keeps it greppable in a CI settings page, a secrets store, or someone
else’s hook script.
Your application’s own variables are never touched. A workload that expects
FANOUT_*, DATABASE_URL, or OTEL_EXPORTER_OTLP_ENDPOINT receives exactly
those keys, unchanged — Onebox passes workload environment through rather than
namespacing it.
Injected into local hooks
Section titled “Injected into local hooks”A hook declared local: true runs on your machine. It is given enough to reach
the server itself, because Onebox’s own connection is not something a separate
process can borrow:
| Variable | Value |
|---|---|
ONEBOX_APP | The application name |
ONEBOX_HOST | The server’s hostname, unbracketed |
ONEBOX_SERVER | user@host, valid as an OpenSSH destination |
ONEBOX_SSH_USER | The SSH user |
ONEBOX_SSH_PORT | The SSH port, separate because user@host:port is invalid for both ssh and rsync |
ONEBOX_SSH_JUMP | The jump host, empty on a direct connection — see Deploy through a jump host |
ONEBOX_RELEASE_DIR | Absolute path of the release directory on the server |
ONEBOX_RELEASE_ID | The release identifier |
ssh ${ONEBOX_SSH_JUMP:+-J "$ONEBOX_SSH_JUMP"} "$ONEBOX_SERVER" -p "$ONEBOX_SSH_PORT" 'uptime'The job result protocol
Section titled “The job result protocol”| Variable | Value |
|---|---|
ONEBOX_RESULT_FILE | Path a job writes its structured result to |
A job that reports back writes one JSON document there:
printf '{"schema_version":"onebox.run/job-result/v1alpha1","changed":true}' > "$ONEBOX_RESULT_FILE"Backup helpers
Section titled “Backup helpers”| Variable | Value |
|---|---|
ONEBOX_REPOSITORY_KEY | Repository encryption key |
ONEBOX_S3_KEY_ENTRY | Name of the entry holding the S3 access key |
ONEBOX_S3_SECRET_ENTRY | Name of the entry holding the S3 secret key |
ONEBOX_S3_SESSION_TOKEN_ENTRY | Name of the entry holding the S3 session token |
Read from your shell or CI
Section titled “Read from your shell or CI”| Variable | Effect |
|---|---|
ONEBOX_LOCAL | 1 or true runs against the local Docker daemon instead of connecting over SSH |
ONEBOX_BIN_DIR | Where just build writes the binary, and where the other recipes look for it (default bin) |
ONEBOX_INSTALL_DIR | Where just install places the binary (default ~/.local/bin) |
ONEBOX_VERSION | Version string just build stamps into the binary; must match vYYYY.M.REVISION with an optional -alpha suffix |
ONEBOX_RELEASE_REPOSITORY | Repository scripts/release.sh queries to confirm the previous release run finished, when the git remote does not name it |
ONEBOX_LOCAL is the only one of these Onebox itself reads; the rest are build
and release controls read by just and the release script.
Contributor and test controls — ONEBOX_E2E, ONEBOX_E2E_*, ONEBOX_SERVER_E2E,
and ONEBOX_UPDATE_VERDICTS — follow the same prefix. just e2e sets
ONEBOX_E2E for you; the rest are set by hand when running a suite or
refreshing a frozen fixture.
Nothing in this namespace reaches a generated runtime. Generation reads no process environment at all, so the same project renders the same Compose on your laptop and in CI, and a digest keeps meaning something.