Isolation Modes
Relevant source files
The following files were used as context for generating this wiki page:
Honmoon provides multiple operating modes designed to isolate AI agents within a network boundary. These modes allow the system to intercept, inspect, and enforce policies on outbound network traffic before it reaches external destinations. The project defines three primary isolation strategies: Process Wrapper, Gateway, and Join.
The primary purpose of these modes is to guard the boundary between AI agents and production systems, ensuring that agents—which may run shell commands or call APIs—do not perform unauthorized or destructive actions such as exfiltrating data or deleting resources.
Sources: README.md:11-23, ARCHITECTURE.md:12-23, wiki/getting-started/overview.md:1-12
Operating Mode Overview
Honmoon's deployment shapes are categorized by how they intercept traffic. While the Process Wrapper and Gateway modes are currently implemented (Phase 1), the Join mode remains a planned feature.
| Mode | Command | Implementation Status | Core Mechanism |
|---|---|---|---|
| Process Wrapper | honmoon run -- <cmd> | Phase 1 (Advisory) | Sets proxy environment variables for child processes. |
| Gateway | honmoon gateway | Phase 1 (Functional) | Standalone central proxy accepting client connections. |
| Join | honmoon join | Planned | Routes all host traffic via a tunnel to a gateway. |
Sources: README.md:95-101, wiki/getting-started/overview.md:113-124, ARCHITECTURE.md:118-125
Process Wrapper (run)
The run command is designed to isolate a single process. It starts an ephemeral proxy and executes a child command, pointing the child's network configuration toward the Honmoon proxy.
Current Implementation and Limitations
In Phase 1, the Process Wrapper is considered advisory. It functions by setting proxy environment variables (like https_proxy) for the child process. Because it relies on the process respecting these variables, a malicious or poorly-configured agent could theoretically bypass the policy by ignoring environment-based proxy settings.
Full network-namespace isolation (Linux netns or macOS NetworkExtension) is tracked as technical debt (TD-003) and is scheduled for Phase 5 of the roadmap.
The diagram shows the lifecycle of a wrapped process, from proxy initialization to policy enforcement.
Sources: README.md:144-146, wiki/getting-started/overview.md:126-132, wiki/onboarding/executive-guide.md:46-51, ARCHITECTURE.md:121-123
Gateway Mode (gateway)
The gateway command launches a central proxy that loads a specific configuration and listens for incoming connections. This mode is suitable for a shared infrastructure where multiple agents or services point their traffic to a centralized Honmoon instance.
Architecture and Data Flow
The Gateway mode combines the data plane (proxy) with the management API and dashboard. It acts as a terminating CONNECT proxy. When an agent sends a CONNECT request, the gateway canonicalizes the host and evaluates it against the policy before establishing a tunnel.
This sequence illustrates the standard gateway flow for an outbound HTTP/HTTPS request.
Sources: README.md:98-99, crates/honmoon-cli/src/main.rs:9-11, ARCHITECTURE.md:52-67, wiki/getting-started/overview.md:118-119
Join Mode (join)
The join mode is a planned feature (Phase 5+) intended to route all traffic from a host through a tunnel to a remote Honmoon gateway.
Planned Mechanism
Unlike the process wrapper which targets specific commands, join aims to provide host-level isolation. In its current state in the codebase, the join command exists as a stub that triggers a bail! error, as the required tunneling infrastructure is not yet implemented.
Sources: README.md:100-101, crates/honmoon-cli/src/main.rs:58-60, wiki/getting-started/overview.md:120-121
Comparison of Isolation Hardening
The project roadmap indicates a progression from advisory isolation to hardened, OS-level enforcement.
| Phase | Maturity | Enforcement Level |
|---|---|---|
| Phase 1 | Advisory | Environment variables only; bypassable. |
| Phase 5 (Planned) | Hardened | Linux netns / macOS NetworkExtension. |
| Future (SaaS) | Fleet | Centralized policy and RBAC across many nodes. |
Sources: wiki/deep-dive/roadmap-open-core.md:21-36, wiki/onboarding/executive-guide.md:38-44, ARCHITECTURE.md:121-125
Summary
Honmoon's isolation modes provide a tiered approach to securing AI agents. The Gateway mode offers a functional centralized proxy, while the Process Wrapper provides a convenient but currently advisory method for isolating individual commands. Future developments (Phase 5) will introduce Join mode and transition the Process Wrapper to hardened OS-level network isolation to prevent policy bypass.
Sources: wiki/getting-started/overview.md:126-132, README.md:209-222