HostMesh

Give AI agents safe, structured access to your Linux servers.

HostMesh is a local-first control plane for MCP-compatible clients such as Cursor, Claude Code, and Codex. The Portal, policy engine, identities, audit log, and SQLite database stay on your machine; remote Linux hosts run a deterministic agent reached through SSH.

Quick install

Install the Local Control Plane on macOS or Linux (amd64 or arm64):

curl -fsSL https://github.com/sotarak/hostmesh/releases/latest/download/install-hostmesh.sh | bash

The installer downloads the release archive, verifies its SHA-256 checksum, installs hostmesh into ~/.local/bin, and starts a per-user service. It uses LaunchAgent on macOS and a systemd user service on Linux. No root daemon or shell-profile edit is required.

The Portal opens at http://127.0.0.1:47821. To inspect the script before running it, download install-hostmesh.sh from the release page first.

To build instead:

git clone https://github.com/sotarak/hostmesh.git
cd hostmesh
make build
./bin/hostmesh start

See Installation for upgrades, service locations, manual builds, and uninstall options.

Add your first server

1. Open the Portal and create a workspace.
2. Go to Servers → Add server.
3. Enter the SSH host, port, user, and labels.
4. Copy the generated command and the one-time enrollment token.
5. Run the command on the Ubuntu server and enter the token when prompted.

curl -fsSL https://github.com/sotarak/hostmesh/releases/latest/download/install-agent.sh | sudo bash

The token is read from /dev/tty, so it does not appear in shell history or process arguments. It is short-lived, single-use, and bound to one workspace and server. The agent listens only on 127.0.0.1:7443; HostMesh reaches it through an SSH tunnel.

Core features

• Local Portal, API, SQLite state, controller identity, and one stdio MCP server.
• Workspace-scoped server registry and label selectors.
• SSH-first enrollment with permanent Ed25519 controller/agent trust.
• Signed, target-bound controller requests and agent responses.
• Semantic system, process, file, service, and network inspection.
• Reusable custom policies with managed templates and server attachments.
• Deny-by-default evaluation with DENY > APPROVAL > ALLOW.
• Agent-side hard denies, bounded execution/output, and two-phase audit events.
• Local server removal separated from remote agent uninstall.

Current implementation status and future work live in Project status and roadmap, not in this README.

How it works

Cursor / Claude Code / Codex
             │
             │ MCP (stdio)
             ▼
┌─────────────────────────────┐
│ HostMesh Local Control Plane│
│ Portal · Workspaces · Policy│
│ Connections · Audit · SQLite│
└──────────────┬──────────────┘
               │ SSH tunnel
               ▼
┌─────────────────────────────┐
│ Linux server                │
│ hostmesh-agent              │
│ 127.0.0.1:7443              │
└─────────────────────────────┘

Every remote operation follows the same path:

MCP → workspace target resolution → persisted policy → audit start
→ SSH transport → signed agent request → agent validation
→ signed response → audit completion

Policies

The Portal includes reusable policy templates:

• Default read-only diagnostics for the normal inspection workflow.
• Log files reader for file.read beneath /var/log/** only.
• System inspector for system, process, service, and network metadata without file access.

Templates are cloned into editable custom policies and attached to servers. Use Replace current policies when reducing a server to least privilege; adding policies unions their rules. No matching rule means deny.

MCP setup

Ensure hostmesh is on the MCP client's PATH, then configure one local MCP server:

{
  "mcpServers": {
    "hostmesh": {
      "command": "hostmesh",
      "args": ["mcp"]
    }
  }
}

Choose the default workspace with hostmesh workspace use <workspace-id>. Tools target a server by name/ID or a bounded label selector; HostMesh never creates one MCP namespace per server. See MCP.

Uninstall

Remove a remote Ubuntu agent while preserving its identity/state:

curl -fsSL https://github.com/sotarak/hostmesh/releases/latest/download/uninstall-agent.sh | sudo bash

Remove the local controller while preserving local data:

curl -fsSL https://github.com/sotarak/hostmesh/releases/latest/download/uninstall-hostmesh.sh | bash

Both uninstallers support --purge; destructive purge requires an interactive confirmation or explicit --yes. Removing a server in the Portal only removes its local registry data—it never SSHes into the host or uninstalls the agent.

Security

HostMesh is localhost-only and local-first, but it is not yet presented as production-grade security software. Important controls include workspace isolation, one-time enrollment, permanent identities, signed target-bound protocol messages, policy resource constraints, agent hard denies, checksum-verified artifacts, and bounded audit-safe operations.

Review the threat model and current limitations in Security. Report vulnerabilities through SECURITY.md, not a public issue.

Documentation

• Installation
• Architecture
• Enrollment
• Policies
• Portal
• MCP
• Development
• GitHub Releases
• Project status and roadmap

Contributing

Focused issues and pull requests are welcome. Read CONTRIBUTING.md and AGENTS.md before changing protocol, policy, enrollment, transport, or other trust boundaries.

License

MIT