Crate hatchery_node 

Native Gate4Agent node server and runtime.

Re-exports

pub use machine_env::collect as collect_machine_environment;

pub use kit::force_link;

pub use kit::linked_core_names;

pub use kit::start_mailbox;

pub use kit::MailboxHandle;

pub use gate4agent_node_protocol as protocol;

Modules

browser_capture

Linux dig2browser capture inside the node (feature d2b).

door

Local door for agents on this node: mail and task operations without ever touching a key.

enroll_client

Node side of enrollment: key generation in the node’s own state directory, the signed request with the operator’s one-time code, and the stored public answer.

grok_leader

Per-session grok leader isolation.

isolation

Node-side isolation: run provider sessions as an unprivileged user, and apply the egress kill-switch rendered by hatchery_enroll::KillSwitch. Linux/Unix only; both are opt-in and fail closed (a requested isolation that cannot be set up stops the node).

keystore_proxy

Node-side keystore proxy (was m4a_signer_proxy) (option A, specs/m4a-session-keys-2026-10-16.md).

kit

Standard node kit cores: dig2browser (d2b), mail4agent (m4a), the four session-restore crates (session-restore) and kernel WireGuard (wireguard). Each core is compiled only with its own feature; the default build (kit) enables all of them.

local_infra

Discovery of local infrastructure the node can reuse instead of starting its own copy: a mail4agent courier, another gate4agent node.

local_server

Session-local HTTP server pool (tesserax-http static + supervised http children).

m4a_accounts

Per-session m4a accounts assigned by the node at spawn (owner model: session = nick = one key = one role). Every PTY spawn gets its own account when the node can find m4a-agent (env HATCHERY_M4A_AGENT_BIN, else next to this binary, PATH, or ~/.cargo/bin) and an accounts root (env HATCHERY_M4A_ACCOUNTS_ROOT, else <enroll-state>/m4a-accounts). Product URL comes from env or the enrollment reply (m4a_product_url). The node runs m4a-agent account provision (registry and vaults stay under the node’s accounts root, outside the session sandbox), reads the fresh capability from a one-shot 0600 file it removes at once, and injects ONLY M4A_NICK and M4A_SESSION_CAP into that session’s child environment. The capability is never logged.

m4a_adopt

Adoption of a provider session the node did not spawn: the node gives it a per-session m4a account and puts the node’s own m4a MCP server (m4a-agent mcp, stdio) in the provider’s config, removing a stale standalone mailbox MCP entry (a loopback HTTP url) with a backup.

m4a_attach

POST /m4a/attach: on-demand m4a account for a provider session the node did not spawn (spec live-session-m4a-attach).

m4a_signer_proxy

0.2.15 name of keystore_proxy. Unix only, same as the proxy itself.

m4a_wake

Letter wake for live sessions the node adopted (/m4a/adopt).

machine_env

Collect host machine resources + installed provider CLI versions for topology inventory.

node_control

Local control channel of this node (POST /control/{drain,reload,handoff} on the ops HTTP listener). Owner-only: a random bearer token written 0600 (Unix) into the node’s own state directory, a per-user location on Windows. /health publishes the token file path and the capabilities, never the token.

node_log

Rotating JSON-lines log for the node. Path comes from the caller or GATE4AGENT_NODE_LOG — never a hardcoded absolute path.

plugins

Signed session plugins (node-owned session environment).

provider_inventory

Provider inventory: which provider CLIs this node can run and which models each one exposes, read from the CLI itself (or its own config). Nothing is invented: a provider whose CLI does not list models reports only what its help text / config names.

restream_g4a_bridge

Node restream g4a bridge (A2).

restream_session

Node end of a live restreamer session (A2 / A3).

session_signals

Short session signals the node reads off its own PTY screens: a provider CLI hit a usage/rate limit, needs a login, or is ready again. Only state changes are sent to core (task.session_signal over the node-call channel); screens never leave the node for this. Detection is heuristic text matching on the rendered screen and is kept per provider-agnostic phrase lists so a CLI wording change degrades to “no signal”.

uplink_calls

Node calls (mail.*, task.*) over the restreamer uplink.

uplink_journal

Persistent uplink journal and JournalReq responder for the A2 restreamer.

wake_pipeline

The node’s letter pipeline: letter in -> policy -> g4a deliver (or refuse; the letter stays in the inbox).

wg_status

Process-wide WireGuard health for /health and logs. No secrets.

windows_process

Windows process-creation helpers for non-PTY children.

Structs

BundleCatalog

Bounded immutable lookup table for bundles installed before node startup.

ManagedWorktreeProfile

NativeHistoryConfig

NativeHistoryRoot

NetworkAllowlistCatalog

Empty-default station network allowlist catalog.

NetworkAllowlistEntry

One node-local catalog entry. Wire / inventory still use SpawnNetworkAllowlistId.

NetworkPermitSketch

dig2browser-spirit peer+protocol permit (node-local; non-secret).

NodeBundle

Immutable host-local bundle bytes and their public content receipt.

NodeBundleFile

One immutable, normalized file captured from a validated bundle root.

NodeEnvironmentProfile

Immutable host-local binding from one public profile revision to native child-environment resolvers. Resolver values remain inside the native profiles and are never serialized or formatted for diagnostics.

NodeLetter

One letter for a session of this node.

NodeSecretReference

NodeServer

NodeServerConfig

NodeSessionMaterializationProfile

NodeSessionPathBinding

NodeShutdownHandle

NodeWake

NodeWgPeerConfig

ProviderNativeNetworkSketch

Honest, partial provider-native network mapping (node-local).

SpawnProfileRegistry

WgStatus

WorkspaceConfig

Enums

BundleCatalogError

HistorySourceLayout

NetworkAllowlistCatalogError

NetworkPermitProtocol

Allowed permit protocols (string form in JSON: tcp / udp).

NodeBundleError

NodeEnvironmentProfileError

NodeSecretResolveError

NodeSecretValue

NodeSecretValueError

NodeServerError

NodeSessionEnvironmentMutation

NodeSessionFile

NodeSessionMaterializationProfileError

NodeSessionPathClass

NodeWgPeerError

SpawnProfileRegistryError

WorktreeServiceMode

Constants

CLAUDE_STATION_NETWORK_SETTINGS_FILE

Sidecar settings filename under ProviderHome (CLAUDE_CONFIG_DIR home/).

DEFAULT_SPAWN_PROFILE_ID

MAX_BUNDLE_CATALOG_ENTRIES

MAX_BUNDLE_FILES

MAX_BUNDLE_FILE_BYTES

MAX_BUNDLE_PATH_BYTES

MAX_BUNDLE_TOTAL_BYTES

MAX_NETWORK_ALLOWLIST_CATALOG_ENTRIES

Soft bound on station network allowlist catalog membership (ids only). Soft bound on station network allowlist catalog ids exposed on launch inventory.

MAX_NETWORK_PERMITS_PER_ENTRY

Soft bound on permit rows per catalog entry (dig2 MAX_NETWORK_PERMITS spirit).

MAX_NODE_ENVIRONMENT_PROFILES

MAX_NODE_SECRET_REFERENCE_BYTES

MAX_NODE_SECRET_VALUE_BYTES

MAX_SESSION_ENVIRONMENT_ENTRIES

MAX_SESSION_MATERIALIZATION_FILES

MAX_SESSION_MATERIALIZATION_FILE_BYTES

MAX_SESSION_MATERIALIZATION_RELATIVE_PATH_BYTES

MAX_SPAWN_PROFILES

NETWORK_ALLOWLIST_CATALOG_ENV

Env path to an optional allowlist catalog file (absolute regular file). Unset → empty catalog (deny unknown at resolve). Never a secret store.

NETWORK_ALLOWLIST_CATALOG_SCHEMA_VERSION

Structured catalog schema version (JSON v2).

WG_ADDRESS_ENV

WG_INTERFACE_ENV

WG_KEEPALIVE_ENV

WG_LISTEN_PORT_ENV

WG_PEER_ADDRESS_ENV

WG_PEER_ENDPOINT_ENV

WG_PEER_KEY_ENV

WG_PRIVATE_KEY_ENV

WIREGUARD_LINK_TAG

Link tag so the kit binary retains this module.

Traits

NodeSecretResolver

Functions

bring_up_node_wireguard

Creates the node↔C2 WireGuard peer. Allowed IPs and the installed route are only the C2 tunnel host. Linux: ip link add type wireguard, and a failed ip is an error. Windows, no tun on the machine: one adapter and a host route for the peer. Windows, a tun already owns the default route: no adapter and no route. The WireGuard session runs in this process and its UDP leaves through that tun.

claude_allowed_domains_from_permits

Deduplicated Claude allowedDomains from catalog permits (stable order).

claude_bash_sandbox_network_os_supported

Vendor Bash sandbox network overlay is macOS / Linux / WSL2 only. Native Windows (and WSL1 host without Linux node) has no vendor sandbox — refuse rather than silent no-op or invented argv.

claude_settings_network_overlay_args

Documented Claude CLI argv: --settings <absolute-path>.

claude_station_network_settings_json

Settings JSON fragment for Claude Bash sandbox network (vendor documented sandbox.enabled + sandbox.network.allowedDomains).

codex_network_access_config_overlay

Codex -c overlay for legacy sandbox_workspace_write.network_access.

default_node_endpoint

default_state_path

load_network_allowlist_catalog_file

Load catalog from path (absolute regular file). Dual format.

node_wg_from_env

Optional service-mode bring-up. Unset WG_INTERFACE_ENV leaves the tunnel down. The key is a path, never a secret value in the unit file.

orca_home_roots

Pinned Orca-compatible roots beneath an explicitly supplied native home.

parse_network_allowlist_catalog_text

Parse catalog text: JSON v2 when first non-comment content is {, else v1 id-list (one id per line).

permit_peer_to_allowed_domain

Map catalog permit peer → Claude sandbox.network.allowedDomains host.

provider_native_mapping_supported

Whether provider_native on a catalog entry can be honored for provider at the resolved ApprovalLevel.

resolve_network_allowlist_catalog

Resolve optional catalog from an explicit path, else from NETWORK_ALLOWLIST_CATALOG_ENV, else empty.

resolve_provider_native_launch_overlay

Resolve provider-native launch overlay argv for a catalog entry, or refuse.

spawn_linux_wireguard_retry

Spawn a background retry loop for Linux kernel WireGuard. The node process stays up while the tunnel is down (WgStatus reports down).