Installing the Nodetonet agent on Windows, macOS and Linux

The Nodetonet desktop agent is a small, single-binary daemon that turns any Windows, macOS or Linux machine into a proxy back-end. Once it is running and paired with a token, the device appears in your dashboard as a green ONLINE device and you can start routing mobile proxy, rotating proxy or HTTP tunnel traffic through it within seconds.

This guide walks through every platform step-by-step, including the platform-specific friction you will hit on first run. For the Android agent (phones and tablets), see Your first token and Android pairing. Token creation is the same on every platform and is explained at the end of that post.

Before you begin: create a token

Every agent instance is tied to a proxy token. Tokens are how the panel identifies a device, selects it for traffic and tracks its health. If you have not created one yet, open /tokens in the panel, click New token, give it a label, and copy the value — you will paste it into the agent on first launch. One token = one agent process; you can run as many agents as you like on separate machines, each with its own token.

If you want that agent to be part of a round-robin rotating proxy pool, create a token group and add the token to it after setup. For sticky sessions — where a caller appends -session-XXXX to the proxy username — no extra configuration is needed on the agent side.

1. Windows

Installation on Windows is the simplest of the three paths. From the /download page, choose the Windows tab and download nodetonet-agent-windows-x64.exe. The binary is code-signed, so Windows Defender SmartScreen should allow it to run without a warning.

1. Double-click the .exe. A small console window opens.
2. On first launch the agent prompts: "Paste your token:". Copy your token from /tokens and right-click inside the console window to paste it.
3. The agent saves the token to %APPDATA%Nodetonetconfig.json and reconnects automatically on every subsequent launch — you will never be asked for the token again on that machine.

Running on Windows startup (no third-party tools)

Open the Run dialog with Win+R, type shell:startup and press Enter. Drop a shortcut to the .exe file into the folder that opens — Windows will launch the agent for you whenever the user logs in. If you need service-like behaviour (restarts on failure, runs without a logged-in user), use a Scheduled Task with a "Run whether user is logged on or not" setting and the "Restart on failure" action tab.

2. macOS

macOS adds a layer of friction because Gatekeeper blocks unsigned third-party binaries by default. From the download page choose the macOS tab and grab nodetonet-agent-macos-x64. The same binary runs on Apple Silicon under Rosetta 2; a native arm64 build is planned.

1. Open Terminal and make the file executable: chmod +x ~/Downloads/nodetonet-agent-macos-x64
2. Try to launch it: ~/Downloads/nodetonet-agent-macos-x64. macOS will refuse with "cannot be opened because the developer cannot be verified."
3. In Finder, locate the binary, right-click it and choose Open. A dialog appears with an Open button — click it. This whitelists the binary in Gatekeeper's database; subsequent launches require no extra step.
4. Paste your token at the prompt. Configuration is saved to ~/Library/Application Support/Nodetonet/config.json.

Faster Gatekeeper bypass: run xattr -d com.apple.quarantine ~/Downloads/nodetonet-agent-macos-x64 once in Terminal before launching. The quarantine extended attribute is the only thing triggering the warning; removing it lets the binary open normally with no dialog.

Running on macOS login

The recommended approach is a launchd plist. Create ~/Library/LaunchAgents/com.nodetonet.agent.plist with a ProgramArguments key pointing to the binary and RunAtLoad set to true, then run launchctl load ~/Library/LaunchAgents/com.nodetonet.agent.plist. The agent will start automatically on every login and restart if it exits.

3. Linux

Linux is the most flexible platform. Download nodetonet-agent-linux-x64 from the download page. The binary is statically linked — no glibc version dance, no missing shared libraries, no Docker wrapper required. It runs on Ubuntu 20.04, Debian, CentOS, Alpine and virtually anything with a 64-bit kernel.

curl -L https://nodetonet.com/agent/nodetonet-agent-linux-x64 -o /usr/local/bin/nodetonet-agent
chmod +x /usr/local/bin/nodetonet-agent
nodetonet-agent --token YOUR_TOKEN_HERE

The agent runs in the foreground and logs to stdout. Press Ctrl+C to stop. After the first --token invocation the config is persisted to ~/.config/nodetonet/config.json, so subsequent runs need no flag.

4. Running as a systemd service (Linux)

For headless or unattended servers, running the agent as a proper systemd unit is strongly recommended — it starts at boot and restarts automatically on crash.

Create the service file at /etc/systemd/system/nodetonet-agent.service:

[Unit]
Description=Nodetonet agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/local/bin/nodetonet-agent
Restart=always
RestartSec=5
User=nodetonet
Group=nodetonet
MemoryMax=256M
TasksMax=128

[Install]
WantedBy=multi-user.target

Then create a dedicated system user, write the token config under that user, and enable the service:

useradd --system --create-home --shell /usr/sbin/nologin nodetonet
sudo -u nodetonet nodetonet-agent --token YOUR_TOKEN_HERE
# Press Ctrl+C once the config file is written
systemctl daemon-reload
systemctl enable --now nodetonet-agent
systemctl status nodetonet-agent

The first invocation as the nodetonet user writes the token into that user's config directory; from that point on, systemd manages restarts automatically. Check logs with journalctl -u nodetonet-agent -f.

Platform comparison at a glance

5. Verifying the connection

Open /tokens in the panel after starting the agent. The row for your token should flip to ONLINE within a few seconds, with device metadata (OS, hostname) visible in the device column. You can also open our What is my IP tool and route a request through the newly paired token to confirm traffic is flowing and the exit IP matches the machine's connection.

If the token stays OFFLINE for more than 30 seconds:

• Check that outbound TCP on port 443 to vds.nodetonet.com is not blocked by a firewall or corporate proxy.
• Check the agent's stdout (or systemd journal on Linux) — it logs every reconnect attempt and the reason for any failure.
• Confirm the token value is correct; a single mistyped character will cause a persistent auth failure.

For a deeper look at what heartbeat timing, timeout logic and the ONLINE/OFFLINE state machine actually mean, read Device health — what ONLINE actually means.

What to do after installation

• How to use Nodetonet — end-to-end setup from first login to live proxy traffic.
• Token groups: creating device pools — add this agent to a round-robin pool for rotating proxy requests.
• PC agent on Windows in depth — service configuration, log files and performance tuning.
• Proxy clients and per-customer auth — issue separate credentials with quotas and thread limits to each end-user.
• SOCKS5 with authentication — configure SOCKS5 on the newly paired device.
• Create a free account if you have not done so yet.