Install AgentDeck and Set Up Remote Access with Localtonet

How the AgentDeck and Localtonet architecture fits together

AgentDeck is a local monitoring and control environment for AI coding agents. Its dashboards can show sessions, current activity, timelines, supported usage information, and requests that need attention. AgentDeck supports several surfaces, including terminal dashboards, native applications, mobile companions, Stream Deck integrations, and hardware displays. This tutorial focuses specifically on the Node.js CLI daemon because that is the documented path for terminal use, Windows, Linux, and external integrations.

In the normal daemon-first workflow, AgentDeck runs on the computer where your coding agents operate. Supported integrations report lifecycle activity to the daemon, and a local dashboard or paired surface presents that state. AgentDeck recommends running ordinary local sessions through this observation model rather than launching every session through an AgentDeck-managed command.

Remote attach is different. Commands such as agentdeck claude, agentdeck codex, agentdeck opencode, and agentdeck monitor remain available for compatibility. AgentDeck explicitly describes managed remote attach as a legacy feature that remains functional while replacement workflows are validated. It has no announced removal date, but it should not be confused with the preferred local daemon-first workflow.

With Localtonet, the machine running the AgentDeck daemon also runs our client. The Localtonet client establishes an outbound connection to one of our relay servers. A TCP tunnel then maps an assigned public host and port to the verified AgentDeck TCP listener on the local machine. This does not require inbound router port forwarding, a public IP address, firewall rule changes for an inbound internet listener, or VPN setup.

Prerequisites and supported installation path

The CLI installation path documented by AgentDeck requires Node.js 22, 24, or 26. It supports macOS 15 or newer, Windows 11, and Linux. You also need at least one supported coding agent if you want to verify live session observation. The documented integrations include Claude Code, Codex CLI, OpenCode, Kiro CLI or IDE, Antigravity, and an experimental OpenClaw Gateway integration, but their observation methods and limitations differ.

Claude Code is presented as the primary supported integration and uses lifecycle hooks. Codex CLI uses lifecycle hooks and rollout logs. OpenCode uses an observer plugin and native events. Kiro relies on transcript observation and may report delayed, idle-only activity. AgentDeck also notes that Kiro has no managed launcher. This matters when selecting a test case: a delayed or passive integration can make a correct daemon installation appear inactive if you expect immediate lifecycle updates.

Confirm Node.js before installation

Open a terminal or PowerShell window and print the installed Node.js version:

node --version

The major version should be 22, 24, or 26. If the command is unavailable or reports another major version, install a supported Node.js release using the method appropriate for your operating system before continuing. This guide does not prescribe a package manager because Node.js installation mechanisms and repository availability differ across operating systems.

Choose the correct AgentDeck path

The Node.js path is not required for every AgentDeck installation. The macOS App Store application includes its own daemon and can run without Node.js. However, the setup in this guide intentionally uses the CLI daemon because the documented legacy remote-attach workflow and port 9120 endpoint apply to that path. Do not install both approaches solely for this tutorial unless you understand how their daemon handoff behaves.

Prepare the Localtonet device

Install and run the Localtonet client on the AgentDeck host whenever possible. Keeping the tunnel client and daemon on the same computer simplifies the local target and avoids adding another LAN dependency. If our client runs on a different device, that device must be able to reach the AgentDeck host over the local network, and you must confirm that AgentDeck is listening on a non-loopback address that is appropriate for LAN access. The supplied AgentDeck evidence does not establish that bind behavior, so do not assume a separate Localtonet device can reach it.

Install and start AgentDeck

The documented terminal workflow has a short installation sequence: run the setup package, install the daemon, start a supported agent normally, and open the dashboard in another terminal. Run the commands as the operating-system user who will operate the coding agents. Avoid unnecessary administrator or root execution because AgentDeck’s integrations and configuration need to correspond to the user’s actual agent environment.

npx @agentdeck/setup

agentdeck daemon install

claude
# or:
codex
# or:
opencode
# or:
kiro-cli

agentdeck dashboard

The dashboard is the most useful functional check because it tests more than process startup. A visible, updating session confirms that the daemon, the selected integration, and the dashboard can exchange the expected local state. If the dashboard opens but no session appears, investigate the agent integration before adding remote networking. A Localtonet tunnel cannot repair missing hooks, unsupported agent behavior, absent transcript permissions, or an inactive daemon.

Verify AgentDeck locally before exposing anything

Remote access should be the final layer, not the first diagnostic step. Establish three facts locally: the CLI works, the dashboard observes a real session, and the daemon is listening on the port you intend to forward. If any of these checks fail, keep the tunnel stopped while troubleshooting.

Run AgentDeck diagnostics

AgentDeck documents the following diagnostics command for installation or integration problems:

agentdeck diag agents

Review the result for the agent you intend to use. The exact diagnostic output can vary with the platform, installed integrations, and AgentDeck version, so this guide does not prescribe fabricated success text. The meaningful outcome is that the intended integration is detected and no reported issue prevents its lifecycle data from reaching the daemon.

Generate observable activity

Start a supported agent normally and perform a small, non-sensitive test task. Keep agentdeck dashboard open in another terminal. Confirm that a session appears and that its state changes as the agent works, waits, or finishes. Some surfaces can expose supported controls when a real control path exists, while other prompts are display-only. Do not treat the mere appearance of a session as proof that remote control is available.

Inspect the daemon listener on Linux

On a Linux system with the ss utility, inspect TCP listeners for the documented primary and fallback ports:

ss -ltn | grep -E ':(9120|9121)\b'

Inspect the daemon listener on macOS

On macOS, use lsof to check each relevant port:

lsof -nP -iTCP:9120 -sTCP:LISTEN
lsof -nP -iTCP:9121 -sTCP:LISTEN

Inspect the daemon listener on Windows

In PowerShell, query the two relevant local ports:

Get-NetTCPConnection -State Listen |
  Where-Object { $_.LocalPort -in 9120, 9121 } |
  Select-Object LocalAddress, LocalPort, OwningProcess

Record both the active port and the local address. An address such as 127.0.0.1 indicates loopback-only access. A wildcard or LAN address has different exposure implications. The command output tells you what the operating system reports, but it does not prove that AgentDeck authorizes remote clients or encrypts application traffic.

If neither port is listening, return to the daemon installation and diagnostics checks. If port 9121 is active because of the known handoff condition, do not create a long-lived tunnel that silently targets the fallback unless you deliberately intend to use it. Restarting the daemon after port 9120 becomes available can restore the documented primary endpoint:

agentdeck daemon restart

Re-run the operating-system listener check after the restart. Never infer success solely from the absence of an error message.

Understand AgentDeck’s legacy remote-attach constraints

AgentDeck documents the following worker-side pattern for attaching a managed Claude session to a daemon on another machine:

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

In this example, mainnode.lan is a hostname for the daemon host on a network where the machines can reach each other. The command demonstrates a host option, but the supplied documentation does not establish a separate command-line option for a custom daemon port. It also does not establish whether a host:port value is accepted by --daemon-host. We therefore must not invent either syntax.

This creates an important compatibility condition for a direct Localtonet connection. A Localtonet TCP tunnel supplies a public host and port. AgentDeck’s documented remote command must be able to connect to that exact combination. If the AgentDeck client always assumes port 9120 and our assigned public port is different, replacing only mainnode.lan with the public host will not be sufficient.

AgentDeck also demonstrates forwarding port 9120 through SSH in its remote-attach material. That establishes the general principle of carrying the daemon connection through a transport, but it does not establish an undocumented AgentDeck port flag or guarantee that every public endpoint layout is compatible. Localtonet can provide the TCP transport, while AgentDeck still determines how the worker selects its destination port and authenticates to the daemon.

Configure a Localtonet TCP tunnel

Proceed only after AgentDeck works locally and you have recorded the daemon’s active address and port. A raw TCP tunnel is the relevant Localtonet tunnel family because the AgentDeck endpoint is a TCP service rather than a browser-based HTTP application. Do not configure an HTTP tunnel merely because AgentDeck has dashboard interfaces, and do not describe this setup as a VPN. Localtonet VPN Manager is a separate private mesh VPN feature.

Our standard workflow is to install and run the client, select the device by its authentication token, select an available relay server, create the appropriate tunnel, start it, and then use the assigned public endpoint. Available servers, regions, options, and plan-specific capabilities must be taken from the current dashboard rather than hardcoded into a tutorial.

The safest local target is the narrowest one that actually works. If AgentDeck listens on 127.0.0.1:9120 and our client runs on the same machine, target that loopback endpoint rather than unnecessarily opening the daemon to the entire LAN. If the Localtonet client runs on a separate device, a loopback listener on the AgentDeck host will not be reachable from that device. Do not change the daemon’s bind address unless AgentDeck officially supports that configuration and you understand the LAN exposure it creates.

Test the public endpoint and attempt remote attach

Test in layers. First confirm raw TCP reachability from the remote network. Then evaluate whether AgentDeck can use that endpoint. This separation makes it clear whether a failure belongs to the tunnel, the daemon, or AgentDeck’s remote-attach addressing.

Test TCP reachability from Windows

In PowerShell on the remote computer, replace the placeholders with the exact public host and port shown in your Localtonet dashboard:

Test-NetConnection -ComputerName PUBLIC_HOST -Port PUBLIC_PORT

A successful TCP test means a connection can be established to that public host and port. It does not prove AgentDeck protocol compatibility, authentication, encryption, or full remote-session behavior.

Test TCP reachability from macOS or Linux

If your system has Netcat installed, use:

nc -vz PUBLIC_HOST PUBLIC_PORT

Keep the public endpoint private. Placeholders are used here deliberately because a real assigned endpoint should not be included in a public tutorial, repository, or support transcript.

Confirm endpoint compatibility before using AgentDeck

Compare the Localtonet public port with the port expected by the AgentDeck remote worker. The supplied AgentDeck material documents the daemon on port 9120 and shows only a daemon hostname argument. If your current AgentDeck version expects 9120 and the tunnel’s public endpoint is also reachable on that expected port, you can substitute the assigned public hostname for the documented LAN hostname:

agentdeck claude --remote-daemon --daemon-host PUBLIC_HOST

This command is appropriate only when all of the following are true:

• The public host resolves from the remote worker.
• The public port matches the port AgentDeck actually attempts to use.
• The tunnel targets the verified local AgentDeck listener.
• You have confirmed that the current AgentDeck remote-attach security model is acceptable for this exposure.
• The remote worker has a compatible AgentDeck CLI and Claude environment.

The same reasoning applies to other managed commands that AgentDeck says remain functional, but this guide does not invent their remote arguments. If the assigned public port does not match AgentDeck’s expected destination, stop at the connectivity test and verify current AgentDeck support for custom ports. Do not append the port to the host or add an undocumented option based on guesswork.

Verify behavior at the dashboard

Keep agentdeck dashboard open on the daemon host during the test. A successful result should be evaluated through actual AgentDeck behavior: the managed session should appear, lifecycle changes should be visible, and the session should correspond to the intended remote worker. A raw TCP success result alone is not enough.

Test with a disposable, non-sensitive task before using the connection for real work. If the remote command hangs, fails, or creates no visible session, stop the tunnel while investigating. This reduces unnecessary exposure and prevents networking retries from obscuring the original application error.

Security boundaries for remote AI-agent access

An AI-agent monitoring endpoint can expose operational details about projects, tools, session state, prompts, or controls, depending on the connected integration and surface. Remote control can carry greater risk than read-only observation. Treat the daemon endpoint as sensitive even if your test dashboard contains no confidential project content.

Localtonet removes the need to configure inbound router port forwarding for this workflow because our client creates an outbound connection to the relay. That networking convenience does not replace application-level authorization. It also does not establish that AgentDeck’s protocol is encrypted. Those are separate controls and must be evaluated independently.

Do not expose unrelated services through the same assumption set. A TCP tunnel forwards to the local address and port you specify. Confirm that port ownership still belongs to the intended AgentDeck process whenever you restart applications, switch between the macOS application and CLI, or encounter the 9121 fallback. Forwarding a reused port could expose a different local service.

Routine operation and troubleshooting

A practical startup sequence

For later sessions, begin with the local application and add remote access only after it passes verification:

1. Start or confirm the AgentDeck daemon.
2. Run agentdeck diag agents if the selected integration is uncertain.
3. Start the supported agent normally and confirm it appears in agentdeck dashboard.
4. Inspect the listener and confirm whether the active port is 9120 or, under the documented macOS handoff condition, 9121.
5. Start the Localtonet client on the selected device.
6. Confirm that the TCP tunnel’s local target still matches the verified listener.
7. Start the tunnel and test its public host and port from the remote network.
8. Attempt AgentDeck remote attach only if the public endpoint is compatible with AgentDeck’s documented destination behavior.

The AgentDeck command is not found

Confirm that the setup command completed under the current user and that you opened a fresh terminal if your environment requires it to recognize newly installed executables. Verify that Node.js reports a supported major version, then rerun:

npx @agentdeck/setup

Do not use an arbitrary global-install command as a substitute unless AgentDeck’s current documentation explicitly directs you to do so.

The dashboard opens but no session appears

Keep networking out of the diagnosis initially. Run:

agentdeck diag agents

Confirm that you launched a documented supported agent and generated actual activity. Remember that integrations differ. Claude Code uses lifecycle hooks and is the primary supported integration. Kiro transcript observation can be delayed and idle-only. On sandboxed Apple environments, Kiro transcript access requires a one-time folder grant. A missing local session cannot be fixed by forwarding the daemon port.

Nothing is listening on port 9120

Confirm that the daemon installation completed and inspect port 9121 as well if you are on macOS and recently quit the native application. Once 9120 becomes free, restart the daemon:

agentdeck daemon restart

Then repeat the listener inspection. If neither port is present, use AgentDeck diagnostics and resolve the daemon issue before starting the tunnel.

The tunnel starts, but the public TCP test fails

Check the layers in order:

• Confirm that the selected Localtonet client device is connected.
• Confirm that the tunnel is running, not merely created.
• Confirm that the configured local address and port match the active AgentDeck listener.
• If our client is on another machine, verify that it can reach the daemon host over the LAN.
• Confirm that the public test uses the exact assigned host and port.
• Confirm that local endpoint protection or operating-system policy is not blocking the Localtonet client’s connection to the target.

Do not change several layers at once. First prove local daemon access from the Localtonet client device, then prove the public TCP endpoint, and only then test AgentDeck remote attach.

The TCP test succeeds, but AgentDeck cannot attach

This usually indicates that basic relay reachability works while the application layer does not. Compare the assigned public port with the port AgentDeck attempts to use. Check CLI compatibility on both machines and confirm that you are using the documented managed remote command. Also verify the daemon’s current authentication or pairing expectations from current AgentDeck behavior.

Do not conclude that --daemon-host accepts a port simply because another command-line tool accepts host:port. The supplied evidence does not establish that format. If the tunnel endpoint cannot match AgentDeck’s expected port, stop the tunnel and use a currently documented compatible design rather than improvising.

The daemon unexpectedly moves to port 9121

On macOS, this can occur when the CLI starts immediately after the native application quits and port 9120 remains unavailable through AgentDeck’s existing 20-second wait. Wait for 9120 to be released, run agentdeck daemon restart, and verify the listener again. Update the Localtonet target only after deciding which daemon instance and port should remain authoritative.

The connection worked and then disappeared

Check whether the AgentDeck daemon is still running, whether the Localtonet client remains connected, and whether the TCP tunnel is still started. The public endpoint depends on all three. A sleeping host, disconnected client, stopped tunnel, or daemon restart can interrupt the connection.

Ending the remote session safely

Close the managed remote session using the application’s normal behavior, then stop the Localtonet tunnel. If this was a temporary configuration, delete the tunnel. Recheck the dashboard for unexpected sessions and retain no public endpoint information in shared notes. Stopping the tunnel removes public reachability through that tunnel even if the local AgentDeck daemon continues serving local dashboards.

Frequently asked questions