Install LiveDebugger locally, validate both development endpoints, and evaluate remote access without assuming that a public URL is safe or fully compatible
LiveDebugger provides a browser-based view into Phoenix LiveView component trees, assigns, callback execution, state transitions, and rendered elements. This guide installs the current 1.0 series with the documented Igniter command, reviews the generated development-only integration, and verifies the default debugger endpoint at http://localhost:4007. It then explains how to configure a Localtonet HTTP tunnel for that endpoint while keeping the debugger separate from the Phoenix application itself. Because the available LiveDebugger documentation does not confirm every interactive transport, public-host, or browser-origin behavior through an HTTPS reverse tunnel, remote use must be tested end to end and must not be treated as safe without a suitable protective access layer.
📋 What's in this guide
Understand the LiveDebugger and Phoenix endpoint architecture
LiveDebugger is a browser-based debugging tool for applications built with Phoenix LiveView. Its documented capabilities include viewing the LiveView and LiveComponent tree, inspecting assigns in real time, tracing and filtering callback execution, observing state changes, and selecting rendered elements to identify the component that produced them. The project’s official documentation provides the current installation overview and feature introduction.
LiveDebugger is embedded into a development project, but its default browser interface is served at a distinct local address: http://localhost:4007. That is not necessarily the same address or port as the Phoenix application under examination. For example, the Phoenix application has its own endpoint selected by the host project, while LiveDebugger has its documented default endpoint on port 4007.
This distinction matters during remote collaboration. A developer who only needs to view the debugger may need access to the debugger endpoint. A collaborator who must click, submit forms, trigger LiveView events, or reproduce behavior in the application normally needs access to the Phoenix application endpoint as well. Tunneling port 4007 does not automatically expose the Phoenix application, and exposing the Phoenix application does not automatically expose port 4007.
| Component | Role | Remote-access implication |
|---|---|---|
| Phoenix application | Hosts the LiveView interface and receives the user interactions being debugged. | A remote collaborator needs this endpoint if they must operate the application rather than only observe an already active session. |
| LiveDebugger | Displays component structure, assigns, callbacks, state changes, and element relationships. | Its documented default endpoint is http://localhost:4007. A tunnel targeting this port exposes the debugger, not the Phoenix application. |
| Localtonet client | Establishes an outbound connection from a device that can reach the selected local service. | The local target must be reachable from the client’s own network environment. |
| Localtonet HTTP tunnel | Provides a public HTTPS address that forwards to one selected local HTTP target. | Use a separate configuration for each distinct local endpoint that genuinely needs remote access. |
A second public hostname can also change how the Phoenix application evaluates requests. Phoenix and application-specific code may enforce host checks, allowed origins, LiveView socket origin rules, secure-cookie behavior, CSRF protections, redirects, callback URLs, or absolute URL generation. Those settings belong to the Phoenix application and must remain restrictive. Do not disable origin or CSRF checks merely to make a remote test pass.
The maintainers explicitly state that LiveDebugger should not be used in production and require the dependency to be limited to the development environment. Keep only: :dev, use sanitized development data, and never attach the debugger to a production release or production dataset.
Prerequisites and environment checks
Begin with an existing Phoenix LiveView application that you are authorized to modify and debug. The application should already have a working local development procedure. LiveDebugger documents its dependency, layout integration, Igniter task, and default debugger endpoint, but it does not define the database, assets, secrets, external services, or startup sequence for every Phoenix project.
Project prerequisites
- An existing Phoenix application that uses Phoenix LiveView.
- A functioning local development environment for that application.
- Mix available in the shell used to manage the project.
- Permission to change
mix.exsand the application root layout. - Igniter available to the project if you plan to use the primary installation method.
- A clean or committed working tree so generated changes can be inspected and reverted.
- A browser in the application’s local network environment.
The current LiveDebugger README and documentation show the dependency requirement as ~> 1.0.0. That requirement accepts compatible releases in the 1.0 series. The supplied release evidence identifies v1.0.2 as the latest published release at the time of review. The installation command remains:
mix igniter.install live_debuggerLiveDebugger’s published material does not establish a universal Igniter bootstrap command or a complete Elixir, Erlang, Phoenix, and Phoenix LiveView compatibility matrix in the evidence available for this guide. If the task is unavailable, follow the dependency-management policy of your project or use the documented manual installation described below.
Localtonet prerequisites
- A Localtonet account and access to the current dashboard.
- The Localtonet client installed on the Phoenix host or on another device that can reach the required endpoint.
- A device-specific authentication token handled as a secret.
- An available relay server selected from the current dashboard.
- A verified local IP address and port for each endpoint that needs a tunnel.
- A protective access layer appropriate for debugger data before any public exposure.
A tunnel forwards traffic to an existing service. It does not repair a failed dependency installation, a broken root layout, an inactive Phoenix process, or an unreachable debugger. Confirm the Phoenix application and http://localhost:4007 locally before configuring remote access.
Install LiveDebugger with Igniter
Run the installer from the Phoenix project root, where mix.exs is located. Preserve the current working state first. Igniter is expected to modify project files, so a clean baseline makes it easier to see whether the transformation completed correctly.
Open the Phoenix project root
Use a terminal in the directory containing mix.exs. Confirm that you are modifying the intended development project and that its normal supporting services are available.
Run the documented Igniter task
Execute mix igniter.install live_debugger. The LiveDebugger documentation states that this task adds the dependency and modifies root.html.heex.
Review the generated changes
Inspect the project diff. Confirm that the dependency is development-only and that the LiveDebugger tags expression appears inside the actual root layout’s <head>. Resolve any reported conflict before continuing.
The expected dependency form in the current documentation is:
defp deps do
[
{:live_debugger, "~> 1.0.0", only: :dev}
]
endThe exact resolved patch release is determined by Mix within the declared version requirement and the project’s lock file. Do not replace a reviewed lock-file update with an arbitrary version copied from another project.
The documented root-layout example is:
<head>
<%= Application.get_env(:live_debugger, :live_debugger_tags) %>
</head>
The example path is lib/my_app_web/components/layouts/root.html.heex, where my_app_web represents the project’s own namespace. Use the root layout actually rendered by your application. The expression attaches the LiveDebugger meta tag and scripts in the development environment and enables the documented browser features.
For the maintained setup text, warnings, and optional configuration entry point, consult the LiveDebugger README. The official LiveDebugger documentation also presents the installation paths and feature overview.
only: :dev
Do not move LiveDebugger into general dependencies or a production release. The development-only restriction is an explicit project requirement and a security boundary, not an optional optimization.
Manual installation alternative
Use the manual method when Igniter is unavailable, when it cannot match a customized project layout, or when you need to apply the two changes directly. If Igniter already completed both changes, do not duplicate them.
Add the development dependency
Add {:live_debugger, "~> 1.0.0", only: :dev} to the list returned by the existing deps/0 function. Preserve valid Elixir syntax and the surrounding dependencies.
Add the root-layout expression
Insert <%= Application.get_env(:live_debugger, :live_debugger_tags) %> inside the <head> of the application’s real root HEEx layout.
Retrieve dependencies and start the application using its established development workflow after either installation method. The exact preparation and startup commands depend on the host project, so this guide does not substitute a generic command for project-specific database, asset, environment, or service requirements.
Start Phoenix and verify both endpoints locally
LiveDebugger’s documented default address is http://localhost:4007. The endpoint is available after the Phoenix application starts. Before adding a tunnel, verify the application endpoint, the debugger endpoint, and the interaction between them in the same local browser environment.
Start the Phoenix application in development
Use the project’s normal development procedure. Watch its output for dependency, compilation, template, configuration, database, asset, socket, or port errors.
Open the Phoenix application locally
Use the application’s established local URL. Navigate to a LiveView that produces the behavior you intend to inspect and confirm that ordinary interactions work.
Open LiveDebugger locally
Open http://localhost:4007 from the same effective host environment. If the project deliberately changed LiveDebugger configuration, use its configured address instead of the default.
Exercise an active LiveView
Interact with the Phoenix application and confirm that LiveDebugger displays useful component, assign, callback, state, or element information. This verifies more than a simple response from port 4007.
Optional browser extensions
LiveDebugger offers official Chrome and Firefox DevTools extensions. The project states that the browser plugin alone is not enough. The Mix dependency, layout integration, running Phoenix application, and debugger endpoint are still required. Current extension links are maintained in the DevTools extension section of the LiveDebugger README.
localhost refers to the current network environment
If Phoenix runs inside a container, virtual machine, or remote development environment, localhost:4007 on the physical host may not reach it. Confirm the bind address, port publication, and network route established by your project. The Localtonet client must be able to reach the chosen target from where that client actually runs.
What is and is not established about remote compatibility
The primary LiveDebugger documentation establishes installation, browser integration, and a default local endpoint at http://localhost:4007. It does not, in the evidence available for this guide, state that every LiveDebugger feature works unchanged through an arbitrary public HTTPS reverse tunnel.
LiveDebugger is interactive and observes an active LiveView application. A complete remote workflow can involve more than loading the initial debugger HTML. Depending on the implementation and application configuration, browser behavior may rely on long-lived or real-time connections, generated URLs, the public host, the browser origin, cookies, or communication with the Phoenix application. The supplied documentation does not provide a confirmed public-host configuration recipe for this scenario.
If the public URL displays the LiveDebugger shell, that proves only that an HTTP request reached the local service. It does not establish that component updates, callback tracing, element inspection, DevTools integration, or communication with a separately hosted Phoenix application will work. Test every required feature from the actual remote browser.
When the collaborator needs the Phoenix application too
If the collaborator must reproduce the issue by clicking the application, submitting a form, navigating between LiveViews, or triggering a socket event, they need a reachable Phoenix application endpoint in addition to LiveDebugger. That may require a second Localtonet HTTP tunnel targeting the application’s local port.
A second tunnel produces a separate public origin unless the application architecture deliberately combines the paths. The Phoenix application may therefore need development configuration that recognizes its temporary public host and HTTPS origin. Review the project’s endpoint host configuration, LiveView socket origin policy, cookie settings, redirects, CSRF behavior, and any application-specific origin allowlists.
Make only the narrow changes required for the temporary development hostname. Do not use wildcard origin acceptance, disable CSRF protection, or turn off host validation as a general workaround. The exact Phoenix settings depend on the Phoenix and LiveView versions and the application’s configuration, so they must be validated against that project’s primary documentation and code.
Decision guide before tunneling
| Remote task | Likely endpoint requirement | What must be tested |
|---|---|---|
| View an already populated debugger session | LiveDebugger endpoint on port 4007 | Initial page load, continuing updates, callback data, assigns, and session behavior. |
| Operate the application and observe the result | LiveDebugger plus the Phoenix application endpoint | Both public URLs, LiveView socket behavior, allowed origins, cookies, CSRF, redirects, and debugger updates. |
| Use a DevTools extension beside the application | Application, debugger, dependency, layout integration, and compatible browser extension | Extension discovery, public-host behavior, element inspection, and communication between the browser surfaces. |
| Perform an unattended or long-lived session | Not recommended without a verified protective layer and operational controls | Authorization, data exposure, tunnel lifecycle, client connectivity, and cleanup procedures. |
Configure the Localtonet HTTP tunnel
Configure the tunnel only after the debugger works locally and only if you have an appropriate way to prevent unauthorized access. LiveDebugger presents an HTTP endpoint, so use a Localtonet HTTP tunnel. The following sequence keeps configuration aligned with the documented Localtonet lifecycle while leaving testing and shutdown to separate operational sections.
Install and run the Localtonet client
Run our client on the development host or another device that can reach the LiveDebugger endpoint. Keep the client connected for the duration of the tunnel session.
Authenticate or select the client device
Use the device-specific authentication token associated with the intended client. Never place that token in the Phoenix repository, screenshots, shared terminal output, issue reports, or public examples.
Select an available relay server
Choose a currently available server or region from the dashboard. Do not copy a server code from an old tutorial because availability can vary by account, plan, region, and product state.
Create the HTTP tunnel configuration
Select an HTTP tunnel and enter the local IP address and port reachable from the selected client. Use port 4007 when LiveDebugger is using its documented default. HTTP tunnels may use Random Sub Domain, Custom Sub Domain, or Custom Domain process types where available, and all serve the target at a public HTTPS address.
Start the tunnel
Creating the configuration does not start it. Use the Start button and wait for the selected device and tunnel to be connected. The public address is available only while the client remains connected and the tunnel remains running.
Use the current Localtonet HTTP tunnel documentation alongside the live dashboard for current field names and account-specific choices. We intentionally do not hardcode relay codes, regions, plan availability, or custom-domain DNS instructions here.
If the Localtonet client runs in the same network environment as LiveDebugger, localhost and port 4007 may be the appropriate target. If the client runs elsewhere, localhost refers to that other device. Enter a local IP address reachable from the client and test that route before starting the tunnel.
If the collaborator also needs the Phoenix application, configure and assess that endpoint separately. Use the application’s verified local address and port rather than reusing port 4007. Do not expose an additional endpoint unless the session genuinely requires it.
Verify the complete workflow from the remote browser
Remote verification is an operational test, not part of creating the tunnel. Use the exact device and browser intended for the collaboration session. Testing only from the development machine can conceal origin, cookie, socket, DNS, or browser-policy differences.
Confirm the local services again
Verify the Phoenix application and LiveDebugger locally immediately before the test. This establishes that any new failure is associated with the remote path or public-host configuration.
Open the assigned debugger URL remotely
Use the assigned Localtonet HTTPS address from a separate browser or device. Confirm that the intended debugger interface loads rather than another local service.
Test continuing debugger updates
Keep the page open while activity occurs in the target LiveView. Verify component updates, assigns, callback tracing, state changes, and any element-inspection capability required by the session.
Test the Phoenix endpoint when required
If a separate application tunnel is part of the workflow, open it remotely and exercise a sanitized scenario. Confirm LiveView socket connectivity, navigation, forms, cookies, CSRF handling, redirects, and expected debugger updates.
Reject partial compatibility
If the shell loads but required real-time features fail, do not describe the setup as working. Keep the session local or use another approved collaboration method until the transport and public-host behavior are understood.
A successful request from the host itself does not establish that a remote browser can use the complete tool. Browser origin, host, extension support, cookies, sockets, and application policy can differ across local and public URLs.
Protect the debugger before any public exposure
LiveDebugger can expose component structure, assigns, callback behavior, state transitions, and relationships between rendered elements and internal components. Depending on the development data, this may reveal personal information, tokens, internal identifiers, business state, or implementation details. Treat the debugger as an administrative development surface.
The evidence available for this article does not establish a specific Localtonet HTTP-tunnel authentication or IP-restriction procedure that can be documented reliably for every account and product version. We therefore do not claim that an unlisted dashboard option protects this workflow.
A temporary, random, custom, or difficult-to-guess URL is not authorization. If your current setup cannot require suitable authentication or otherwise restrict access to approved collaborators, do not expose the debugger publicly. Keep it local or use an organization-approved protected access method instead.
Keep the dependency and data development-only
Retain only: :dev and use a dedicated development instance. Avoid production databases, copied customer records, live credentials, access tokens, private keys, and production integrations. Prefer synthetic or sanitized data that reproduces the problem without revealing real user information.
Protect Localtonet device tokens
The Localtonet authentication token identifies a client device. Do not commit it to source control, place it in Phoenix configuration examples, expose it in screen recordings, or send it to a collaborator as an access credential. Device authentication and authorization to view the debugger are different concerns.
Minimize the exposed surface
Expose only the endpoint required for the session. If the collaborator only needs the debugger, do not automatically expose the Phoenix application too. If they must operate the application, expose only the required development endpoint and preserve its normal authentication, authorization, origin, socket, and CSRF protections.
Use the shortest practical session
Start the tunnel when the authorized session begins, observe the session, and stop the tunnel immediately afterward. A configured but stopped tunnel is different from an active public endpoint. Delete obsolete tunnel configurations when they are no longer needed.
Review visible information before sharing
Inspect representative LiveViews locally before inviting a collaborator. Look at assigns, callback arguments, component names, application logs, screenshots, and browser developer tools from the perspective of someone who should not know the application internals. Remove secrets and unnecessary personal data before remote access begins.
Routine operation, shutdown, and troubleshooting
A controlled session routine
- Start the Phoenix application in its development environment.
- Verify the Phoenix application locally.
- Open
http://localhost:4007and verify LiveDebugger locally. - Confirm that the required protective access layer is active.
- Start the Localtonet client.
- Start only the HTTP tunnel or tunnels required for the session.
- Test the complete workflow from the collaborator’s browser.
- Perform the debugging task using sanitized data.
- Stop every active tunnel when the session ends.
- Shut down the development application when it is no longer needed.
Shutdown and cleanup
Stop the tunnel in the dashboard after the session. If the tunnel is not expected to be reused, delete it. Stop the Phoenix development process, remove any temporary public hostname from application configuration, and revert any temporary origin or callback entries that were added for the test. Review shared screenshots and recordings for exposed state or credentials.
The Igniter task is unavailable
Confirm that the shell is in the correct Mix project and that Igniter is available through the project’s supported dependency workflow. The LiveDebugger documentation confirms the task but does not establish a universal Igniter installation command. If the task cannot be used, apply the documented dependency and root-layout changes manually.
The project no longer compiles
Inspect the generated diff and start with the first relevant compiler error. Check for malformed dependency-list syntax, a duplicate live_debugger entry, an expression inserted outside the root layout’s <head>, or an unresolved Igniter conflict. Revert to the clean baseline if necessary and apply the two documented changes carefully.
Port 4007 does not respond
Confirm that the Phoenix application is still running in development and that LiveDebugger is present in the development dependency set. Recheck the root-layout integration and application logs. If the project intentionally customized LiveDebugger, consult its configuration and use the configured endpoint rather than assuming port 4007.
The debugger opens but browser features are missing
Verify that the LiveDebugger tags expression is inside the root layout’s <head> and that the rendered page uses that layout. Remember that the optional DevTools extension cannot replace the Mix dependency or layout integration.
Local access works but the public URL does not
Check from the inside out. Confirm the local endpoint, then verify that the Localtonet client’s device can reach the same IP address and port. Confirm that the correct device token and server are selected and that the tunnel has been started. If the client runs inside a different container, virtual machine, or physical device, localhost:4007 may refer to the wrong environment.
The public page loads but updates fail
Treat this as a compatibility failure rather than a successful setup. Inspect browser errors and application logs for failed real-time connections, origin rejection, host mismatch, cookie problems, or generated URLs that still point to localhost. The supplied LiveDebugger documentation does not define a universal reverse-tunnel correction, so use project-specific primary documentation before changing Phoenix or LiveDebugger configuration.
The collaborator cannot operate the application
Confirm whether only port 4007 was exposed. A LiveDebugger tunnel does not expose the Phoenix application endpoint. If remote application interaction is required, evaluate a separate application tunnel and its host, origin, LiveView socket, cookie, CSRF, redirect, and authentication requirements.
The Phoenix socket rejects the public origin
Do not disable origin checking globally. Add only the exact temporary development origin if the application’s supported configuration permits it, and remove that entry after testing. Consult the Phoenix and LiveView documentation that matches the versions used by the project.
The tunnel was created but is unavailable
Creation and execution are separate lifecycle states. Use the Start button after configuration. The selected Localtonet client must also remain connected. The public endpoint is unavailable when either the client disconnects or the tunnel stops.
The public URL reaches the wrong service
Stop the tunnel immediately. Recheck the target IP address and port from the perspective of the Localtonet client device. Port 4007 is LiveDebugger’s documented default, but another process or customized configuration may occupy a different endpoint.
Test the Phoenix application, then LiveDebugger locally, then target reachability from the Localtonet client, then the public debugger URL, and finally the separate public Phoenix URL if one is required. This order helps distinguish application, network, tunnel, origin, and browser failures.
Frequently asked questions
What command installs LiveDebugger with Igniter?
Run mix igniter.install live_debugger from the Phoenix project root. The current documentation says it adds the dependency and modifies root.html.heex. Review the generated diff and confirm that the dependency remains restricted to :dev.
Which LiveDebugger dependency requirement is currently documented?
The current README and documentation show {:live_debugger, "~> 1.0.0", only: :dev}. The supplied release evidence identifies v1.0.2 as the latest published release at review time, while Mix resolves the project’s actual compatible version through its dependency and lock-file workflow.
What is the default LiveDebugger address?
After the Phoenix application starts, LiveDebugger runs by default at http://localhost:4007. Verify it locally before configuring a tunnel. Use the configured endpoint instead if the project deliberately changed the default.
Does tunneling port 4007 expose the Phoenix application?
No. Port 4007 is LiveDebugger’s documented default endpoint. The Phoenix application has its own local endpoint. A collaborator who must operate the application may need a separate tunnel and appropriate Phoenix host, origin, socket, cookie, CSRF, redirect, and security configuration.
Is LiveDebugger confirmed to work completely through a public HTTPS tunnel?
The supplied LiveDebugger documentation confirms its local endpoint but does not establish that every interactive feature works unchanged through an arbitrary public HTTPS reverse tunnel. Test initial loading, continuing updates, callback tracing, assigns, element inspection, public-host behavior, and any browser extension from the actual remote browser.
Can I expose LiveDebugger using only a difficult-to-guess URL?
No. An obscure URL is not authorization. If you cannot place the debugger behind a verified protective layer suitable for your environment, do not publish it. Keep the debugger local or use an approved protected collaboration method.
Can LiveDebugger be used in production?
No. The maintainers explicitly state that it should not be used in production. Keep the dependency limited to the development environment with only: :dev. A tunnel does not change this restriction.
Is the LiveDebugger browser extension enough by itself?
No. The official project states that the main dependency must be added to the Mix project. The optional Chrome or Firefox extension complements the dependency, root-layout integration, running Phoenix application, and debugger endpoint.
Does the Localtonet client have to run on the Phoenix host?
Not necessarily. It must run on a device that can reach the selected local endpoint. If it runs in another environment, localhost refers to that client device, so configure a reachable local IP address and verify the route before starting the tunnel.
Does creating a Localtonet tunnel start it automatically?
No. Creating and starting are separate lifecycle actions. Use the Start button after configuration. The public endpoint remains available only while the selected client is connected and the tunnel is running.
Do I need router port forwarding or a public IP address?
No. The Localtonet client establishes an outbound connection to our relay, so this workflow does not require inbound router port forwarding, a public IP address, VPN setup, or inbound firewall changes. The resulting URL is still a public endpoint and must be protected accordingly.
Evaluate protected remote debugging with Localtonet
Install LiveDebugger as a development-only dependency, verify the Phoenix application and port 4007 locally, and confirm that you have an appropriate protective layer. You can then create a temporary Localtonet HTTP tunnel, test every required interactive feature from the remote browser, and stop the tunnel immediately after the session.
Get Started Free →
