Crate hatchery_node 

Native Gate4Agent node server and runtime.

Re-exports

pub use machine_env::collect as collect_machine_environment;

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.

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).

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). When HATCHERY_M4A_AGENT_BIN and HATCHERY_M4A_ACCOUNTS_ROOT are set, every PTY spawn gets its own account: 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_signer_proxy

0.2.15 name of keystore_proxy.

machine_env

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

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).

Structs

BundleCatalog

Bounded immutable lookup table for bundles installed before node startup.

MailboxHandle

Handle of the background mailbox thread.

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

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 a kernel WireGuard interface for the node↔C2 peer. Allowed IPs and the installed route are only the C2 tunnel host. Does not substitute another transport when ip link add type wireguard fails.

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

force_link

Touches a real symbol in each enabled core so the node binary links them. Does not start a browser, a provider CLI, or a tunnel, and does not read a secret. The mailbox is started separately by start_mailbox.

linked_core_names

Names of the cores linked into this build, in owner order.

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.

start_mailbox

Start the mail4agent mailbox on a background thread (m4a only). Same daemon the standalone mail4agent binary runs.