The Nodetonet CLI — install the agent, pair it, and drive tunnels from the terminal

This page documents how to drive Nodetonet from the command line in 2026. We'll be transparent about one thing up front: we don't yet ship a single-binary nodetonet CLI like ngrok http 3000. That's on the public roadmap and we'll get there. In the meantime, the agent is a CLI binary, the REST API is fully featured, and a 30-second shell function gets you most of the way.

Bottom line: if you can use curl and you have a Bearer token, you can do anything the web panel can do — create HTTP tunnels, manage mobile proxies, query live stats, rotate IPs and tear everything down in CI — all without touching a browser.

What you can do from the terminal today

Before diving into commands, here is a quick map of what the API covers versus what a future CLI binary will add:

The API surface is stable and versioned — anything you script today will keep working when the CLI ships, because the CLI is just a friendly wrapper on the same endpoints.

1 · Install the agent

The agent is a single Node.js bundle shipped as a precompiled binary for Linux, macOS, and Windows. The one-line installer detects your OS/arch and drops the binary into /usr/local/bin/nodetonet-agent (or $HOME/.local/bin on user installs). This agent also powers the Windows .exe that hosts HTTP tunnels on a VDS — the same binary, different role.

# macOS / Linux — installs to /usr/local/bin (uses sudo)
curl -fsSL https://nodetonet.com/agent/install.sh | sh

# User install — no root, drops into ~/.local/bin
curl -fsSL https://nodetonet.com/agent/install.sh | INSTALL_DIR=$HOME/.local/bin sh

# Windows (PowerShell)
iwr https://nodetonet.com/agent/install.ps1 -useb | iex

After the installer finishes, nodetonet-agent --version should print the build hash and version. The SHA-256 of every release is published next to the binary under /download so you can verify the artifact before you trust it. See also the full agent installation guide for troubleshooting tips.

2 · Pair the agent

The agent only talks to your account after it has been paired. Pairing is a one-time exchange: the agent generates a keypair, the panel issues a pairing token (8-char code), and once you paste the code into nodetonet-agent pair, the device shows up under your account dashboard ready to accept tunnels.

$ nodetonet-agent pair
Paste the 8-char pairing code from the panel: AB12-CD34

v Paired as 'web-1' (id: 8f3e...c4)
v Agent registered with hub wss://hub.nodetonet.com
v Status: online - uptime budget OK - accepting tunnels

From this point the agent stays connected over a persistent WebSocket. You can run as many tunnels through it as your token group allows. The keypair is stored locally (~/.config/nodetonet-agent/keys.json on macOS/Linux, %APPDATA% odetonet-agentkeys.json on Windows) and never leaves your machine in plaintext.

3 · Get a Bearer token

Every API call is authenticated with a Bearer token scoped to your account. Generate one from the panel under your profile settings, or programmatically:

# Create a token via the API (you need one token to create more — use the panel for the first one)
curl -X POST https://nodetonet.com/api/v1/tokens   -H "Authorization: Bearer $NTN_TOKEN"   -H "Content-Type: application/json"   -d '{"name": "ci-bot", "scopes": ["proxies:write", "proxies:read"]}'

Store the token in your CI secrets manager (GitHub Actions Secrets, GitLab CI Variables, etc.) — never commit it to source control. For a full walkthrough see understanding your API key and customer API tokens vs personal tokens.

4 · Create a tunnel from the command line

Until the dedicated CLI ships, the canonical "make a tunnel" command is a curl call to POST /api/v1/proxies with your Bearer token. The REST API first call guide covers authentication and error handling in depth.

export NTN_TOKEN="ntn_live_xxxxxxxxxxxxxxxx"

curl -X POST https://nodetonet.com/api/v1/proxies   -H "Authorization: Bearer $NTN_TOKEN"   -H "Content-Type: application/json"   -d '{
    "name": "dev-server",
    "subdomain": "alice-dev",
    "target_host": "127.0.0.1",
    "target_port": 3000,
    "device_id": "8f3e...c4"
  }'

The response includes the public URL, the auto-issued Let's Encrypt cert status, and the proxy id you'll need for later PATCH / DELETE calls. Certificates renew automatically — see Let's Encrypt auto-renewal for how that works.

{
  "id": "px_01HXXXX",
  "url": "https://alice-dev.nodetonet.com",
  "status": "running",
  "created_at": "2026-05-15T09:14:22Z"
}

5 · A drop-in shell function

Drop this into ~/.zshrc or ~/.bashrc and you have a passable ngrok http 3000 equivalent today:

ntn() {
  local port="${1:-3000}"
  local sub="${2:-$(whoami)-dev}"
  curl -fsS -X POST https://nodetonet.com/api/v1/proxies \
    -H "Authorization: Bearer $NTN_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"subdomain\":\"$sub\",\"target_host\":\"127.0.0.1\",\"target_port\":$port}" \
    | jq -r '.url'
}

# usage:  ntn 3000           -> prints https://alice-dev.nodetonet.com
#         ntn 8080 my-api    -> prints https://my-api.nodetonet.com

Because idle tunnels cost nothing on Nodetonet's prepaid-credit model, you can call this at the start of every dev session and not worry about forgetting to clean up — there's no metered clock ticking in the background.

6 · Programmatic examples — list, update, delete

The same three verbs you'd expect:

# list every proxy on your account
curl -H "Authorization: Bearer $NTN_TOKEN"      https://nodetonet.com/api/v1/proxies

# stop one (no charge while stopped)
curl -X PATCH -H "Authorization: Bearer $NTN_TOKEN"      -H "Content-Type: application/json"      -d '{"status":"stopped"}'      https://nodetonet.com/api/v1/proxies/px_01HXXXX

# delete one
curl -X DELETE -H "Authorization: Bearer $NTN_TOKEN"      https://nodetonet.com/api/v1/proxies/px_01HXXXX

Full schema for every endpoint lives at /openapi.json; paste that URL into Postman, Insomnia, or any OpenAPI code generator to get a typed client in seconds. For a Python example see programmatic tunnel creation in Python.

7 · Using the API in CI/CD

A common CI pattern: spin up a tunnel at job start, run your integration tests against the public URL, then tear down. Because the API is stateless and tunnels are cheap to create and delete, this is safe to do in parallel across many jobs.

# .github/workflows/integration.yml (excerpt)
- name: Start tunnel
  run: |
    URL=$(ntn $PORT preview-$GITHUB_RUN_ID)
    echo "TUNNEL_URL=$URL" >> $GITHUB_ENV

- name: Run tests
  run: npx playwright test --base-url $TUNNEL_URL

- name: Tear down tunnel (always)
  if: always()
  run: curl -X DELETE -H "Authorization: Bearer $NTN_TOKEN"        https://nodetonet.com/api/v1/proxies/$TUNNEL_ID

For managing mobile proxy pools in automation — rotating IPs, triggering IP changes, reading live byte counts — the same REST API applies under /api/v1/rotating-proxies. See bulk operations for 100+ proxies for the patterns that scale.

8 · Coming: a real ngrok-style CLI

The shell function above gets you 80% of the way. The remaining 20% — the things that actually need a real CLI binary — are on the roadmap:

• nodetonet http 3000 — single-command tunnel, prints URL, holds the foreground, tears down on Ctrl+C.
• nodetonet tcp 5432 — TCP tunnels with the same UX, useful for database connections over the public internet.
• nodetonet config — store your token in the OS keychain so you never have to export NTN_TOKEN again.
• A live request inspector that streams to your terminal — request line, headers, body preview — no browser panel needed.
• Shell completions for bash, zsh, and fish.
• nodetonet proxy rotate — trigger an IP change on a rotating proxy device directly from the terminal.

The CLI is tracked as CLI · Q3 2026. If you want to be a beta tester, reach out on the contact page or join the community on Discord at discord.gg/nodetonet.

Security checklist for terminal use

• Never log or commit your NTN_TOKEN — use your CI provider's secret store.
• Generate scoped tokens with the minimum permissions needed for each job (proxies:read vs proxies:write).
• Rotate tokens regularly; the DELETE /api/v1/tokens/:id endpoint revokes instantly.
• Pin your install.sh to a specific version hash and verify the SHA-256 published at /download.
• If your CI runner is shared, scope the token to your project namespace, not your full account. See customer API tokens vs personal tokens for guidance.

Get started

Ready? Download the agent, grab a Bearer token from your account, and open your first tunnel with the one-liner above. The full REST reference is at /openapi.json and the community is on Discord at discord.gg/nodetonet.