Set Up AgentDeck with a Localtonet TCP Tunnel

Current decision: evaluate compatibility, do not assume a working setup

A complete AgentDeck remote-attach setup through an assigned Localtonet TCP endpoint is not established by the available primary documentation. Two independent questions remain unanswered: how the AgentDeck client selects the assigned public port, and whether the daemon endpoint has an appropriate authentication, authorization, and encryption model for public exposure.

This article therefore evaluates the integration rather than promising a completed setup. You can inspect a local installation, prepare our client, and understand the TCP configuration without publishing the daemon. Do not start a public tunnel to AgentDeck until both questions have documented answers for the versions you actually run.

The distinction matters because a Localtonet TCP endpoint contains two values: a public hostname and a public port. A client option that accepts only a hostname might use a fixed port. Substituting the public hostname into such an option would not necessarily send traffic to the endpoint assigned to your tunnel. A successful generic TCP probe cannot resolve that application-level mismatch.

The current AgentDeck project site advertises version 2.1 features. The older npm-v1.4.2 release is hundreds of commits behind the repository state supplied for this review. Its installation and port-handoff notes are useful historical evidence, but they cannot establish current behavior for every later release.

Separate AgentDeck behavior from the network path

AgentDeck's project describes dashboards and physical controls for coding-agent sessions. Its current site discusses integrations including Claude Code hooks, Codex lifecycle hooks, OpenClaw Gateway pairing, and Kiro CLI observation. These references establish the project's general purpose, not identical capabilities across integrations or a public remote-daemon contract.

The local application must work before remote networking is introduced. A dashboard that cannot observe a local session will not be repaired by TCP forwarding. Conversely, a working dashboard does not prove that another machine can address the daemon, authenticate to it, or use its protocol safely.

With Localtonet, standard TCP tunneling does not require inbound router port forwarding, a public IP address, or VPN setup. It still requires an allowed outbound connection and compliance with your network policies. The tunnel exists as a usable path only while the selected client device is connected and the tunnel is running.

Prefer running our client on the same host as the service when practical. A daemon listening on 127.0.0.1 can then remain locally bound while our client targets that address. This avoids unnecessarily widening its LAN listener, but it does not make the forwarded service private: starting a public tunnel deliberately creates a path to that local socket.

Establish a version-specific AgentDeck baseline

Before installing or updating AgentDeck, identify the intended release and installation channel. Do not mix a current project homepage, an older npm release, native-app instructions, and CLI instructions into one assumed configuration. Record the daemon version, remote client version, operating system, Node.js version if relevant, and agent integration you intend to test.

The repository contains a README, package manifest, changelog, and security policy file. These are appropriate primary files to inspect, preferably at the tag or commit matching your deployment. Their presence is not evidence that they document arbitrary remote ports or authorize public daemon exposure.

What the older release actually supports

The npm-v1.4.2 release publishes the following installer command and identifies packages for the CLI, daemon hub, hooks, and shared protocol types:

npx @agentdeck/setup

This is a historical command reference, not a pinned reproduction of v1.4.2. Running an unversioned npm package today can obtain a later package. Review the current installation instructions before executing it. The same release says the macOS App Store app runs standalone without this CLI installation; do not assume the native app and CLI have the same prerequisites or lifecycle.

Earlier instructions also presented agentdeck daemon install, agentdeck dashboard, and agentdeck diag agents. Current primary excerpts available here do not verify those commands or their exact behavior. Treat them as items to check in version-matched documentation, not a guaranteed installation sequence. For the same reason, this evaluation does not assert Node.js 22, 24, or 26, macOS 15+, Windows 11, or same-major interoperability as current requirements.

You can inventory an existing Node environment without changing it:

node --version
npm --version

These commands report the installed runtime and package manager. They do not prove AgentDeck supports those versions. A complete fresh AgentDeck installation tutorial would require current installation and startup evidence that is not available here; this guide deliberately stops short of inventing it.

Verify local observation and discover the actual listener

Start with a harmless local session

On an existing, supported installation, use the local startup and dashboard procedure documented for that release. Start a supported coding agent in a disposable project and generate a non-sensitive interaction. Confirm that the expected session appears, that displayed activity corresponds to your test, and that the session finishes or becomes idle as expected.

If observation fails, investigate installation context, integration configuration, permissions, and version support first. Avoid switching casually between root, administrator, and ordinary user accounts: configuration and background processes can belong to different accounts. Use only diagnostics confirmed by the installed CLI's documentation.

List listening sockets and identify their owners

Inspect all TCP listeners rather than filtering only for a remembered port. On Linux, use:

ss -ltnp

On macOS, or another system with lsof installed:

lsof -nP -iTCP -sTCP:LISTEN

In Windows PowerShell:

Get-NetTCPConnection -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

Match the listener to the intended daemon process. Elevated privileges may be necessary to see process ownership. On Windows, inspect the reported PID with Get-Process -Id followed by that numeric PID. Do not assume a process is AgentDeck solely because it owns a familiar port.

Record the address family as well as the address and port. An IPv4 loopback listener at 127.0.0.1 and an IPv6 loopback listener at ::1 are not interchangeable in every configuration. A wildcard bind such as 0.0.0.0 is not the destination address you should copy into a tunnel; select a reachable address appropriate to the client device.

If our client runs on another machine, 127.0.0.1 refers to that other machine, not the AgentDeck host. You would need a reachable private address and a supported daemon bind policy. Do not widen the daemon's binding or change firewall rules simply to make a probe succeed without first reviewing the security consequences.

Keep the 9121 handoff note version-specific

The npm-v1.4.2 release notes describe a macOS handoff limitation: starting the CLI immediately after quitting the native app could select port 9121 if 9120 remained unavailable after a 20-second wait. For that release, the notes say agentdeck daemon restart targets 9120 again once it is released.

That is not a current universal troubleshooting rule. Do not assume every missing listener on 9120 means a 9121 fallback, and do not apply the restart command without checking your version. Discover the actual listener and review the applicable release information. An update or restart can invalidate a previously recorded target.

Resolve endpoint compatibility and security before exposure

The public-port question

The earlier article showed this host-only example:

agentdeck claude --remote-daemon --daemon-host mainnode.lan

This is an example under review, not a verified command for current releases. It does not establish how to supply an arbitrary public TCP port. No current evidence here confirms a --daemon-port flag, a host:port value, an environment variable, or another supported override.

Before proceeding, obtain a version-specific command that selects both values in the assigned Localtonet endpoint. Ordinary DNS hostname resolution does not rewrite a destination port. Likewise, a public endpoint forwarding to a local port such as 9120 does not mean the public port is also 9120.

Do not request or assume a fixed public-port capability that has not been confirmed for your account. Check the actual endpoint shown by our dashboard and the capabilities available to you. If the application cannot address that endpoint, the compatibility decision is no-go even when generic TCP forwarding works.

The daemon trust question

AgentDeck's project site describes local data storage, optional integrations, local pairing state, and credentials used for specific features. These privacy statements do not establish authentication or encryption for the remote-daemon endpoint. A security policy file may describe vulnerability reporting rather than the deployment trust model. Read it, but do not infer protections that it does not specify.

A defensible review should answer the following:

• What authenticates the remote client before it can read session data or send control messages?
• What separates read-only observation from actions such as input, interruption, or steering?
• What protects traffic across every network segment, and how are peers verified?
• How are credentials or pairing relationships revoked?
• What information or controls are available before authentication?
• What bind addresses and network deployment patterns are explicitly supported?

These are requirements to investigate, not claims about capabilities AgentDeck already has. Test access denial and revocation as well as successful access once a documented model exists.

If the endpoint's trust model remains unclear, keep it local. An authenticated private access design may be an alternative, but it still needs a supported application connection pattern and a review of who can reach the daemon. We offer VPN Manager for private mesh networking; standard TCP tunneling is not itself a VPN. SSH forwarding is another general networking pattern, but a current AgentDeck-specific SSH workflow is not established by the supplied primary excerpts.

Install and verify the Localtonet client without publishing AgentDeck

You can prepare our client independently of the unresolved AgentDeck questions. Use the download choices in our Getting Started documentation. Select the operating system and CPU architecture of the device that will reach the local service, not those of the remote worker.

The documented downloads include Windows 32-bit, 64-bit, and ARM variants; Linux x64, ARM, ARM64, and MUSL variants; and macOS Intel and ARM64 variants. Docker and Android paths are also listed. Availability of a client package does not establish AgentDeck compatibility on the same platform.

The complete service installation below is limited to the documented Linux DEB and RPM path. Current Windows and macOS package-specific installation and startup procedures are not included in the available evidence, so this article does not invent executable names, startup flags, or service registration commands for them. Use the instructions associated with the selected official package, launch the client, authenticate the intended device, and verify its dashboard connection before continuing.

Linux package prerequisites

The DEB and RPM packages support x64 and ARM64 and require systemd 247 or newer and OpenSSL 3. Documented examples include Debian 12, Ubuntu 22.04+, and RHEL 9. Check your environment before choosing this path:

uname -m
systemctl --version
openssl version

Download the matching package from our documentation. The commands below assume you are in its download directory. Run only the installation command that matches your distribution and architecture.

# Debian / Ubuntu x64
sudo apt install ./localtonet-linux-x64.deb

# Debian / Ubuntu ARM64
sudo apt install ./localtonet-linux-arm64.deb

# Fedora / RHEL x64
sudo dnf install ./localtonet-linux-x64.rpm

# Fedora / RHEL ARM64
sudo dnf install ./localtonet-linux-arm64.rpm

sudo chmod 600 /etc/localtonet/auth-token
sudo localtonet --headless --authtoken-file /etc/localtonet/auth-token --check-config

sudo systemctl enable --now localtonet.service
sudo journalctl -u localtonet.service

Confirm both the local process state and the account-side device connection. On Linux, systemctl status localtonet.service checks the service, while the dashboard shows whether the intended device is connected. An active process alone does not prove successful authentication or relay connectivity.

Protect the token as a credential. Do not put it in shell command examples, screenshots, repositories, chat messages, or public diagnostic bundles. Review logs before sharing them. If configuration validation fails, correct the token file or package environment before repeatedly restarting the service.

Conditional TCP configuration after approval

The workflow below applies only after the two gates pass, or to a separately approved disposable TCP service used to evaluate transport. Do not use a generic probe as justification for exposing an unreviewed AgentDeck daemon.

Our documented general tunnel lifecycle is shown here. The available evidence names TCP in the Localtonet documentation's Supported Tunnels navigation, but does not supply a verified TCP detail-page URL or its exact screen sequence. Select TCP there for the current dedicated workflow; we do not invent a deep link or additional dashboard fields.

Do not confuse the local destination port with the public listening port. Record them separately with the target address, device identity, test time, and approval scope. Avoid storing credentials in that record.

Test local behavior, sockets, transport, and application behavior separately

Probe the exact public endpoint

Only after approval, test from the remote machine. With Netcat installed:

nc -vz YOUR_PUBLIC_HOST YOUR_PUBLIC_PORT

In Windows PowerShell:

Test-NetConnection -ComputerName YOUR_PUBLIC_HOST -Port YOUR_PUBLIC_PORT

Replace both placeholders with the values displayed for the running tunnel. A successful result establishes that the probe connected to the public endpoint. It does not by itself identify the destination process, prove useful data passed to the daemon, or show that an application handshake succeeded.

Correlate the probe with local service observations where available. If it fails, inspect endpoint spelling, tunnel state, device connectivity, target address, target port, and listener ownership in that order. Avoid changing several settings at once because that destroys the value of a staged test.

Do not fabricate the application test

This evaluation intentionally provides no public AgentDeck attach command. The available evidence does not establish one that accepts the assigned public port. A host-only example with the public hostname substituted would reproduce the original compatibility gap.

Once a supported command and security model are verified, test a disposable session. Confirm that it appears on the intended daemon, that expected state changes occur, and that unauthorized clients cannot obtain data or controls. Record the actual daemon/client versions and endpoint used. If TCP works but attach fails, investigate application endpoint selection, protocol compatibility, and authentication before rebuilding the tunnel.

Finally, stop the tunnel and repeat a new TCP probe. Confirm the public path is unavailable. Separately terminate the test session and check its application state; network shutdown is not a substitute for application cleanup.

Operate and troubleshoot each layer independently

Maintain a small operational record

Keep a non-secret record of the daemon version, client version, approved access method, actual listener, tunnel target, and last successful test. Include the source of the remote-port syntax and security decision when those become available. This prevents an old release note from silently becoming a permanent production assumption.

Handle restarts and upgrades conservatively

After an AgentDeck update, reverify local observation and listener ownership before reopening remote access. Recheck any compatibility policy against the release involved. Do not assume a same-major guarantee or a fixed daemon port without current evidence.

For the documented Linux Localtonet packages, install the new package and restart the ordinary service:

sudo systemctl restart localtonet

The package workflow preserves configuration. Verify the service journal, dashboard connection, and tunnel state after the restart. Do not assume service startup proves an application-level recovery.

If the dashboard does not see local sessions

Keep the tunnel stopped. Verify the selected AgentDeck integration, user account, local permissions, and version-specific setup. Use the diagnostics actually supported by the installed release. Network forwarding cannot install missing hooks or fix unsupported integrations.

If the public probe fails

Confirm the endpoint and running state first. Then verify our client is connected and can reach the configured local target. A loopback target on the wrong client device is a common addressing mistake. A stale port after a daemon restart is another. Inspect current listeners rather than assuming the historical 9120 or 9121 behavior.

If TCP works but AgentDeck does not

Verify that the application attempted the same host and port as the probe. Then check protocol expectations, component compatibility, and documented authentication requirements. Stop if supported endpoint syntax is still unknown. Repeatedly recreating a healthy TCP tunnel cannot add a missing client port option.

If the host sleeps or changes networks

The public path depends on the client's outbound relay connection. Restore the host's network, verify device connectivity, inspect the tunnel state, and confirm the local listener before retesting. Keep this dependency in mind when choosing a workstation for anything that needs predictable availability.

Revoke access deliberately

Stop or delete the tunnel when the approved session ends. Stopping it removes the public forwarding path but does not necessarily stop AgentDeck, its local dashboard, or the coding agent. If you need to stop the Linux client itself, the service command is:

sudo systemctl stop localtonet.service

This can affect other tunnels associated with that device. Prefer stopping the individual tunnel when only one service needs to be taken offline. If a token or application credential may have been exposed, stop access immediately and follow the relevant account recovery or credential replacement process rather than assuming a stopped tunnel invalidates credentials.

Frequently asked questions