Monitor local AI coding-agent activity from a live project map, then make the dashboard available when you are away from the development machine
agenttrail is a local, open-source observability dashboard for following coding-agent plans, file changes, tool activity, and progress inside a repository. This guide starts with the primary workflow: checking the prerequisites, launching agenttrail with npx, optionally initializing its richer project map, and verifying the dashboard locally. After the local installation works, we show how to expose its localhost service through an HTTP tunnel with Localtonet. Because the documented agenttrail material does not specify a fixed dashboard port, the setup uses the actual local URL printed by your running instance rather than guessing one.
📋 What's in this guide
What agenttrail is and what it monitors
agenttrail is designed to answer a practical question that comes up during long coding-agent runs: what is the agent doing right now, and does its observed work match its declared plan? Instead of presenting only a transcript, it turns repository activity into a live browser-based project map. The dashboard can show plans, components, dependencies, file changes, tool activity, current work, and completed or blocked tasks when the corresponding information is available.
This tutorial covers the agenttrail package documented by the sodiumsun/agenttrail project, described as an infinite canvas and local observability layer for AI coding agents. It should not be confused with the similarly named agent-trail/agent-trail project, which documents a draft interchange format and tooling ecosystem for portable coding-agent session records. The commands and behavior in this guide apply to the local browser dashboard invoked with npx agenttrail.
Similar names do not imply compatible commands or installation procedures. Confirm that the package you intend to run is agenttrail and that its documented purpose is the local live project map described here. This guide does not install or configure the separate Agent Trail interchange-format monorepo.
agenttrail compares two broad kinds of information. Declared information comes from the project plan and represents what an agent says it is working on. Observed information comes from local activity, including the files currently being changed. A mismatch between these signals can reveal that an agent has moved to an unexpected component, reopened previously completed work, or stopped making visible progress on the declared task.
127.0.0.1, and does not require an agenttrail account or cloud service.
A repository does not need a PLAN.md file for the basic dashboard to be useful. The live tree, activity state, and available run cards can work without a plan. The richer component map appears after an agent writes the plan structure. That distinction is useful during setup because it lets you verify the server and file watcher before opting into project initialization.
Prerequisites and preparation
You need a local development machine with the repository you want to observe, a terminal, a browser, and a working Node.js environment that provides npm and npx. The available project evidence does not establish a minimum supported Node.js or npm version for agenttrail, so this guide does not invent one. Use a maintained Node.js release compatible with the package, and review the current package output if installation reports a version requirement.
npx runs a command supplied by an npm package. If the requested package is already available in the local project, npm can use that installation. If it is not present, npm can place the package in its cache, add the executable to the command environment, and ask for confirmation before running it. This is why npx agenttrail can launch the dashboard without requiring a separate global installation.
| Requirement | Why it is needed | How to check it safely |
|---|---|---|
| Local repository | agenttrail watches the repository from which it is launched. | Open the intended project and confirm that you recognize its files before running any initialization command. |
| Node.js with npm and npx | npx resolves and executes the agenttrail package command. |
Confirm that node, npm, and npx are available in your terminal. No minimum version is asserted here because the evidence does not specify one. |
| Web browser | The monitoring board is a browser interface served from the local process. | Use a browser on the same machine for the initial localhost test. |
| Permission to inspect and initialize the repository | The optional initialization workflow creates or modifies repository-local planning, instruction, ignore, and hook files. | Review your repository status and make sure you are authorized to make those changes. |
| Localtonet client for remote access | The client establishes the outbound connection to our relay after the local dashboard works. | Install and run the Localtonet client only on a device that can reach the agenttrail localhost service. |
Check your Node.js tooling
Run the following commands to confirm that the executables exist. These commands report installed versions but do not install or modify anything:
node --version
npm --version
npx --versionIf one of these commands is unavailable, install a maintained Node.js distribution appropriate for your operating system before continuing. Because the agenttrail documentation excerpt does not provide an exact version floor or an official operating-system support matrix, any compatibility error reported by npm or Node.js should be treated as authoritative for the package version being resolved on your machine.
Choose the correct repository
Open a terminal in the repository you actually want to monitor. agenttrail uses that working directory as the project context, so launching it from a parent directory, home directory, or unrelated checkout can produce an unhelpful board or watch the wrong files. If your repository contains confidential code, plans, filenames, or agent activity, consider the sensitivity of that information before proceeding to remote access.
It is also sensible to inspect the repository's current change state before optional initialization. The exact command you use depends on the version-control system. For a Git repository, the standard status command is:
git status
A clean or understood working tree makes it easier to identify what agenttrail init changes. Do not discard unrelated changes simply to make the tree clean. Instead, record or commit work according to your team's normal process.
npx can fetch a package that is not already installed locally. Read the package name carefully, review any installation prompt, and make sure it is the package you intend to execute. Running a package gives its process the permissions of your user account within the surrounding operating-system controls.
Install and launch agenttrail with npx
The primary agenttrail setup is intentionally short. There is no documented global-install requirement, database migration, application build, account registration, or cloud-service configuration. Enter the target repository and run the package command. The browser should then open on the live board, while the local process watches repository activity.
Enter the repository you want to monitor
In your terminal, change into the repository's root directory. Replace the placeholder below with your real local path. Confirm that this directory contains the project files and any agent instruction files you expect to use.
Run agenttrail through npx
Execute npx agenttrail. If npm needs to fetch the package, review and respond to its package-execution prompt. Keep the terminal available so you can see startup information, including the actual local dashboard address reported by this run.
cd /path/to/your-repository
npx agenttrailThe path above is deliberately a placeholder. Repository paths differ by operating system and user, so replace it rather than copying it literally. If the command succeeds, agenttrail starts watching the repository and opens its browser board. Do not assume that a missing browser window means the process failed. First inspect the terminal for the local URL and any startup or browser-launch message.
The available agenttrail documentation confirms that the service binds to 127.0.0.1, but it does not state a fixed dashboard port. Use the complete URL displayed by agenttrail. Do not copy a port from another tutorial, another machine, or an unrelated application.
At this point, the base installation is complete. Running the command is enough to get the live file tree and activity-oriented view even when the repository does not yet contain an agenttrail plan. Keep this basic state in mind when diagnosing setup issues: a missing component map is not necessarily an installation failure.
Understanding what npx installed
In this workflow, “install with npx” does not mean that agenttrail must be installed globally. npm may use an existing local dependency or fetch the requested package into its cache and run the package executable from there. A future unqualified npx agenttrail invocation can therefore resolve according to npm's normal package rules at that time.
Teams that require deterministic dependency review should define and document their own approved package-version policy. The supplied project command does not include a version specifier, and the evidence does not identify a particular version that we can safely recommend pinning in this article. Do not invent a version number. If reproducibility is required, select a reviewed release and use npm's documented package-specifier behavior according to your organization's change-control process.
Optionally initialize the richer project map
The first launch can observe repository activity without a PLAN.md. Initialization is optional and has a different purpose: it adds the project conventions needed for the fuller component map and installs repository-local Claude Code hooks. Run it only after the basic board starts successfully and after you understand the files it can change.
The documented initialization command is:
npx agenttrail initRun initialization from the repository root
Execute npx agenttrail init in the same repository you launched earlier. Review the consent flow and resulting changes. Initialization creates a starter PLAN.md, appends the agenttrail convention to CLAUDE.md and AGENTS.md, adds .agenttrail/ to .gitignore, and installs additive local Claude Code hooks.
Copy and use the backfill prompt if you want an initial map
On the board, use the documented Copy backfill prompt action and paste the prompt into your coding agent. The agent can study the code, repository history, and planning material to produce the initial component map. Review the generated plan as project content rather than accepting it blindly.
Unlike the read-only running dashboard, agenttrail init intentionally creates or updates planning, instruction, ignore, and hook configuration files. Inspect the resulting diff before committing it. Hooks are documented as being wired only with consent, but you should still review repository-local automation under the same security policy as other development tooling.
The plan convention represents components with stable identifiers, connects file patterns to components, records dependencies and links, and distinguishes states such as working, done, or stuck. Agents maintain the Markdown plan as they work, so the board is not a separate project-management database. This design also means that map quality depends on the accuracy of the plan and the agent's updates.
Claude Code receives the richest documented integration because local hooks can relay run events to the daemon, including current task and tool information. OpenAI Codex, Cursor, and other agents that edit files still contribute observable filesystem activity. They can maintain the map through the repository's AGENTS.md convention, but the evidence does not claim identical run-card capabilities across all agents.
| Coding-agent category | Live activity | Documented integration detail |
|---|---|---|
| Claude Code | File watcher plus local hooks | Supports the richest documented view, including run cards and todos, and uses CLAUDE.md for the map convention. |
| OpenAI Codex | File watcher | Can be observed through file changes and can maintain the map through AGENTS.md; equivalent local-hook run cards are not documented. |
| Cursor or another file-editing agent | File watcher | Repository modifications remain observable, and the map convention can be provided through AGENTS.md. |
Verify the dashboard locally before remote access
Remote tunneling should be the second phase, not the first. A tunnel cannot correct an application that failed to start, and combining both layers too early makes troubleshooting harder. Verify the agenttrail process, local URL, browser board, repository selection, and live activity on the host machine before creating a Localtonet tunnel.
Confirm that the agenttrail process remains active
Check the terminal in which you ran npx agenttrail. It should not have exited with an error. Preserve the complete local URL shown there, including its scheme and port.
Open the exact local URL
Use the URL reported by agenttrail in a browser on the same machine. The documented bind address is 127.0.0.1. Do not substitute an assumed port.
Confirm that the correct repository appears
Inspect the board's project identity and file tree. If the files belong to another directory, stop and relaunch agenttrail from the intended repository root rather than exposing the wrong board.
Generate an observable local change
Use your normal development workflow or coding agent to make an authorized test change. Confirm that the dashboard reflects repository activity. Avoid changing production code solely for a test if a safe documentation or temporary development change is available.
Distinguish the base view from the plan-backed map
If file activity appears but a detailed component map does not, check whether the repository has been initialized and whether PLAN.md contains the map convention. A missing map in an uninitialized repository does not mean the watcher failed.
Successful local verification gives you the two values required for the network integration: the local target address and its actual port. For example, if agenttrail prints an address with 127.0.0.1 followed by a port, use those exact values when configuring the tunnel. This article intentionally does not show a made-up example port because copying it could direct the tunnel to the wrong process.
Routine agenttrail operations
During ordinary development, run agenttrail in the repository whose activity you want to inspect. The project documents one daemon per repository, with live boards available through a shared tab switcher. Adding another repository involves starting agenttrail in that repository, after which its tab can appear on the boards. When that repository's daemon is no longer running, it disappears from the shared view.
Relaunch known boards after a reboot
The documented command for relaunching every board you have previously run is:
npx agenttrail upRun it in an environment where your Node.js and npm tooling are available. Before relying on this command for remote monitoring, verify locally that the expected repositories return and that each board points to the intended code checkout.
Configure a repository board to start at login
agenttrail also documents:
npx agenttrail autostartThis makes a repository's board start at login and self-heal according to the project description. The supplied evidence does not document the platform-specific startup mechanism, supported operating-system list, generated service path, or an exact removal command. For that reason, this guide does not invent platform-specific service-management steps. Review the command's current output and any files it proposes to create before enabling persistent startup.
Stop and restart during maintenance
Keep in mind that the agenttrail board, the Localtonet client, and the Localtonet tunnel have separate lifecycles. The evidence provided for agenttrail does not specify a dedicated shutdown subcommand, so we do not claim one. Stop the running process using the process-control method appropriate to how you launched it, then verify that the local board is unavailable before considering maintenance complete.
A Localtonet tunnel remains usable only while its selected client or device is connected and the tunnel is running. If agenttrail stops while the tunnel remains active, the public endpoint cannot produce a healthy dashboard because its local target is absent. If the Localtonet tunnel stops while agenttrail remains active, the board should continue to work locally but will no longer be reachable through that public endpoint.
Expose the working agenttrail dashboard with Localtonet
agenttrail deliberately binds to 127.0.0.1, which limits direct access to the host machine. That is a sensible local default, but it prevents you from opening the board directly from another network. With Localtonet, our client on the development machine establishes an outbound connection to a relay server. This lets you expose the local service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
An HTTP tunnel is the appropriate Localtonet family for this browser dashboard workflow. The local target is the IP address and port reported by agenttrail. The resulting tunnel provides a public HTTPS address for browser access. Do not use a TCP or UDP tunnel merely because the dashboard has a port. When a local service is a browser application, the HTTP tunnel workflow is the natural fit.
A service reachable only through 127.0.0.1 is not automatically suitable for unrestricted public access. The board can reveal repository names, component structure, plans, filenames, coding-agent activity, tool calls, and work status. Before starting a tunnel, apply authentication and access controls available for your selected configuration, expose only what is necessary, and stop the tunnel when remote access is no longer required.
The available Localtonet context establishes the workflow below but does not provide a safe fixed list of dashboard field names for every current client or plan. It also does not establish that every region, domain option, or access-control capability is available in every subscription. Obtain the current relay-server choices and supported options from your dashboard rather than copying hardcoded values.
Install and run the Localtonet client on the agenttrail host
Use the development machine running agenttrail, or another device that can reach its local service. For a dashboard bound specifically to 127.0.0.1, running our client on the same host avoids assuming that the service accepts connections from other LAN devices.
Authenticate or select the device using its token
Select the device-specific authentication token associated with the client that will run the tunnel. Treat the token as a credential. Never paste it into repository files, screenshots, support messages, article examples, or public issue reports.
Select an available relay server or region
Choose from the values currently offered in your Localtonet dashboard. Do not hardcode a server code from another account or old guide because availability can vary by plan, region, client version, or deployment.
Create an HTTP tunnel for the verified local target
Use 127.0.0.1 as the local IP when our client runs on the same machine. Enter the exact port from the URL printed by agenttrail. Do not guess the port, and do not enter the public tunnel port as the local target.
Start the tunnel and obtain its public address
Creating a Localtonet tunnel does not start it automatically. Use the Start action, confirm that the selected client is connected, and then copy the public URL assigned to the running HTTP tunnel.
Test remotely, then stop or delete the tunnel when finished
Open the public URL from the intended remote browser and verify that it shows the same repository board as the local URL. When access is no longer needed, stop the tunnel. Delete it if you do not intend to reuse the configuration.
For the current dashboard workflow and exact fields, consult our Localtonet HTTP tunnel documentation while configuring the tunnel. The local target must still come from your agenttrail process because agenttrail's documented material does not specify a universal port.
| Value | Where it comes from | Common mistake to avoid |
|---|---|---|
| Local IP address | The documented agenttrail bind address is 127.0.0.1 when our client runs on the same host. |
Do not replace it with a router address or public IP without evidence that agenttrail is listening there. |
| Local port | The actual local URL printed by the running agenttrail process. | Do not assume a standard port or copy one from an unrelated dashboard. |
| Tunnel family | HTTP, because this workflow exposes the browser dashboard. | Do not select UDP or treat ordinary tunneling as VPN functionality. |
| Device token | Your Localtonet account and selected client device. | Do not guess, publish, or store the token in the monitored repository. |
| Relay server or region | The current choices in your dashboard. | Do not hardcode a server code from an old article or another account. |
| Public URL | Assigned after the HTTP tunnel is configured and started. | Do not confuse the public URL with the local target used by the tunnel. |
Verify the complete remote path
Test the public URL from a separate network when possible, such as a mobile connection, rather than relying only on the development host. Confirm that the expected board loads, that repository activity updates, and that your intended access controls behave correctly. A successful page load proves the basic path from the remote browser to the Localtonet relay, through the outbound client connection, and into the local agenttrail service.
Also test failure behavior. Stop the Localtonet tunnel and confirm that the public endpoint is no longer available. Restart it and verify access again. Separately, stop agenttrail while leaving the tunnel running and confirm that the dashboard no longer loads correctly. These tests help you identify which lifecycle needs attention during a real outage.
Security considerations for remote agent monitoring
Remote observability is useful precisely because it reveals operational detail. That detail can also be sensitive. A project map may disclose architecture, dependencies, filenames, task status, recent changes, agent identities, or decisions that have not yet been committed. Run the tunnel only for repositories and environments you are authorized to expose.
Use least exposure
Prefer an on-demand tunnel for short monitoring sessions. Start it when remote access is needed and stop it afterward. A persistent dashboard creates a longer exposure window and requires correspondingly stronger operational controls. Creating a tunnel configuration is not the same as starting it, so confirm its state rather than assuming it is offline.
Protect credentials and private endpoints
The Localtonet device token identifies the client device and must remain secret. Do not place it in PLAN.md, CLAUDE.md, AGENTS.md, shell history shared with others, screenshots, or source control. Likewise, avoid publishing a private dashboard URL in a public issue. A URL should not be treated as a substitute for authorization.
Review project-generated changes
The dashboard is documented as read only while it runs, but initialization is not read only. It changes repository-local instruction and planning files, adds an ignored agenttrail directory, and can install Claude Code hooks. Review those modifications before committing or sharing them. Ensure that generated planning material does not include secrets copied from local files, history, or internal documentation.
Do not confuse tunneling with a VPN
An HTTP tunnel exposes the selected local web service. It does not create general private network membership and should not be described as a VPN. Localtonet VPN Manager is our separate private mesh VPN feature. For this tutorial, the narrower HTTP tunnel is the relevant tool because the goal is to reach one browser dashboard.
Troubleshooting agenttrail and Localtonet
npx agenttrail is not recognized
Confirm that Node.js, npm, and npx are available in the current terminal. If Node.js was installed after the terminal opened, start a new terminal so its executable search path is refreshed. The evidence does not define a minimum supported Node.js version, so if npm reports an engine or compatibility requirement, follow the requirement shown for the package version being resolved.
npm asks permission to install the package
This can be normal when the requested package is not already available in the local project. npx can fetch it into npm's cache and prompt before execution. Verify the exact package name before approving. If organizational policy requires dependency review or a private registry, follow that policy rather than bypassing the prompt.
The browser did not open automatically
Inspect the terminal for the URL printed by agenttrail and open that exact address manually. A failed automatic browser launch does not necessarily mean the local server failed. If no URL is printed and the process exits, use the displayed error as the starting point rather than inventing a port and probing random addresses.
The board opens, but it shows the wrong repository
agenttrail watches the repository from which it is run. Check the terminal's working directory, stop that process using the process-control method appropriate to your launch environment, enter the intended repository root, and run npx agenttrail again. Do not expose the board remotely until its file tree matches the intended project.
The file tree works, but there is no component map
The base dashboard works without PLAN.md. A detailed component map depends on initialization and on an agent writing the plan convention. Run npx agenttrail init only after reviewing its documented file changes, then use the board's Copy backfill prompt workflow if you want the agent to produce an initial map.
Claude Code activity is less detailed than expected
Confirm that you consented to and reviewed the repository-local Claude Code hooks installed by initialization. The documented hook path is .claude/settings.local.json. A plain file watcher can still show repository changes, but the richer Claude Code run-card and todo view depends on local hook information.
The local board works, but the public URL does not
Check each layer in order:
- Confirm that agenttrail is still running.
- Open the exact local URL on the host again.
- Confirm that the Localtonet client associated with the selected token is connected.
- Verify that the HTTP tunnel targets
127.0.0.1and the exact agenttrail port. - Confirm that the tunnel was started, because creation alone does not make it run.
- Review the current tunnel status and any available diagnostic information without exposing tokens or private URLs.
The tunnel reaches the wrong local application
This usually indicates a target-port mismatch. Return to the terminal running agenttrail and compare its complete local URL with the HTTP tunnel target. If another local process uses the port configured in the tunnel, the public address can forward to that process instead. Correct the local target and test again.
The public dashboard stopped after a reboot
Check both lifecycles. agenttrail may need to be relaunched with npx agenttrail up, or the repository may need its reviewed npx agenttrail autostart configuration. Separately, the Localtonet client must reconnect and the tunnel must be running. Do not assume that starting one component automatically starts the others.
Another device on the LAN cannot connect directly to agenttrail
The project explicitly documents binding to 127.0.0.1, which is the loopback interface. Direct LAN access is therefore not the expected behavior. This guide does not invent an agenttrail flag for changing the bind address. Run our Localtonet client on the same host and target the loopback service instead of weakening the local bind based on an undocumented option.
Always prove the shortest path first: agenttrail process, local URL, correct repository, connected Localtonet client, correct HTTP target, running tunnel, then remote browser. This order prevents a local application problem from being mistaken for a tunnel problem.
Frequently asked questions
Does agenttrail require a global npm installation?
No global installation is required by the documented workflow. From the target repository, run npx agenttrail. npm can use a matching local package or fetch the package into its cache and make the executable available for that command.
What port does agenttrail use?
The available project evidence does not state a fixed port. Use the complete local URL printed by your own running agenttrail process. The documented bind address is 127.0.0.1, but the port must not be guessed.
Does agenttrail work without PLAN.md?
Yes. The live file tree, activity state, and available run cards do not require a plan. The richer component map appears when the repository contains a plan written using the agenttrail convention.
What does npx agenttrail init change?
Initialization creates a starter PLAN.md, appends the convention to CLAUDE.md and AGENTS.md, adds .agenttrail/ to .gitignore, and installs additive local Claude Code hooks. Review the resulting repository diff before committing it.
Does agenttrail control or send prompts to my coding agent?
The project states that the running dashboard observes and draws rather than controlling the agent. It does not send prompts or edit your code. The optional initialization workflow can produce a backfill prompt for you to copy and submit to your agent yourself.
Which coding agents can agenttrail monitor?
Claude Code has the richest documented live integration through local hooks. OpenAI Codex, Cursor, and other agents that modify repository files can be observed through the file watcher and can maintain the project map through the AGENTS.md convention.
Why should I use an HTTP tunnel for agenttrail?
agenttrail provides a browser dashboard, so an HTTP tunnel maps naturally to the local web service. Configure the tunnel with 127.0.0.1 and the exact port printed by agenttrail, then use the assigned public URL for remote browser access.
Does Localtonet require router port forwarding or a public IP?
No. Our client establishes an outbound connection to a Localtonet relay server, so this workflow does not require inbound router port forwarding, firewall changes, VPN setup, or a public IP address.
Will the public dashboard remain available if agenttrail stops?
No. The local agenttrail process must remain available, the selected Localtonet client must be connected, and the tunnel must be running. If any part of that path stops, the remote dashboard will not remain usable.
Is exposing agenttrail through an HTTP tunnel the same as using a VPN?
No. The HTTP tunnel exposes the selected local web service. It does not create a general private network. Localtonet VPN Manager is our separate mesh VPN feature, while this guide uses a standard HTTP tunnel for one dashboard.
Access your agenttrail board with Localtonet
First verify agenttrail on its printed localhost URL. Then run our client on the same machine, create an HTTP tunnel for the verified 127.0.0.1 port, apply appropriate access controls, and start the tunnel only when remote monitoring is needed.
