Environment and mount reference

A custom runtime image and Agent Guard share this contract: every environment variable the container receives and every directory it sees. Build a runtime image explains how to use them.

Environment variables

Gateway and session

Variable	Value	Use
AGENTGUARD_OPENAI_BASE_URL	http://127.0.0.1:9091/openai/v1	Base URL of the Jozu AI Gateway's OpenAI-compatible route.
OPENAI_BASE_URL	Same as AGENTGUARD_OPENAI_BASE_URL	Set so OpenAI SDKs pick the Jozu gateway up with no code change.
AGENTGUARD_OPENAI_API_KEY	The session token	Send as Authorization: Bearer <token> on every model request. The MCP route and the policy endpoint do not require it. It is not a provider key.
OPENAI_API_KEY	Same as AGENTGUARD_OPENAI_API_KEY	Set so OpenAI SDKs send the token with no code change.
AGENTGUARD_MCP_GATEWAY_URL	http://127.0.0.1:9091/mcp	One MCP endpoint (streamable HTTP) serving the tools of every mcp module in the definition.
AGENTGUARD_POLICY_URL	http://127.0.0.1:9091/gerty/v1/evaluate/tool	Endpoint for a policy decision on an action the application takes outside MCP. Use it only if the application asks for decisions on its own actions.
AGENTGUARD_SESSION_ID	The session identifier	Correlate the application's own logs with Agent Guard's audit records.
AGENTGUARD_VERSION	The Agent Guard release running the session	Lets the application check which Agent Guard release it runs under.

The session token is minted once per boot, is valid only against that session's gateway, and is never written to a file.

Directories

Variable	Value
AGENTGUARD_WORKSPACE	The workspace path. Absent when the run has no workspace.
AGENTGUARD_STATE_DIR	/var/lib/agentguard/app-state
XDG_STATE_HOME	/var/lib/agentguard/app-state/state
XDG_DATA_HOME	/var/lib/agentguard/app-state/data
XDG_CACHE_HOME	/var/lib/agentguard/app-cache
AGENTGUARD_SKILLS_DIR	/opt/agentguard/skills

TLS trust

These point at the Jozu gateway's CA bundle, so standard HTTP clients trust the Jozu gateway's certificate. They are omitted when the Jozu gateway's TLS interception could not be set up for the session, since there is then no bundle.

Variable	Value
SSL_CERT_FILE	/opt/agentguard/ca/bundle.pem
REQUESTS_CA_BUNDLE	/opt/agentguard/ca/bundle.pem
CURL_CA_BUNDLE	/opt/agentguard/ca/bundle.pem
NODE_EXTRA_CA_CERTS	/opt/agentguard/ca/bundle.pem

Terminal

TERM=xterm-256color, COLORTERM=truecolor, LANG=en_US.UTF-8, LC_ALL=en_US.UTF-8, and COLUMNS and LINES for the terminal size.

Values from the agent definition

Each entry in the definition's spec.needs whose target is env (the default) becomes a variable of that name, holding the value the host resolved. An optional need that did not resolve is absent, not empty. A value an llm module lists under env goes to the Jozu gateway instead and is never set in the container. See Declare a runtime in an agent definition.

Precedence

When two sources set the same variable, the later one in this list wins:

1. The image's own ENV
2. Terminal and locale variables
3. Values from spec.needs
4. TLS trust variables
5. Gateway, session, and directory variables

Agent Guard removes any image ENV entry that names a gateway, session, or directory variable, and any variable beginning with GERTY_ or OTEL_, whatever its source.

Mounts

The container sees exactly these directories from outside its own image.

Path in the container	Access	Lifetime
The workspace, at the same path as on the host	read-write	The host directory itself. Absent with --no-workspace.
/var/lib/agentguard/app-state	read-write	Persists with the environment, across runs. With --no-overlay, it lasts one session.
/var/lib/agentguard/app-cache	read-write	Emptied at the start of every session.
/opt/agentguard	read-only	Rebuilt every session. Holds skills/ and ca/bundle.pem.

The container's own root filesystem is writable, and it is discarded when the container exits.

The container

Property	Value
Runtime	Rootless podman inside the microVM
Container name	agentguard-app
Network	The microVM's network namespace (--network=host). The Jozu gateway is on its loopback. No ports are published to the host.
Capabilities	All dropped (--cap-drop=ALL), with no-new-privileges
Init	--init, so signals reach the application and zombies are reaped
User	The image's USER, mapped to Agent Guard's agent account. See Build a runtime image.
Command	The image's ENTRYPOINT and CMD. Arguments after -- on the agentguard run command line replace CMD.
Stop	SIGTERM when the session ends, then a kill after 5 seconds
Exit code	Becomes the exit code of agentguard run

Image label

Label	Meaning
dev.jozu.agentguard.min-version	The oldest Agent Guard release allowed to run the image, as a semantic version (0.8.0 or v0.8.0). Agent Guard refuses the image when the running release is older. Optional.