Self-Host Agent Deck Web UI on Linux with Localtonet

How Agent Deck and Localtonet fit together

Agent Deck describes itself as a command center for AI coding agents. Instead of keeping unrelated terminal windows open for every project, you can use one terminal interface to see sessions that are running, waiting, or finished and move between them. Its current repository documents workflows for tools such as Claude Code, Gemini, OpenCode, and Codex, together with grouping, search, session forking, Git worktrees, skills, MCP attachment, and cost tracking.

The primary interface is a terminal UI launched with agent-deck. The project also documents agent-deck web, which starts a web UI at http://127.0.0.1:8420. The address 127.0.0.1 is the Linux host's loopback interface. A browser on the same machine can reach it, but another computer normally cannot connect to that address directly.

That local-only default supports a disciplined deployment process. First install Agent Deck and confirm that its terminal interface works. Next start the web process and verify the dashboard from the Linux host. Only after those checks pass should you introduce Localtonet as a separate network layer. This order prevents an application startup problem from being mistaken for a tunnel failure.

Localtonet does not install, configure, or authenticate Agent Deck. Our role begins after the local HTTP service responds successfully. The Localtonet client on the Linux host connects the local target to the public address assigned to an HTTP tunnel. That address is available only while the selected client is connected and the tunnel is running.

Linux prerequisites and deployment decisions

Agent Deck currently documents support for Linux, macOS, and Windows through WSL. This tutorial focuses on native Linux. Before installing it, choose the Linux user that will own and operate the sessions. Use a non-root account where practical so Agent Deck and its managed tools do not receive unnecessary access to the host.

The primary installation command requires curl, Bash, network access to GitHub, and permission to write to the location selected by the installer. The repository does not provide one universal package-manager command for every Linux distribution, so this guide does not invent an apt, dnf, pacman, or zypper sequence.

Check the commands needed by the primary installation path:

command -v curl
command -v bash

Each command should print an executable path. If one is missing, install it through your distribution's supported package-management process before continuing.

Prepare the AI tools you intend to manage

Agent Deck coordinates AI coding agent sessions, but installing Agent Deck does not install or authenticate every supported agent. Install the tools needed for your workflow using their own current documentation. Test each tool directly from the intended Linux user and project directory before adding it to Agent Deck.

Keep agent API keys, login tokens, environment files, cloud credentials, signing keys, and private repository information out of screenshots, shell history, shared task files, and support output. A dashboard that can interact with an authenticated coding agent should be treated as an administrative interface.

Prepare the Localtonet account and device

You need a Localtonet account and a device-specific auth token for the Linux host that will run the tunnel. The token identifies that client device and must not be guessed, published, embedded in an article, committed to a repository, or included in a screenshot.

Use the Linux client installation path presented by the current Localtonet HTTP tunnel documentation or your authenticated dashboard. Install and run the client on the same Linux machine as Agent Deck. We do not reproduce an unverified package URL or shell command here because Linux delivery details can change, and the supplied product evidence does not establish a single permanent command for every distribution.

Same-host placement matters because Agent Deck's documented endpoint uses loopback. A Localtonet client on another computer cannot normally reach 127.0.0.1 on the Agent Deck host. This guide does not change Agent Deck's bind address because the current repository evidence supplied for this revision does not establish a supported bind-address option.

Install Agent Deck on Linux

The current Agent Deck repository README documents four installation paths: the project installation script, Homebrew, Go, and a source checkout. Select one method. Combining methods can leave several binaries in different directories and make upgrades difficult to audit.

Option 1: Use the documented installation script

The repository currently presents this as its main installation command:

curl -fsSL https://raw.githubusercontent.com/asheshgoplani/agent-deck/main/install.sh | bash

Run it as the Linux user that will operate Agent Deck. When it finishes, open a new shell if instructed and verify that the executable can be found:

command -v agent-deck

A successful check prints an executable path. The repository evidence does not establish one destination for all Linux environments, so do not assume a particular directory without checking the installer's output.

Option 2: Install with Homebrew

If Homebrew is already part of your Linux package workflow, the current repository documents:

brew install asheshgoplani/tap/agent-deck

This command assumes that Homebrew is already installed and functioning. Verify the resulting command with:

command -v agent-deck

Option 3: Install with Go

With an existing Go toolchain, the repository documents:

go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@latest

Go places installed commands in its configured binary directory. That directory must be in your shell's PATH. Inspect your own Go configuration rather than assuming a fixed location.

For a reproducible deployment, replace @latest with a release you have reviewed. The following pinned example was revalidated against the Agent Deck release page during this article's 2026 revision:

go install github.com/asheshgoplani/agent-deck/cmd/agent-deck@v1.16.26

Version v1.16.26 is an example, not a recommendation that it remain current. Review the v1.16.26 release entry and the broader Agent Deck release history before selecting a version. Test upgrades against your session workflow rather than changing versions blindly.

Option 4: Install from source

The repository documents this source installation sequence:

git clone https://github.com/asheshgoplani/agent-deck.git
cd agent-deck
make install

This method requires Git, make, and the build toolchain expected by the checked-out revision. The supplied repository extract does not enumerate every build dependency or supported compiler version. Inspect the current repository documentation and build files before automating a source installation.

Before using Agent Deck with important repositories, review the project's security policy. That page is the appropriate place to check currently supported versions and the project's security-reporting process.

Configure the initial Agent Deck workflow

The documented quick-start path does not require a separate web-server configuration file. Begin with the terminal interface so you can confirm that the binary starts and that your chosen coding agent works before adding the web dashboard.

The current README lists shortcuts including Enter to attach, Ctrl+Q to detach, n for a new session, r to rename, R to restart, d to delete, and ? for full help. Use the help displayed by your installed version as the final authority because interactions can change between releases.

Start and verify the Agent Deck web UI locally

Start the dashboard from the same Linux account and environment used for the working Agent Deck installation:

agent-deck web

The currently documented endpoint is:

http://127.0.0.1:8420

Keep the launching terminal open during the test. From a browser on the same Linux machine, open the local address. A successful result should display the Agent Deck web interface rather than a connection error, an unrelated application, or a generic response from another process.

On a headless host, perform a basic HTTP request from another terminal on that same machine:

curl http://127.0.0.1:8420

A returned HTTP response shows that something is accepting requests at the target. It does not prove that every page asset and interactive feature works, so browser verification remains necessary where possible. Confirm that the displayed session state corresponds to the test session you created in the terminal interface.

Expected local results

• command -v agent-deck prints the selected executable path.
• agent-deck opens the terminal UI without an immediate fatal error.
• The selected coding agent works from the intended project and Linux account.
• agent-deck web remains running rather than returning immediately to the shell.
• A same-host request to http://127.0.0.1:8420 receives an HTTP response.
• The browser displays the expected Agent Deck interface and non-sensitive test session.

If the local URL fails, stop at this layer. A tunnel cannot repair a process that is not running or a service that does not respond at its configured target. Read the output from agent-deck web, verify that the request originates on the same Linux host, and check whether another process is already using port 8420.

The current repository evidence supplied for this revision establishes the default endpoint. It does not establish a supported alternate-port flag, bind-address flag, daemon mode, systemd unit, or automatic-start procedure. This guide therefore does not invent any of those options. Check the documentation and command help belonging to your installed release if its behavior differs.

Routine Agent Deck operations

Run documented session commands

A supported session can be forked with:

agent-deck session fork my-proj

A multiline task stored in a file can be sent with:

agent-deck session send my-proj --message-file task.md

A stopped or errored session can be removed from the registry while preserving its transcripts with:

agent-deck session remove my-proj

Replace my-proj and task.md with resources that exist in your environment. Review task files before sending them because they may instruct an authenticated agent to modify source code, invoke tools, or access project data.

Enable shell completion

For Bash, the current README documents:

echo 'source <(agent-deck completion bash)' >> ~/.bashrc

For Zsh:

echo 'source <(agent-deck completion zsh)' >> ~/.zshrc

For Fish:

agent-deck completion fish > ~/.config/fish/completions/agent-deck.fish

Open a new shell or reload the relevant configuration afterward. Inspect the file before appending anything and avoid adding duplicate completion lines.

Stop the dashboard

If agent-deck web is running in the foreground, return to that terminal and use the normal terminal interrupt. A request to 127.0.0.1:8420 should then fail. Stop the Localtonet tunnel as well so it does not remain active with a failed local target.

Uninstall Agent Deck

The documented interactive uninstall command is:

agent-deck uninstall

To remove the binary while retaining session data, the repository documents:

agent-deck uninstall --keep-data

Read the prompts carefully. If you installed Agent Deck with Homebrew or maintain a source checkout, also consider how that installation method manages packages or source files.

Configure a temporary Localtonet HTTP tunnel

Begin only after http://127.0.0.1:8420 works locally. Agent Deck provides an HTTP service, so use the Localtonet HTTP tunnel workflow documented in our HTTP tunnel documentation. This is standard HTTP tunneling, not VPN functionality.

For this test, use a clean Agent Deck environment with no private repositories, credentials, confidential prompts, production sessions, or sensitive transcripts. Keep the test attended, do not distribute the assigned URL, and stop the tunnel immediately after verification. A hard-to-guess URL is not authentication.

Verify the complete request path

First reload http://127.0.0.1:8420 on the Linux host. Next confirm that the Localtonet device is connected and the tunnel is running. Finally, use the assigned HTTPS address from the intended test browser. The remote page should display the same non-sensitive test session seen locally.

Test browser
  -> assigned Localtonet HTTPS address
  -> running HTTP tunnel
  -> connected Localtonet client on the Linux host
  -> http://127.0.0.1:8420
  -> Agent Deck web UI

If the public request fails while the local page continues to work, the application layer is healthy. Investigate the Localtonet client, selected device, local target, relay selection, and tunnel state. If the local page also fails, return to Agent Deck rather than changing tunnel fields.

Apply a controlled test boundary

An AI agent dashboard may expose project names, paths, prompts, outputs, transcripts, tool activity, repository context, and session controls. Depending on the configured agent, access could lead to source changes or command execution. Treat it as an administrative interface, not a passive status page.

HTTPS does not authenticate the operator

HTTPS protects data while it travels between a browser and the tunnel edge. Authentication establishes who is making the request. Authorization establishes what that identity may do. These are separate properties.

The Agent Deck evidence used for this revision does not establish built-in authentication or role-based authorization for agent-deck web. The supplied Localtonet evidence also does not establish an HTTP authentication feature that can be promised for this exact deployment. We therefore do not present direct public exposure as a secure permanent architecture.

Use a dedicated non-sensitive test context

Create a test project with no proprietary source code, secrets, customer information, production configuration, or privileged tooling. Use a Linux account whose filesystem and command permissions are limited to that test. This makes the tutorial's boundary operational rather than relying only on a warning.

Do not assume that an unshared or random-looking public URL is private. Public endpoints can be discovered, copied, logged, or exposed accidentally. URL secrecy is not an identity control.

Protect the device token

A Localtonet auth token identifies the client device that runs the tunnel. Obtain it from the authenticated product flow and keep it out of shell transcripts, screenshots, screen recordings, issue reports, and repositories. Redact account details, device tokens, public endpoints, project names, prompts, repository paths, and credentials from any screenshots used for documentation.

Limit process privileges

Run Agent Deck and its coding agents with only the filesystem, repository, and command permissions required for the test. Do not run the dashboard as root to work around an installation or path problem. Review environment variables and project directories before opening the tunnel.

End every test explicitly

Stop the Localtonet tunnel first, then stop agent-deck web if the browser interface is no longer needed. Confirm that the public address no longer delivers the dashboard and that 127.0.0.1:8420 stops responding after the local process exits. Delete obsolete tunnel configurations to avoid selecting the wrong device or target during a later test.

Troubleshooting by failure layer

agent-deck is not found

command -v agent-deck

If this prints nothing, the executable is not available through the current PATH. Review the output from the installation method you used. For Go installation, confirm that the configured Go binary directory is in PATH. Avoid installing a second copy until you know where the first method placed its binary.

The terminal UI works, but an agent session fails

Run the selected coding agent directly from the same Linux user and project directory. Confirm that it is installed, authenticated, and permitted to read or modify the intended files. This separates an agent-specific error from an Agent Deck interface problem. Never include API keys or login tokens in public diagnostic output.

agent-deck web exits immediately

Read the command's terminal output and verify that it is running under the user whose Agent Deck environment works. Check whether another process already occupies port 8420. The reviewed evidence does not establish an official alternative-port option, so do not guess at flags. Consult the command help and documentation matching your installed release.

The browser cannot open 127.0.0.1:8420

Confirm that agent-deck web is still running and that the request originates on the same Linux machine. On a phone or another laptop, 127.0.0.1 refers to that device, not the Agent Deck host.

curl http://127.0.0.1:8420

If this same-host request fails, resolve the Agent Deck process before changing any Localtonet configuration.

The local dashboard works, but the Localtonet device is disconnected

This is a client layer failure. Confirm that the Localtonet application is running on the Agent Deck host and is using the intended device token. Verify that the dashboard selection corresponds to that client. Do not copy the token into diagnostic output.

The device is connected, but the public URL fails

1. Retest http://127.0.0.1:8420 on the Linux host.
2. Confirm that the Localtonet client remains connected.
3. Confirm that the selected dashboard device is the same Linux host.
4. Confirm that the HTTP target is 127.0.0.1 and port 8420.
5. Confirm that the selected relay server is currently valid.
6. Confirm that the tunnel was started rather than only created.
7. Retest the public address currently assigned to that tunnel.

The public page shows unexpected content

Stop the tunnel immediately. Confirm what responds locally at 127.0.0.1:8420 and check whether another process has taken the port. Restart the tunnel only after the local browser clearly shows the expected Agent Deck test environment.

Access stopped after a reboot or terminal closure

Verify the Agent Deck process, Localtonet client, and tunnel independently. The web process may have ended, the client may be disconnected, or the tunnel may be stopped. The reviewed Agent Deck evidence does not document an official systemd unit, daemon flag, or automatic-start procedure, so this guide does not provide a guessed service definition.

The browser opens without a login page

That is not proof of a tunnel malfunction. It is a reason to enforce this tutorial's temporary test boundary. Do not continue with sensitive projects. Complete the non-sensitive connectivity check, stop the tunnel, and do not establish routine access until a verified authentication or private-access architecture is in place.

Frequently asked questions