Environment variables

AgentBox uses environment variables in two distinct places: inside the box (what a box knows about itself) and on the host (cloud tokens, agent-auth forwarding, and control knobs the relay reads). For persistent, layered settings prefer the typed config keys — env vars are for credentials and one-off control.

In-box variables

Every box is stamped at launch with identity vars so an agent — or the in-box agentbox CLI — knows it is sandboxed and which box it is.

Variable	Meaning
`AGENTBOX=1`	Presence flag. The canonical "am I inside a box?" signal.
`AGENTBOX_BOX_ID`	The box's internal id.
`AGENTBOX_BOX_NAME`	The box name.
`AGENTBOX_HOST_WORKSPACE`	Absolute host path of the workspace. Informational only — not a mount.
`AGENTBOX_PROJECT_ROOT`	Set only when the workspace has an `agentbox.yaml` ancestor.
`AGENTBOX_PROJECT_INDEX`	The per-project box index (same condition).

Two more wire the in-box agentbox-ctl back to the host relay so commands like agentbox-ctl git pull|push work (see Sync & git):

Variable	Meaning
`AGENTBOX_RELAY_URL`	Host relay endpoint (docker: `http://127.0.0.1:8788`).
`AGENTBOX_RELAY_TOKEN`	Per-box bearer token for relay calls.

On the cloud providers, two extra vars appear: AGENTBOX_BRIDGE_TOKEN and AGENTBOX_BOX_KIND=cloud. A box restored from a checkpoint is deliberately re-stamped with these same vars, so it keeps correct self-awareness.

Inspect them from inside a box with agentbox shell:

$ agentbox shell mybox -- env | grep '^AGENTBOX'
AGENTBOX=1
AGENTBOX_BOX_ID=2f9c1a...
AGENTBOX_BOX_NAME=mybox
AGENTBOX_HOST_WORKSPACE=/Users/you/projects/app
AGENTBOX_PROJECT_ROOT=/Users/you/projects/app
AGENTBOX_PROJECT_INDEX=1
AGENTBOX_RELAY_URL=http://127.0.0.1:8788
AGENTBOX_RELAY_TOKEN=b7d4...

TIP

Scripts and hooks can branch on AGENTBOX=1 to behave differently inside a box versus on the host.

HEADS UP

AGENTBOX_HOST_WORKSPACE is a reference string only — there is no host bind-mount of your workspace into the box. The box edits its own git worktree at /workspace. See Core concepts and Teleport a project.

box.env

The same identity pairs are also written to /etc/agentbox/box.env inside the box, right after the container starts.

Why: docker run -e vars live only in PID 1's environment. A fresh agentbox shell or any bash -l is a new process tree that would otherwise miss them. The image-baked /etc/profile.d/agentbox.sh runs set -a; . /etc/agentbox/box.env; set +a on login, so interactive shells re-source the vars.

The file is POSIX-sourceable with single-quoted values, written as root with umask 022. It carries the identity vars (plus the portless vars); the relay vars AGENTBOX_RELAY_URL / AGENTBOX_RELAY_TOKEN stay in the launch env and are not written here. Writing it is best-effort — if it fails, PID 1 still has the docker run -e vars and only login shells lose them.

$ agentbox shell mybox -- cat /etc/agentbox/box.env
AGENTBOX_BOX_ID='2f9c1a...'
AGENTBOX='1'
AGENTBOX_BOX_NAME='mybox'
AGENTBOX_HOST_WORKSPACE='/Users/you/projects/app'

WHY

Because login shells source box.env, agentbox shell and any agent spawned through a login shell see the identity vars even though they're separate processes from PID 1.

Agent model, effort, and credential forwarding

When launching an agent, AgentBox forwards a fixed allowlist of host env vars into the box. These are re-read from the current host shell both at create time and at ... start exec time — so launching a box from inside a host Claude session propagates that session's model and auth.

Claude forwards: ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, CLAUDE_EFFORT, ANTHROPIC_MODEL. Model and effort are forwarded as env vars because Claude Code stores your /model and --effort selection only in the parent process env, not in a settings file — env forwarding is the only way to carry it in.

Codex forwards: OPENAI_API_KEY.

OpenCode does no host-env credential forwarding — its auth lives in a synced config volume (auth.json). See Run an agent.

For Claude auth the precedence is: host env (ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN) wins, otherwise the long-lived OAuth token at ~/.agentbox/auth.json (mode 0600), which AgentBox captures on your first agentbox claude via claude setup-token and forwards as CLAUDE_CODE_OAUTH_TOKEN.

Pick a model or effort for a box by exporting before launch:

ANTHROPIC_MODEL=claude-opus-4-6 agentbox claude

CLAUDE_EFFORT=high agentbox claude

Bring your own key instead of the captured OAuth token:

ANTHROPIC_API_KEY=sk-ant-... agentbox claude

OPENAI_API_KEY=sk-... agentbox codex

TIP

Forwarding re-reads your shell on every launch — including agentbox claude start <box> on an existing box — so the model you picked in your host session carries into the box automatically. No config key needed. See Configuration.

HEADS UP

Don't put these tokens in agentbox.yaml or a config key — they're credentials. Use your shell env, or --with-env / carry: for in-workspace .env files. See Teleport a project.

Host env vars

Control and cloud-credential knobs read on the host side.

Cloud provider tokens

Cloud credentials live in ~/.agentbox/secrets.env, written by each provider's login command and auto-loaded into the environment before any SDK or API call. A value already set in your shell wins over secrets.env — handy for CI.

Provider	Keys	Login
Daytona	`DAYTONA_API_KEY` (or `DAYTONA_JWT_TOKEN` + `DAYTONA_ORGANIZATION_ID`), optional `DAYTONA_API_URL`	`agentbox daytona login`
Hetzner	`HCLOUD_TOKEN`, optional `HCLOUD_ENDPOINT`	`agentbox hetzner login`
Vercel	`VERCEL_TOKEN` + `VERCEL_TEAM_ID` + `VERCEL_PROJECT_ID`	`agentbox vercel login`

$ agentbox daytona login
$ agentbox hetzner login
$ agentbox vercel login

For non-interactive or CI use, set the keys directly in the shell instead of running login:

HCLOUD_TOKEN=... agentbox create --provider hetzner -y

TIP

secrets.env is AgentBox-managed — don't hand-edit it; re-run the provider's login. A key set in your shell always overrides it.

carry: controls

These mirror the carry: flags (see Teleport a project):

Variable	Effect
`AGENTBOX_CARRY_YES=1`	Auto-approve the `carry:` prompt (same as `--carry-yes`). Required for non-TTY `-y` runs with a non-empty `carry:`.
`AGENTBOX_CARRY=skip`	Disable carry for this run (same as `--carry skip`).

AGENTBOX_CARRY_YES=1 agentbox create -y

Relay and host-action controls

These govern the host actions the relay performs on a box's behalf (see Sync & git):

Variable	Effect
`AGENTBOX_PROMPT=off`	Auto-accept host-action permission prompts (e.g. `git push`). Headless mode.
`AGENTBOX_GH_FORCE=1`	Required, even with `AGENTBOX_PROMPT=off`, to allow the irreversible `gh pr merge`.
`AGENTBOX_GH_PR_CHECKOUT=allow`	Opt in to `gh pr checkout` (it switches the host repo's branch; off by default).

HEADS UP

AGENTBOX_PROMPT=off lets a box run host git operations without asking. Use it only in trusted or CI contexts. Even then, gh pr merge is gated separately behind AGENTBOX_GH_FORCE=1 because it's irreversible.

Other host knobs

Variable	Effect
`AGENTBOX_HOME`	Override the `~/.agentbox` state directory root.
`AGENTBOX_NO_ANIM`	Disable install/CLI animation (`NO_COLOR` and `CI` are also honored).
`PORTLESS_STATE_DIR`	Override the Portless state dir for web URLs (also a `portless.stateDir` config key).

See CLI for the flag equivalents of --carry-yes, --carry skip, and --with-env.

Environment variables

On this page