ngentx

ngentx is an MCP server you run on your server — like nginx, but instead of serving web traffic it serves your host to an AI agent.

Install it on a machine, start it, point Claude Code (or any MCP client) at its URL, and the agent can inspect and operate that machine: run commands, read and edit config files, tail logs, check load and processes — without you SSH-ing in and pasting output back and forth.

┌──────────────────┐        MCP over HTTPS         ┌──────────────────────┐
│  Claude Code /   │  ─────────────────────────▶   │  your server         │
│  any MCP client  │      Bearer <token>           │  ngentx  ── shell    │
│  (your laptop)   │  ◀─────────────────────────   │          ── files    │
└──────────────────┘                               │          ── system   │
                                                   └──────────────────────┘

Early. The protocol surface works end to end, the tool set is small and deliberate, and the config is where the security story lives. Feedback and issues welcome.

One line, prebuilt binary (Linux x86_64/aarch64, macOS):

curl -fsSL https://raw.githubusercontent.com/imduchuyyy/ngentx/main/install.sh | sudo sh

That drops ngentx in /usr/local/bin, writes /etc/ngentx/ngentx.toml with a freshly generated token (never overwriting an existing config), and installs the systemd unit without starting it. VERSION=v0.1.0 and PREFIX=/usr override the defaults; sudo sh install.sh --uninstall reverses it, --purge also removes the config.

From source (needs Rust 1.85+):

git clone https://github.com/imduchuyyy/ngentx
cd ngentx
sudo make install

Same result as the installer, built locally. sudo make uninstall / sudo make purge to remove.

Manual, if you'd rather place everything yourself:

cargo build --release
sudo install -m 755 target/release/ngentx /usr/local/bin/ngentx

Both install paths already wrote /etc/ngentx/ngentx.toml with a token, so this is a review step rather than a setup step:

sudo $EDITOR /etc/ngentx/ngentx.toml
ngentx check --config /etc/ngentx/ngentx.toml

Starting from scratch instead:

sudo mkdir -p /etc/ngentx
sudo cp ngentx.example.toml /etc/ngentx/ngentx.toml
ngentx token                       # generate an auth token, paste it in

See ngentx.example.toml for every option. The parts that matter most:

ngentx serve --config /etc/ngentx/ngentx.toml

Or as a service:

sudo cp contrib/ngentx.service /etc/systemd/system/
sudo systemctl enable --now ngentx

ngentx stdio runs the same tools over stdio, which is handy for testing locally before you expose anything.

Claude Code:

claude mcp add --transport http my-server https://server.example.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Or in .mcp.json / any MCP client config:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://server.example.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

Then ask the agent things like "why is nginx returning 502?" and let it look for itself.

Tools whose section is disabled in the config are not advertised at all.

ngentx hands a remote model a shell on your machine. Treat it like sshd:

• Always keep auth.enabled = true and use the long random token from ngentx token. Requests without a matching Authorization: Bearer header get a 401.
• Terminate TLS in front of it. Bind to 127.0.0.1 and reverse-proxy through nginx or caddy; the token is only as safe as the transport.
• Narrow the blast radius in config. shell.deny, shell.allow, fs.roots, and fs.read_only exist so the agent gets what the job needs and nothing else. A read-only ngentx for triage is a great first deployment.
• Don't run as root unless you must. The bundled unit file does, because service management usually needs it; a dedicated user is better whenever the work allows.
• server.allowed_hosts / allowed_origins guard against DNS-rebinding when the server is reachable from a browser context.

cargo test
cargo clippy --all-targets -- -D warnings
cargo fmt

make check runs fmt, clippy and tests the way CI does. make install PREFIX=/tmp/fakeroot CONFDIR=/tmp/fakeroot/etc/ngentx exercises the install path without touching the real system.

Smoke-test the HTTP surface without a client:

NGENTX_TOKEN=$(ngentx token) cargo run -- serve
curl -H "Authorization: Bearer $NGENTX_TOKEN" \
     -H 'Accept: application/json, text/event-stream' \
     -H 'Content-Type: application/json' \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
     http://127.0.0.1:8420/mcp

MIT — see LICENSE.