Network access reference

This page lists every allow-list entry form, where entries come from, how the sources combine, and the format of the credential audit. For how the list is enforced and what it does not cover, see How network access works. For header and registry entries, see Credentials for allowed hosts.

Entry syntax

--allow-host and spec.egress take the same entries. Names are case-insensitive.

Entry	Opens	Checked by
example.com	Port 443 on example.com	Name, at the Jozu gateway
*.example.com	Port 443 on every name under example.com, not example.com itself	Name, at the Jozu gateway
tcp://example.com:5432	Port 5432 on the addresses example.com resolves to	Address
tcp://10.20.3.4:5432	Port 5432 on 10.20.3.4. --allow-host only	Address
tcp://192.168.127.254:5432	Port 5432 on your desktop's loopback interface. --allow-host only	Address
oci://ghcr.io	Port 443 on ghcr.io, signed in with your desktop's login for the registry	Name, at the Jozu gateway, which terminates the connection
oci://docker.io, oci://index.docker.io	Port 443 on registry-1.docker.io, Docker Hub's API host, signed in with your desktop's Docker Hub login	Name, at the Jozu gateway, which terminates the connection
{host: api.github.com, headers: {...}}	Port 443 on api.github.com, with the headers set on every request. spec.egress only	Name, at the Jozu gateway, which terminates the connection

A trailing slash after the port or the registry is accepted, so tcp://example.com:5432/ is the same entry.

Header entries

A spec.egress entry can be a mapping that names one host and the headers the Jozu gateway sets on every request to it:

egress:
  - host: api.github.com
    headers:
      Authorization: "Bearer ${needs.GITHUB_TOKEN}"
      X-GitHub-Api-Version: "2022-11-28"
  - host: github.com
    headers:
      Authorization:
        basic: "x-access-token:${needs.GITHUB_TOKEN}"

Field	Meaning
host	One exact host name. Port 443 is implied.
headers	Header name to value. A value is a string, either a literal or one containing ${needs.NAME} references, or a mapping with the single key basic, whose value is such a string. The gateway sends a basic value as Basic followed by the base64 encoding of the rendered string.

A mapping without headers is the string entry for its host, wildcard and tcp:// forms included.

Each ${needs.NAME} must name a need the definition or one of its bases declares, with target: env. The need is withheld from the agent, which receives agentguard-withheld-NAME under the need's name instead. A need marked optional: true that does not resolve drops every header that references it; an entry left with no headers stays on the list as a plain host.

A header entry is additive across a base chain. A derived definition can add headers to a host its base lists as a plain name, and cannot change or remove headers its base declares.

Registry entries

oci://<registry> names a container registry, in spec.egress or with --allow-host. It opens port 443 on the registry's API host and has the Jozu gateway sign the agent in there with the login your desktop's docker or podman holds for the registry, sent as Basic credentials on each request that carries no Authorization. A registry with no login on your desktop is reached anonymously, after a warning.

The registry's token service and content hosts are admitted during the run as the registry's responses name them, and recorded as admit records. A host the run lists plainly, such as auth.docker.io, stays as listed and receives no login.

Refused entries

Agent Guard refuses these before the microVM boots, and names the entry:

Entry	Why
example.com:5432, 10.20.3.4	An address or a port takes the tcp:// form.
https://example.com, ssh://example.com:22	tcp:// and oci:// are the only schemes. An HTTPS host is a bare name.
tcp://example.com:443	A name on port 443 is the bare name form, which the gateway checks by name.
tcp://*.example.com:22	A wildcard opens port 443 only. Nothing checks the name on any other port.
tcp://example.com:5432/db, tcp://user@example.com:22	A tcp:// entry is a host and a port only.
10.1, 167772161, 0x0a000001	Resolvers read these as IPv4 addresses. Write an address as four decimal octets.
An IPv6 address	The microVM has no IPv6 connectivity.
An address in 0.0.0.0/8, 127.0.0.0/8 or 169.254.0.0/16, multicast, or broadcast	Never opened. Reach your desktop through 192.168.127.254.
An address in 192.168.127.0/24 other than 192.168.127.254	The microVM's own network.
Any address, in spec.egress	A definition runs on many networks, and a private address names a different machine on each. Name the host, or pass the address with --allow-host.
An entry that covers an MCP or model endpoint in the agent definition	The Jozu gateway reaches that endpoint for the agent, under policy. A direct route would bypass the policy.
oci://ghcr.io:5000, oci://ghcr.io/myorg/app	A registry entry is a host name alone. The gateway terminates only port 443, and a login applies to the whole registry, not to one repository.
oci://*.example.com, oci://10.20.3.4	A login goes to one named host. The gateway checks names, not addresses.
A header entry whose host is a wildcard, an address, or a tcp:// or oci:// entry	Headers go to one exact host on port 443. A wildcard would send them to every name under it.
A header named Host, Content-Length, Transfer-Encoding, Connection, Keep-Alive, TE, Trailer or Upgrade, or one starting with Proxy-	The gateway sets these itself.
A header value with a ${...} token other than ${needs.NAME}, an empty value, or a line break	A value is a literal with ${needs.NAME} references and nothing else.
Two header entries for one host in one definition	Merge them into one.
A header entry and an oci:// entry that cover the same host, in the definition or with --allow-host	Both would set the request's Authorization.
A header or registry entry for a model API host	The gateway already terminates that host for GuardrailPolicy. A custom runtime's provider credential belongs in an llm module's credential.
A header entry for a host whose headers a base definition declares	An inherited header entry cannot be changed.

An entry that names a model API host, which always goes through the Jozu gateway, is accepted and has no effect. --allow-host warns when you pass one.

Sources

The list for a run merges every source. An entry listed by more than one source appears once, carrying each source as an origin.

Origin	Source
run	--allow-host on agentguard run
declared	spec.egress in the agent definition being run
base	spec.egress in a definition it inherits from, at any depth
framework	The agent's baseline
system	The baseline every run carries

A derived definition cannot remove an entry its base carries. It can add entries.

--allow-host cannot be combined with --dangerously-allow-all-hosts, which runs with no list. Agent Guard refuses the run.

Framework baselines

Agent	Baseline	Needed for
Claude Code	platform.claude.com	/login and token refresh
Codex CLI	auth.openai.com	Sign-in with ChatGPT and token refresh. An API key needs nothing beyond the gateway
Antigravity CLI	oauth2.googleapis.com, www.googleapis.com, lh3.googleusercontent.com	Token refresh, and the account check the CLI runs before every turn
OpenClaw	None

Each agent also tries hosts its baseline leaves out: update checks, plugin marketplaces, feature flags and telemetry. The agent works without them, and their refused lookups appear in every session's egress log.

System baseline

Entry	Needed for
deb.debian.org	apt-get install and apt-get update. The microVM's apt sources use HTTPS, so apt traffic passes the gateway's name check like the agent's

Hosts reached for the agent

These hosts are resolved inside the microVM but never opened to the agent:

Host	Reached by	When
A remote MCP server's endpoint host	The Jozu gateway	The agent definition includes an mcp module with source.endpoint
A custom runtime's llm endpoint host	The Jozu gateway	The agent definition names one
api.github.com	Agent Guard, to configure your git identity	A GitHub token is staged
registry.npmjs.org	Agent Guard, to install OpenClaw on the environment's first boot	The agent is OpenClaw

To let the agent reach one of these hosts itself, list it. An entry that covers an MCP or model endpoint in the definition is refused.

Resolution before boot

Agent Guard resolves every exact name on the list on your desktop before the microVM boots, and opens the IPv4 addresses it gets. Inside the microVM, each lookup of a listed name opens the addresses in the answer as well, so a host whose addresses rotate stays reachable for the run.

Name from	Does not resolve on your desktop
--allow-host	The run stops before boot.
spec.egress or a baseline	Agent Guard warns, records the name in the boot record's unresolved, and the run continues. The agent cannot reach the name unless it resolves inside the microVM later.

Wildcards are not resolved before boot. Their names open as the agent looks them up.

A host with headers, and a registry's API host, are reached only at the addresses resolved on your desktop before boot, for the length of the run. One that does not resolve there is reported as a warning, and the gateway closes the agent's connections to it.

A run with a header or registry entry needs the Jozu gateway inside the microVM. If its binaries cannot be staged, the run stops before boot rather than sending the placeholder.

Credential audit

Every time the Jozu gateway asks for a credential, Agent Guard records the answer in ~/.agentguard/host-private/credential-audit/credential_audit.<session>.jsonl, one JSON object per line. With AGENTGUARD_HOME set, the file is in $AGENTGUARD_HOME/host-private/credential-audit/. The directory is not shared with the microVM, so nothing running in the microVM can read or write the file. The session matches the egress log's.

A value is handed out only once its record is written. If the file cannot be written, the gateway gets no value and the request fails.

Field	Meaning
timestamp	When the record was written, in UTC
need	The need, or oci://<registry> for a registry login
consumer	Who asked: egress:<host> for a header or registry entry, mcp:<module> for a remote MCP module's headers, llm:<module> for an llm module's credential
type	secret for a need, basic for a registry login
source	What produced the value: the host variable a need reads, service/account for a keychain resolver, or the config file or docker-credential-<helper> that holds a registry login. Never the value, and absent for a literal
expiresAt	For a registry login, when Agent Guard reads it again
outcome	answered, refused, or failed
reason	Unless answered: unknown, a need the run did not give that consumer; expired or refresh-failed, a registry login past its time that could not be read again; bad-token or bad-request, a request that did not come from the run's gateway or named no consumer
suppressed	On a refusal, how many repeats of it were counted rather than written

The gateway keeps a need's value in memory for the run, so a need has one answered record per consumer. A registry login is kept for 15 minutes, and the first request after that reads it from your desktop again, with a new record.

Agent Guard does not prune the file, and it is not part of the audit records that sync to Hub.

Related

• How network access works
• Allow a host
• Credentials for allowed hosts
• What an agent definition is
• CLI reference