CLI Reference nfltr

Reference for readers who already know their path. Use this page when you need concrete nfltr commands for hosted orchestration, worker execution, secure transport, or dashboard-managed operator flows.

If you still need to decide between the hosted control plane and a self-hosted deployment boundary, start with When to Use NFLTR before using this reference as your entry surface.

Start From The Right Command Path

After you choose a path, use the sections below as the deep command reference for flags, environment variables, examples, and operational details.

Installation

Download the binary for your platform from the landing page:

# Example: macOS Apple Silicon
chmod +x nfltr-darwin-arm64
sudo mv nfltr-darwin-arm64 /usr/local/bin/nfltr

Commands

nfltr http — HTTP Tunnel

Expose a local HTTP service through an encrypted tunnel.

nfltr http [port|url] [flags]

Arguments

If omitted, defaults to http://localhost:8080.

Flags

Access control flags

These flags protect different layers and can be combined:

--basic-auth and --share-auth are not redundant. --basic-auth runs on your machine and gates all incoming requests. --share-auth is sent to the server as a policy and only applies to the public share URL. Use both together to protect the browse URL with one password and the share URL with another.

Examples

# Basic — expose port 8080
nfltr http 8080

# Custom name — access at /browse/myapp/
nfltr http 3000 --name myapp

# Public share URL is included by default; disable with --no-share
nfltr http 8080 --no-share

# Multi-backend routing (route /api to port 3000, default to 8080)
nfltr http 8080 --route /api=3000

# Multiple backends
nfltr http 8080 --route /api=3000 --route /ws=4000

# Expose an HTTPS local service
nfltr http https://localhost:3443

# Verbose logging of all proxied requests
nfltr http 8080 --verbose

# Limited duration (auto-stop after 1 hour)
nfltr http 8080 --duration 3600

Connection banner

nfltr                  vX.Y.Z
Agent ID               myapp
Forwarding             https://nfltr.xyz/browse/myapp/ → http://localhost:8080

2026/03/25 10:20:55 Resolved identity: myapp
2026/03/25 10:20:55 Share URL: https://vivid-hawk.nfltr.xyz/
2026/03/25 10:20:55 Connected — waiting for requests... (press Ctrl+C to stop)

With --verbose, every proxied request is also logged:

[1] GET  /              → 200 (4521 bytes, 12ms)
[2] GET  /style.css     → 200 (1200 bytes, 3ms)

nfltr tcp — TCP Tunnel (Agent Side)

Expose a local TCP port (SSH, databases, Redis, etc.) through an encrypted gRPC tunnel. Run this on the machine that hosts the service.

nfltr tcp <port> [flags]

Flags

Examples

# Expose SSH
nfltr tcp 22 --name my-ssh

# Expose PostgreSQL
nfltr tcp 5432 --name my-db

# Expose Redis
nfltr tcp 6379 --name my-redis

Connection banner

nfltr vX.Y.Z starting TCP tunnel
  agent-id:  my-ssh
  server:    grpc.nfltr.xyz:443 (tls=true)
  tunnel:    TCP → localhost:22
Connected — TCP tunnel active for localhost:22

  Connect from another machine:
    nfltr tcp-connect my-ssh 22 --listen :<local-port> --server nfltr.xyz:443

  SSH example (if tunneling port 22):
    nfltr tcp-connect my-ssh 22 --listen :2222 --server nfltr.xyz:443
    ssh -p 2222 user@localhost

nfltr tcp-connect — TCP Client (Connect Side)

Connect to a remote agent's TCP service by creating a local TCP listener that tunnels connections through the server. Works with any TCP client (ssh, psql, redis-cli, mysql, etc.).

nfltr tcp-connect <agent-name> <port> [flags]

Arguments

Flags

Examples

# SSH to a remote machine
nfltr tcp-connect my-ssh 22 --listen :2222
ssh -p 2222 user@localhost

# Connect to a remote PostgreSQL
nfltr tcp-connect my-db 5432 --listen :5432
psql -h localhost -p 5432 mydb

# Redis — use random port (shown in banner)
nfltr tcp-connect my-redis 6379
redis-cli -p 54321

# MySQL
nfltr tcp-connect my-mysql 3306 --listen :3306
mysql -h 127.0.0.1 -P 3306 -u root

Connection flow

Your machine                  nfltr Server               Remote Agent
────────────                  ────────────               ────────────
ssh -p 2222 localhost
  │
tcp-connect listener ─HTTP /connect/my-ssh/22─────────→ TCPDispatcher
                                                          bridges gRPC
                              ←──gRPC ConnectTCP stream──── nfltr tcp 22
                                                                dials localhost:22
←─────────────────────────────────bidirectional bytes──────────────────────→

Comparison: server-configured vs tcp-connect

Prerequisite: The server must have tcp.enabled=true. The /connect/{agent_id}/{port} endpoint is available automatically.

SSH config shortcut

# ~/.ssh/config
Host my-ssh
  ProxyCommand nfltr ssh-proxy --name %h --port %p
  User admin

nfltr grpc — gRPC Tunnel new

Expose a local gRPC service through a TCP tunnel so it can be reached remotely via grpcurl, Postman gRPC, BloomRPC, or any gRPC client. Uses TCP tunneling (not HTTP proxy) to preserve HTTP/2 framing, trailers, and bidirectional streaming.

nfltr grpc <port> [flags]

Flags

Examples

# Expose local gRPC service
nfltr grpc 50051

# With custom name
nfltr grpc 50051 --name my-grpc-api

# Connect from another machine
nfltr tcp-connect <agent>.my-grpc-api 50051 --listen :50051 --server nfltr.xyz:443
grpcurl -plaintext localhost:50051 list

Connection banner

nfltr vX.Y.Z — gRPC tunnel to localhost:50051
  agent-id:  alice.my-grpc-api
  server:    grpc.nfltr.xyz:443 (tls=true)
  tunnel:    TCP → localhost:50051 (gRPC/HTTP2)
Connected — gRPC tunnel active for localhost:50051

  Connect from another machine:
    nfltr tcp-connect alice.my-grpc-api 50051 --listen :50051 --server nfltr.xyz:443

  Then test with grpcurl:
    grpcurl -plaintext localhost:50051 list
    grpcurl -plaintext localhost:50051 <service>/<method>

Why TCP tunneling?

gRPC requires HTTP/2 end-to-end — framing, trailers, and bidirectional streaming. The HTTP proxy path decomposes requests into protobuf envelopes, which breaks these semantics. TCP tunneling forwards raw bytes and preserves the protocol correctly.

Connection flow

Your machine                  nfltr Server               Remote Machine
┌────────────────                  ┌────────────               ┌────────────
grpcurl localhost:50051
  │
tcp-connect listener →HTTP /connect/agent/50051→ TCPDispatcher
                                                          bridges gRPC
                              ←──gRPC ConnectTCP stream──── nfltr grpc 50051
                                                                dials localhost:50051
←───────────────────────────────bidirectional gRPC bytes──────────────────→

nfltr command — Expose a CLI Command as an HTTP Endpoint new

Turn any CLI tool into an HTTP microservice, tunnelled through the server. POST requests pipe the body as stdin (or as a flag argument) to the command and return stdout as the response. GET / serves a chat-style web UI with markdown rendering.

nfltr command <cmd> [args...] [flags]

Flags

Examples

# Echo service (stdin → stdout)
nfltr command cat

# JSON formatter as a service
nfltr command jq .

# Python script (share URL included automatically)
nfltr command python3 myscript.py

# Shell pipeline
nfltr command sh -c "sort | uniq"

# GitHub Copilot CLI as a remote AI assistant:
nfltr command --name copilot --basic-auth 'admin:pass' \
  --body-as-arg -p --timeout 600 --model claude-sonnet-4 \
  --cwd /path/to/project \
  copilot -- --allow-all-tools

# Run on multiple repos (one instance per repo):
nfltr command --name copilot-frontend --body-as-arg -p \
  --cwd ~/projects/frontend copilot -- --allow-all-tools
nfltr command --name copilot-backend --body-as-arg -p \
  --cwd ~/projects/backend copilot -- --allow-all-tools

Web UI features

• Chat-style interface with user/assistant message bubbles
• Markdown rendering with syntax-highlighted code blocks
• Model selector dropdown (sends X-Model header per request)
• File attachment support
• Typing indicator during command execution
• Basic auth with session cookies (24h TTL)

How --body-as-arg works

Without it, the POST body is piped as stdin to the command. With --body-as-arg -p, the body is appended as a flag argument instead:

This is essential for tools like GitHub Copilot CLI that read input from a flag (-p) rather than stdin.

nfltr tail — Live File Streaming new

Stream the tail of any file via a public URL — like tail -f over the internet. Visitors see live updates via Server-Sent Events in a web UI with search, pause, and auto-scroll.

nfltr tail [flags] <file>

Flags

Endpoints served

Examples

# Stream syslog with a share URL
nfltr tail /var/log/syslog

# Show last 200 lines
nfltr tail --lines 200 /var/log/nginx/access.log

# Password-protected log stream
nfltr tail --basic-auth admin:secret app.log

# Named agent for easy identification
nfltr tail --name prod-logs /var/log/app.log

# Plain-text access from another machine
curl https://<share-url>/raw

nfltr terminal — Web-Based Terminal new

Open a browser-accessible xterm.js terminal on the agent machine, tunnelled through the server via HTTP polling. Works through any HTTP proxy — no WebSocket support required.

nfltr terminal [flags]

Flags

One of --basic-auth or --no-auth is required.

Examples

# Password-protected web terminal
nfltr terminal --basic-auth admin:secret

# Custom shell
nfltr terminal --shell /bin/zsh --basic-auth user:pass

# Named agent with share URL
nfltr terminal --name my-box --share --basic-auth admin:secret

# No auth (testing only)
nfltr terminal --no-auth

How it works

Browser (xterm.js)           nfltr.xyz             Agent machine
  ┌─ POST /input ───────────└── HTTP tunnel ──────└───────────────────────└
  │                      │                    │  nfltr terminal       │
  │─ GET  /output ──────────│────────────────────│  PTY └───┌ shell      │
  ┌─ GET  /resize ──────────├                    ├───────────────────────├
  ├───────────────────────├

Allocates a real PTY and starts a shell. HTTP polling at 50ms intervals delivers keystrokes and output — fully interactive, works through corporate proxies and firewalls.

nfltr shell vs nfltr terminal — which should I use?

Both give you remote shell access through a tunnel, but they work in fundamentally different ways:

Rule of thumb: Use nfltr terminal when you want a one-click browser shell with a shareable URL. Use nfltr shell when you need SCP, SFTP, port forwarding, or want to use your existing SSH client and config.

nfltr a2a — Agent-to-Agent Communication new

Direct messaging between agents through the relay server. Supports unary send/receive, persistent listening, and bidirectional streaming. In multi-pod deployments, messages are routed across pods automatically.

nfltr a2a <command> [flags]

Sub-commands

Flags

Examples

# Send a message to another agent
nfltr a2a send sensor-42 "get status"

# Pipe JSON through stdin
echo '{"cmd":"status"}' | nfltr a2a send sensor-42

# Listen for incoming messages
nfltr a2a listen --name responder

# Bidirectional pipe (interactive)
nfltr a2a pipe sensor-42

# Pipe a file through another agent
cat data.json | nfltr a2a pipe processor-agent > result.json

Use cases

• IoT sensor data collection (send + listen)
• Remote command execution between agents
• File transfer between machines behind NAT
• Interactive chat between two agents

nfltr p2p — Peer-to-Peer Direct Transfer new

Transfer files, chat, and audio/video calls directly between two machines. The server is used only for initial signaling — all data flows over a direct TCP connection between peers, authenticated with HMAC-SHA256 and encrypted with AES-256-CTR. This means lower latency, no server bandwidth costs, and true end-to-end encryption.

nfltr p2p <command> [flags]

Sub-commands

Shared flags

recv-specific flags

Examples

# ── File transfer (complementary pair) ──────────────
# Terminal 1: receiver waits for incoming files
nfltr p2p recv --name bob-laptop --output ~/received/

# Terminal 2: sender transfers a file
nfltr p2p send report.pdf bob-laptop

# Use the exact scoped peer ID when targeting another API key scope
nfltr p2p send report.pdf partner-key.bob-laptop

# ── Directory transfer ──────────────────────────────
nfltr p2p send ./project/ bob-laptop

# ── Restrict who can send to you ────────────────────
nfltr p2p recv --name bob-laptop --from alice-desktop

# ── Keep receiving multiple transfers ───────────────
nfltr p2p recv --name bob-laptop --keep

# ── Encrypted chat (both sides) ─────────────────────
# Terminal 1:
nfltr p2p chat bob-laptop --name alice-desktop

# Terminal 2:
nfltr p2p chat alice-desktop --name bob-laptop

# ── Audio/video call (both sides) ─────────────────
# Terminal 1 (caller):
nfltr p2p call bob-laptop --name alice-desktop

# Terminal 2 (receiver should already be listening):
nfltr p2p recv --name bob-laptop

# Headless mode (print URL instead of auto-open):
nfltr p2p call bob-laptop --name alice-desktop --no-browser
nfltr p2p recv --name bob-laptop --no-browser

Peer ID resolution: nfltr p2p list shows the peers visible to the current API key. If a peer appears as partner-key.bob-laptop, use that exact ID in send, chat, or call. A bare alias like bob-laptop only resolves when it is unique in that visible list.

How it works

1. Signaling — Both peers connect to the server via gRPC. The initiator sends an offer with a session token and candidate addresses; the responder replies with an answer.
2. Candidate gathering — Each peer discovers its local LAN IPs and queries a STUN server for its public (NAT-reflexive) address.
3. Direct connection — All candidates are dialed in parallel. The first working TCP path wins (LAN-direct, STUN-reflexive, or hairpin NAT).
4. HMAC authentication — A mutual HMAC-SHA256 challenge-response verifies both peers hold the same session token. Replay attacks are prevented by binding the HMAC to a unique session ID.
5. Encrypted transport — After authentication, both sides derive a shared AES-256 key and per-direction IVs from the token and challenges. All subsequent data is encrypted with AES-256-CTR — the connection is fully end-to-end encrypted.
6. Data transfer — Files, directories, chat messages, or call signaling/media flow over the encrypted direct TCP connection. The server is no longer involved.

A2A vs P2P — when to use which

A2A and P2P have similar-sounding subcommands but are not interchangeable — they solve fundamentally different problems:

Why similar names? Both have a "send" side and a "receive" side, but the similarity ends there. a2a send sends a text message through the server; p2p send transfers a file over a direct TCP connection. a2a pipe is like netcat through gRPC; p2p chat is an interactive terminal UI over a direct link. You cannot send files with A2A (no metadata, no checksums), and you cannot send arbitrary text messages with P2P send (it requires a file path).

nfltr shell — Embedded SSH Server new

Starts an embedded SSH server on the agent machine and exposes it through the TCP tunnel — no OpenSSH or sshd required. Remote users can access a shell via the browser terminal in the dashboard or through any SSH client. See shell vs terminal comparison to decide which to use.

nfltr shell [flags]

Authentication modes

At least one of --password, --authorized-keys, or --no-auth is required.

Flags

Examples

# Password auth
nfltr shell --password secret

# Public key auth
nfltr shell --authorized-keys ~/.ssh/authorized_keys

# No auth (smoke tests only)
nfltr shell --no-auth

Connecting

Once the shell agent is running, there are three ways to connect:

1. Browser terminal (dashboard) — click the ► Term button on the agent card in the dashboard. Requires http.terminal.enabled=true on the server (enabled by default on nfltr.xyz).

2. TCP connect + SSH

nfltr tcp-connect <agent-id> 22 --listen :2222
ssh -p 2222 user@localhost

3. SSH proxy

ssh -o ProxyCommand="nfltr ssh-proxy --name <agent-id> --port 22" user@agent

How it works

┌────────────┐  TCP tunnel  ┌─────────────┐  ConnectTCP  ┌────────────────────┐
│ SSH Client │─────────────→│  rpc-server │─────────────→│  nfltr shell       │
│ or Browser │              │             │              │  (embedded sshd)   │
└────────────┘              └─────────────┘              └────────────────────┘

The embedded SSH server listens on a random local port. The TCP tunnel forwards connections from the server to that port. No system-level SSH daemon is needed.

nfltr wg — WireGuard VPN Tunnel new

Create a full Layer 3 VPN tunnel using the WireGuard protocol. The agent runs in userspace (no root required) using gvisor netstack. The server relays opaque WireGuard packets — it never possesses session keys or sees plaintext IP traffic.

nfltr wg <command> [flags]

Sub-commands

Shared flags

socks5-specific flags

Examples

# Start WireGuard server on the agent
nfltr wg serve --name my-network

# Connect from another machine via SOCKS5 proxy
nfltr wg socks5 my-network --listen :1080

# Access remote services through the tunnel
curl --proxy socks5://localhost:1080 http://192.168.1.100:8080

# Configure browser to use SOCKS5 proxy for full network access
# Firefox: Settings → Network Settings → SOCKS Host: localhost, Port: 1080

How it works

1. Key exchange — WireGuard Curve25519 public keys are exchanged over gRPC metadata headers (x-wg-pubkey, x-wg-assigned-ip).
2. IP allocation — The server allocates CGNAT addresses (100.64.0.0/10) for each peer.
3. Tunnel establishment — gvisor netstack creates a userspace network stack — no kernel modules, no root, no /dev/tun.
4. Encrypted relay — All IP traffic (TCP, UDP, ICMP) is WireGuard-encrypted. The server relays opaque packets without decryption.

Encryption

WireGuard provides built-in end-to-end encryption using Curve25519 (key exchange), ChaCha20-Poly1305 (data encryption), and BLAKE2s (hashing). The server has no access to the plaintext IP traffic.

nfltr ssh-proxy — SSH ProxyCommand Helper

Acts as an SSH ProxyCommand that tunnels SSH sessions through the server's HTTP /connect/{agent_id}/{port} endpoint.

nfltr ssh-proxy --name <agent> [--port <port>] [flags]

Flags

SSH config example

# ~/.ssh/config
Host mydevice
    ProxyCommand nfltr ssh-proxy --name %h --port %p
    User admin

Then simply:

ssh mydevice          # connects through the nfltr tunnel
scp file mydevice:/path
sftp mydevice

Inline usage

ssh -o ProxyCommand="nfltr ssh-proxy --name myagent --port %p" user@myagent

nfltr status — Server Status

Check server connectivity and list connected agents.

nfltr status [flags]

Flags

Example output

nfltr dev

Server:  grpc.nfltr.xyz:443
URL:     https://nfltr.xyz
Status:  online
Latency: 668ms

nfltr diagnose — Connectivity Diagnostics

Run a comprehensive connectivity test against your configured NFLTR endpoints.

nfltr diagnose [flags]

Tests (in order):

1. DNS Resolution — resolves the server hostname
2. HTTP Connectivity — GET to the server's HTTPS endpoint
3. HTTPS/TLS — validates the TLS certificate chain
4. gRPC Port — TCP dial to the gRPC port
5. TLS Handshake — verifies TLS works on the gRPC port
6. Round-trip Latency — measures end-to-end HTTPS latency

Example output

nfltr dev — connection diagnostics

DNS resolution (grpc.nfltr.xyz)         OK    34.61.152.169
DNS resolution (nfltr.xyz)              OK    104.21.16.130, 172.67.212.183
TCP connection (grpc.nfltr.xyz:443)     OK    254ms
TLS handshake (grpc.nfltr.xyz:443)      OK    1.511s (TLS 1.3)
HTTP endpoint (https://nfltr.xyz)       OK    200 (622ms)
gRPC channel (grpc.nfltr.xyz:443)       OK    3ms

6/6 tests passed
All connectivity tests passed.

nfltr config — Configuration Management

Manage the nfltr configuration file (stored at ~/.config/nfltr/nfltr.json).

nfltr config <command>

Sub-commands

Examples

# Save your API key (stored as "default")
nfltr config add-api-key rpc_abc123...

# Save a friend's key with a label
nfltr config add-api-key rpc_xyz789... --name alice

# List all saved keys (* marks the active key)
nfltr config list-api-keys
# * default      rpc_...c123
#   alice        rpc_...z789

# Switch active key
nfltr config use-api-key alice

# Remove a key
nfltr config remove-api-key alice

# Check current config
nfltr config check

# Find config file
nfltr config path
# → /Users/you/.config/nfltr/nfltr.json

Per-command key selection

All commands accept --key-name <label> to use a specific named key without switching the global active key:

nfltr a2a send bob-laptop hello --key-name alice
nfltr http 8080 --key-name work
nfltr p2p chat bob-laptop --key-name bob

Priority chain: --api-key flag → NFLTR_API_KEY env → --key-name lookup → active key from config.

Config file format

{
  "api_key": "rpc_abc123...",
  "api_keys": {
    "default": "rpc_abc123...",
    "alice": "rpc_xyz789..."
  },
  "server": "grpc.nfltr.xyz:443",
  "name": "my-laptop"
}

Override with environment variable: NFLTR_CONFIG=/path/to/config.json

nfltr keys — API Key Management

Manage API keys offline (reads/writes the server-side key file directly, no running server required). This is an admin tool — run it on the machine where the server stores its key file.

nfltr keys <command> [flags]

Sub-commands

Common flags

Examples

# Generate a key for an agent
nfltr keys generate --name myagent
#   Agent ID:   myagent
#   API Key:    rpc_abc123...

# List all keys
nfltr keys list
#   AGENT ID         KEY PREFIX           CREATED
#   --------         ----------           -------
#   myagent          rpc_abc123...        2026-03-21T10:00:00Z

# Revoke a key
nfltr keys revoke --name myagent

nfltr mcp — MCP Stdio Server

Run the NFLTR MCP server over stdio for AI planners, workers, and collectors. This command registers discovery, proxy, and worker orchestration tools up front. Calls that need the live A2A control-plane connection still fail until that connection is available.

nfltr mcp [flags]

Flags

Examples

# Local proxy (default)
nfltr mcp

# Hosted planner bridge with explicit auth
nfltr mcp --proxy-url https://nfltr.xyz --server grpc.nfltr.xyz:443 --api-key "$NFLTR_API_KEY"

# Hosted proxy with env vars
NFLTR_PROXY_URL=https://nfltr.xyz NFLTR_API_KEY=... nfltr mcp

# Generate VS Code MCP config
nfltr mcp --proxy-url https://nfltr.xyz --write-mcp-json .vscode/mcp.json

Planner task snapshots and append-only task events persist locally by default beside the nfltr config file at dirname(NFLTR_CONFIG)/orchestrator-tasks.json, usually ~/.config/nfltr/orchestrator-tasks.json, so get_task_status, get_task_events, and list_active_tasks can recover best-effort last-known state after a planner restart. Use --task-store-file or NFLTR_TASK_STORE_FILE to override the path.

The local JSON store writes snapshots and lifecycle events separately, so an abrupt crash can still leave those two views one write apart. Crash-consistent replay is future shared-backend work.

If that file-backed store cannot be opened, nfltr mcp logs a warning and falls back to in-memory task tracking for the current process only.

If one planner runs on one machine and stays up, this local store is usually enough. Shared persistence only matters when the planner process restarts under a supervisor, moves between hosts, or another process needs the same orchestration history.

Core tool groups exposed by nfltr mcp:

• list_my_peers and proxy_request for raw discovery and HTTP relay
• list_worker_peers, rank_worker_peers, and probe_worker for worker selection
• orchestrate_task, delegate_handoff, get_task_status, get_task_events, respond_to_worker, cancel_task, and list_active_tasks for planner-worker control flow; delegate_handoff also supports wait_for_child to fan child results back into the parent reply

nfltr copilot-mcp — Copilot-Backed MCP Worker Tool

Run a local MCP stdio server that exposes a single worker tool backed by the GitHub Copilot CLI. Use this as the --mcp-command target for nfltr worker on machines that have Copilot CLI but no native MCP server command.

nfltr copilot-mcp [flags] [-- copilot-args...]

Flags

Examples

# Start a local Copilot-backed MCP worker tool
nfltr copilot-mcp --cwd ~/project

# Pin the worker to one model and reasoning profile
nfltr copilot-mcp --cwd ~/project --model gpt-5.2 --reasoning-effort high

# Pass through extra Copilot CLI flags
nfltr copilot-mcp --cwd ~/project --verbose --copilot-arg=--stream=off

# Use it behind an nfltr worker
nfltr worker --api-key YOUR_KEY --mcp-command "nfltr copilot-mcp --cwd ~/project"

Use explicit flags like --model, --mode, and --reasoning-effort for common Copilot settings. Arguments after -- and repeated --copilot-arg flags are passed straight through to the underlying copilot CLI.

nfltr worker — A2A Worker Runtime

Run an A2A worker that accepts orchestrated tasks and forwards them to a local MCP-capable AI tool. The local MCP server is launched via --mcp-command and must expose the tool named by --mcp-tool.

nfltr worker [flags]

Connection flags

Worker flags

Examples

# Start a worker backed by a native MCP server
nfltr worker --api-key YOUR_KEY --mcp-command "claude mcp serve"

# Advertise labels and accept up to two concurrent tasks
nfltr worker --api-key YOUR_KEY --labels gpu=a100,ram=64g --max-tasks 2 --mcp-command "python3 ./worker_mcp.py"

# Run a Copilot-backed worker
nfltr worker --api-key YOUR_KEY --verbose --mcp-command "nfltr copilot-mcp --cwd ~/project --verbose"

# Supply the worker MCP command through env vars
NFLTR_WORKER_MCP_COMMAND="python3 ./worker_mcp.py" nfltr worker --api-key YOUR_KEY --mcp-tool run_task

Workers automatically advertise scheduling labels such as coord.cpu_cores, coord.memory_mb, coord.load_pct, coord.transfer, nfltr.worker.protocol, nfltr.worker.tool, and nfltr.worker.max_tasks. Run nfltr worker --help to see the full set of shared connection flags inherited from nfltr a2a.

nfltr version

Print the version string.

nfltr version
# → nfltr dev

nfltr demo

Interactive feature showcase — 10 numbered sections covering every capability with copy-pasteable commands. Shows the current platform, version, and auto-generated agent ID. Requires no API key or network connection.

nfltr demo

nfltr db — Database Tunnel new

Connect to a remote database through a tunnel with database-aware defaults. Wraps tcp-connect with automatic port selection, connection string generation, and CLI client recommendations.

nfltr db <agent-name> <engine> [flags]

Supported engines

Flags

Examples

# Connect to remote PostgreSQL
nfltr db my-server postgres
# → Listening on localhost:5432
# → psql -h localhost -p 5432 -U postgres

# MySQL with user and database hints
nfltr db my-server mysql --user root --dbname myapp
# → mysql -h 127.0.0.1 -P 3306 -u root myapp

# Redis on a custom local port
nfltr db my-server redis --listen :6380
# → redis-cli -p 6380

nfltr serve — HTTP File Server new

Start a local HTTP file server and expose it through a tunnel with an instant public URL. Like python -m http.server but with a share URL.

nfltr serve [path] [flags]

Arguments

Flags

Examples

# Serve the current directory
nfltr serve .

# Serve a build output
nfltr serve ./dist

# Serve a single file
nfltr serve file.zip

# Password-protected share
nfltr serve . --basic-auth admin:secret

# Named agent
nfltr serve ./public --name my-files

nfltr share — Instant Ephemeral URL new

Create an instant, ephemeral URL to share text, a file, or a directory. Content served through the tunnel until Ctrl+C or auto-expiration.

nfltr share [text|file|dir] [flags]

Flags

Examples

# Share text — wraps in a styled HTML page with copy button
nfltr share "error: connection refused on port 5432"

# Pipe from stdin
echo "build log" | nfltr share
git diff | nfltr share

# Share a file for download
nfltr share ./crash.log

# Share a directory with file listing
nfltr share ./dist/

# Auto-expire after 30 minutes
nfltr share "temporary secret" --expire 30m

# Password-protected
nfltr share ./secrets.env --share-auth admin:s3cret

# Plain text (curl-friendly)
nfltr share "data" --raw

nfltr manage — Dashboard-Managed Runtime new

Start one long-lived browser-capable tunnel, then let the dashboard stage Copilot, browser shells, HTTP apps, command UIs, and log tails as durable desired state.

nfltr manage [flags]

Flags

Supported managed capability types

The current single-tunnel runtime can execute http, serve, command, tail, terminal, copilot, claude, codex, and generic ai when config.command is set. The dashboard still accepts tcp, grpc, shell, and watch, but this runtime reports them as unsupported.

Examples

# Start a dashboard-managed runtime on nfltr.xyz
nfltr manage \
  --name dev-laptop \
  --api-key "$NFLTR_API_KEY" \
  --http-addr https://nfltr.xyz \
  --basic-auth review:secret

# Dashboard recipes after the runtime is up:
# Copilot   -> Type=copilot, Target=/home/alice/repo, Config=mode=chat
# Shell     -> Type=terminal, Target=/bin/bash
# HTTP app  -> Type=http, Target=http://localhost:3000
# Generic AI-> Type=ai, Target=/home/alice/repo, Config=command=copilot,mode=chat

Access pattern

Each running capability is mounted under the manage root:

/browse/<agent-id>/managed/<capability-id>/

The dashboard Open button points at that path once the runtime reports it.

For the full setup flow, see Managed Capabilities.

nfltr watch — Live Command Dashboard new

Run a command periodically and stream live-updating output via a share URL. Like watch + tail -f combined, accessible from anywhere via Server-Sent Events.

nfltr watch [flags] <command> [args...]

Flags

Endpoints served

Examples

# Monitor Kubernetes pods
nfltr watch "kubectl get pods"

# Disk usage with 5-second refresh
nfltr watch --interval 5s df -h

# Docker container status
nfltr watch "docker ps --format 'table {{.Names}}\t{{.Status}}'"

# Auto-expire after 1 hour
nfltr watch --expire 1h "uptime"

# Password-protected dashboard
nfltr watch --basic-auth admin:secret "top -b -n 1"

nfltr clipboard — Cross-Machine Clipboard new

Sync clipboard content between machines via A2A messaging.

nfltr clipboard <command> [flags]

Sub-commands

Flags

Examples

# Copy local clipboard to a work machine
nfltr clipboard copy work-laptop

# Copy specific text
nfltr clipboard copy work-laptop "some text to share"

# Pipe text to clipboard
cat secret.env | nfltr clipboard copy work-laptop

# Retrieve clipboard from remote machine
nfltr clipboard paste work-laptop

# Output to stdout instead of local clipboard
nfltr clipboard paste work-laptop --stdout

nfltr notify — Desktop Notifications new

Send desktop notifications to remote agents, listen for incoming notifications, or watch a command and notify when done.

nfltr notify <command> [flags]

Sub-commands

Flags

Examples

# Send a notification to your work laptop
nfltr notify send work-laptop "Build finished!"

# With a custom title
nfltr notify send work-laptop "Tests passed" --title "CI"

# Listen for incoming notifications
nfltr notify listen --name my-laptop

# Run a command and notify when done
nfltr notify watch work-laptop make test
nfltr notify watch work-laptop -- long-running-script.sh

nfltr ai — Remote AI CLI new

Run an AI CLI tool (Claude, Copilot, etc.) in an interactive PTY session exposed via a web UI. Supports text/voice input and screenshot capture for vision-capable models.

nfltr ai [command] [args...] [flags]

Flags

Examples

# Run Claude CLI with web terminal UI (default)
nfltr ai claude

# Copilot with chat-style interface
nfltr ai copilot --mode chat --basic-auth admin:secret

# Custom AI tool with working directory
nfltr ai -- custom-ai-tool --verbose --cwd ~/project

UI modes

nfltr ssh-config — SSH Config Helper new

Generate and manage SSH Host blocks in ~/.ssh/config so you can ssh <agent-name> directly.

nfltr ssh-config <agent-name> [flags]

Flags

Examples

# Add SSH config for an agent
nfltr ssh-config my-server --user admin
# Then simply:
ssh my-server

# Preview without modifying
nfltr ssh-config my-server --print
# Output:
# Host my-server
#   ProxyCommand nfltr ssh-proxy --name %h --port %p
#   User admin

# Remove an agent's config
nfltr ssh-config my-server --remove

nfltr replay — HTTP Traffic Replay new

Replay HTTP requests captured by nfltr http --record against a local or remote server. Useful for reproducing bugs, load testing, or service migration verification.

nfltr replay <capture-file> [flags]

Flags

Examples

# Replay all captured traffic
nfltr replay nfltr-capture-20260325-120000.json

# Replay against a different server
nfltr replay capture.json --target http://localhost:3000

# Only POST requests, with response bodies
nfltr replay capture.json --method POST --verbose

# Filter by path with 100ms delay
nfltr replay capture.json --path /api/users --delay 100

# Preview without executing
nfltr replay capture.json --dry-run

nfltr update — Self-Update new

Update nfltr to the latest version. Detects OS/architecture automatically and performs an atomic binary replacement.

nfltr update [flags]

Flags

Examples

# Update to latest version
nfltr update

# Check for updates without installing
nfltr update --check
# → Current: vX.Y.Z, Latest: vX.Y.Z (update available)

nfltr completion — Shell Completions new

Generate shell completion scripts for bash or zsh.

nfltr completion <bash|zsh>

Examples

# Bash — add to ~/.bashrc
eval "$(nfltr completion bash)"

# Zsh — add to ~/.zshrc
eval "$(nfltr completion zsh)"

Authentication

nfltr supports multiple authentication methods, tried in order:

1. --api-key flag — highest priority
2. NFLTR_API_KEY environment variable
3. --key-name flag — look up a named key from config
4. Config file — active key in ~/.config/nfltr/nfltr.json
5. mTLS certificates — --tls-cert, --tls-key, --tls-ca

API Key Authentication

The server administrator creates API keys via the admin dashboard or admin API. Each key is bound to an agent identity.

# Save once (or save multiple keys with --name)
nfltr config add-api-key YOUR_KEY
nfltr config add-api-key FRIEND_KEY --name alice

# All subsequent commands use the active key automatically
nfltr http 8080
nfltr status

# Or use a specific named key per-command
nfltr http 8080 --key-name alice

mTLS Authentication

For zero-trust environments without API keys:

nfltr http 8080 \
  --tls-cert client.crt \
  --tls-key client.key \
  --tls-ca ca.crt \
  --server grpc.yourcompany.com:443

Agent identity is derived from the certificate Common Name (CN).

Features

Share URLs

Share URLs are enabled by default. Every nfltr http or nfltr command session automatically gets a temporary public URL with a memorable name (e.g., https://vivid-hawk.nfltr.xyz/). Share URLs:

• Are accessible without authentication
• Use word-pair subdomains for easy sharing
• Expire when the agent disconnects
• Are revoked automatically on disconnect

nfltr http 8080
# → Share URL: https://vivid-hawk.nfltr.xyz/

# Disable with --no-share:
nfltr http 8080 --no-share

Multi-Backend Routing

Route different URL paths to different local services:

nfltr http 8080 \
  --route /api=3000 \
  --route /ws=4000 \
  --route /admin=https://localhost:9443

Verbose Request Logging

With --verbose, every proxied request is logged:

[1] GET / → http://localhost:8080/ → 200 (4521 bytes, txn=abc123)
[2] GET /style.css → http://localhost:8080/style.css → 200 (1200 bytes, txn=def456)
[3] POST /api/login → http://localhost:3000/api/login → 200 (89 bytes, txn=ghi789)

Auto-Reconnect

nfltr automatically reconnects when the connection drops:

• Default: 12 retry attempts with 5-second intervals
• Configure: --retries 30 --retry-wait 10
• Total resilience window: retries × retry-wait seconds

Duration Limit

Auto-stop after a fixed duration (useful for demos):

nfltr http 8080 --duration 3600  # Stop after 1 hour

Health Endpoint

nfltr exposes a local HTTP health endpoint (default :29501) for integration with monitoring tools:

nfltr http 8080 --health-addr :9999
# Health check: http://localhost:9999/health

Environment Variables

Quick Command Map