Installation & Quick Start
Relevant source files
The following files were used as context for generating this wiki page:
Honmoon is a polyglot monorepo comprising a Rust data plane and a TypeScript/Bun control plane. It functions as a policy-based firewall gateway designed to guard the boundary between AI agents and production systems by intercepting outbound traffic and applying allow, deny, or pause verdicts based on declarative policies.
Sources: wiki/getting-started/installation.md:8-11, wiki/index.md:7-11
Prerequisites & Toolchain
Honmoon utilizes mise to manage the project toolchain, ensuring consistent versions of Node and Bun across development environments. Rust is managed via the standard rustup toolchain as defined in the project's configuration.
Core Toolchain Requirements
| Tool | Version | Managed By |
|---|---|---|
| Rust | stable (1.85+, edition 2024) | rust-toolchain.toml |
| Node | 24 | mise.toml |
| Bun | latest (1.3.x) | mise.toml |
| Docker | 20.10+ (optional) | Manual (for Squid backend) |
Sources: wiki/getting-started/installation.md:14-20, README.md:164-169
Installation Steps
To set up the environment, clone the repository and use mise to install the managed runtimes:
# Clone the repository
git clone https://github.com/pleaseai/honmoon.git
cd honmoon
# Install runtimes (Node and Bun)
mise trust && mise install
# Install dependencies for Rust and TypeScript
mise run install
Sources: wiki/getting-started/installation.md:25-33, AGENTS.md:15-18
Project Build & Development
The project provides a unified task runner via mise that wraps both the Cargo (Rust) and Bun (JS/TS) ecosystems.
Common Development Tasks
| Command | Action |
|---|---|
mise run build | Builds the Rust workspace and Bun packages |
mise run test | Executes cargo test and bun test |
mise run lint | Runs clippy for Rust and eslint for JS |
mise run check | Runs the full quality gate (lint followed by test) |
Sources: wiki/getting-started/installation.md:37-54, AGENTS.md:19-24
The following diagram illustrates the quality gate flow executed during mise run check:
Quick Start: Running Honmoon
Honmoon provides multiple operating modes to protect agent traffic. The primary modes implemented are the Process Wrapper and the Gateway.
1. Process Wrapper Mode
The run command executes a child process while pointing its https_proxy environment variable to an ephemeral Honmoon proxy.
cargo run -p honmoon-cli -- run --policy policies/agent.yaml -- curl https://api.github.com
Sources: wiki/index.md:27-29, crates/honmoon-cli/src/main.rs:104-106
2. Gateway Mode
The gateway command starts a standalone proxy that can be shared across multiple agents. It typically serves the proxy on one port and the management dashboard on another.
cargo run -p honmoon-cli -- gateway --config policies/agent.yaml --addr 127.0.0.1:8443
Sources: wiki/index.md:31-33, crates/honmoon-cli/src/main.rs:114-123
Request Lifecycle
When an agent makes a request through the Honmoon gateway, the following flow occurs:
Sources: wiki/index.md:43-55, README.md:36-45
Operating Modes Summary
Honmoon is designed for three deployment shapes, although join is currently a planned feature.
| Mode | Command | Description |
|---|---|---|
| Process Wrapper | run | Wraps a single command; uses env-var isolation |
| Gateway | gateway | Centralized proxy for multiple clients |
| Join | join | (Planned) Routes host traffic to a gateway |
Sources: crates/honmoon-cli/src/main.rs:58-60, README.md:123-132
Conclusion
Setting up Honmoon involves a polyglot toolchain managed by mise, ensuring that both the high-performance Rust data plane and the TypeScript control plane are correctly configured. By utilizing either the process wrapper or the standalone gateway, developers can immediately begin enforcing security policies on AI agent network activity.