Self-Host LiveAgent with Docker and Localtonet

How the LiveAgent desktop app, Gateway, Docker, and Localtonet fit together

LiveAgent is a local-first AI agent desktop client. Its documented capabilities include multi-model access, local file operations, command execution, managed long-running processes, scheduled tasks, MCP integration, Skills packages, and persistent memory. Because it can work with files, commands, and other resources on the computer where it runs, the desktop application is the component that performs local agent work.

The desktop application does not require a server for ordinary local use. The LiveAgent Gateway is an optional service for remote browser access and collaboration. It provides a WebUI and uses HTTP and WebSocket communication to reach the local agent. This distinction matters: installing only the Gateway does not replace the desktop agent, and readers who only need local desktop access do not need to deploy the Gateway.

The official Gateway image listens on container port 8080. The documented Docker mapping publishes that port as 3000 on the Docker host, producing a local endpoint such as http://127.0.0.1:3000. The WebUI, HTTP API, and WebSocket connections share this endpoint. There is no evidenced requirement for a separate TCP tunnel, UDP tunnel, or independently exposed WebSocket port in this workflow.

The recommended order is therefore straightforward: install and test the LiveAgent desktop client, run and verify the Gateway on the local Docker host, connect the desktop application to that Gateway as documented by the project, and only then add remote access. Keeping local installation and public exposure separate makes troubleshooting much easier.

Prerequisites and deployment decisions

For this workflow, you need a computer that can run the LiveAgent desktop client, a Docker host for the Gateway, and permission to install and run software on both. They may be the same computer. If they are different machines, account for host firewalls and routing between them, and do not assume that 127.0.0.1 on one machine refers to the other.

You also need Docker with permission to pull images from GitHub Container Registry and create containers. The official Gateway image is documented as multi-architecture for amd64 and arm64. The supplied project documentation does not establish support for other CPU architectures, so confirm compatibility before using another platform.

Choose the correct network placement

Running Docker and the Localtonet client on the same machine is the simplest arrangement. The tunnel target can then be 127.0.0.1 with port 3000. Binding the Gateway to loopback also reduces unnecessary LAN exposure, although the precise Docker publishing command used later determines which host interfaces accept connections.

If the Localtonet client runs on another device, the target cannot be 127.0.0.1, because loopback always refers to the device running the client. You would need a LAN-reachable address for the Docker host and a Docker port binding that permits access from that LAN. The exact address depends on your network and must not be guessed. Test it from the Localtonet client device before configuring the tunnel.

Know which credentials are outside this guide

LiveAgent can connect to AI model providers and compatible services, but provider selection, API keys, custom base URLs, and model-specific settings depend on the services you choose. Never place model credentials in Docker commands, tunnel URLs, screenshots, browser bookmarks, or public documentation. This guide does not invent credential names or environment variables that are not established by the supplied project documentation.

Install the LiveAgent desktop client

LiveAgent installers are published through the project's GitHub Releases page. Choose the installer for your operating system and processor architecture. Package filenames include a version placeholder, so substitute the release version you actually download rather than copying the placeholder literally.

Linux package commands

Replace the placeholder filename with the exact asset you downloaded. Run commands from the directory containing that file.

For an AppImage:

chmod +x LiveAgent-<version>-Linux-x86_64.AppImage
./LiveAgent-<version>-Linux-x86_64.AppImage

For Debian or Ubuntu family systems:

sudo dpkg -i LiveAgent-<version>-Linux-x86_64.deb

For Fedora or openSUSE family systems:

sudo rpm -i LiveAgent-<version>-Linux-x86_64.rpm

A package manager may report missing operating system dependencies. Install the required dependencies using the supported process for your distribution, then retry the package installation. The verified Linux requirement is WebKitGTK 4.1; do not substitute another major API version unless the current LiveAgent release documentation explicitly supports it.

Deploy the LiveAgent Gateway with Docker

The official container image is ghcr.io/stack-cairn/liveagent-gateway:latest. The documented image is built for both amd64 and arm64. The deployment maps container port 8080 to host port 3000, names the container liveagent-gateway, runs it in the background, and configures Docker to restart it unless it has been explicitly stopped.

The project documentation also shows a named volume for Gateway data. However, the supplied verified excerpt does not preserve the complete destination path inside the container. We will not guess that path. The command below is therefore a verified functional baseline for evaluating the Gateway, but it does not claim persistent Gateway storage across container replacement. Before a production deployment, use the complete current volume mapping from the project's release documentation or README.

Check the Docker client and daemon:

docker version

Pull the official image:

docker pull ghcr.io/stack-cairn/liveagent-gateway:latest

Start the verified baseline deployment:

docker run -d \
  --name liveagent-gateway \
  --restart unless-stopped \
  -p 3000:8080 \
  ghcr.io/stack-cairn/liveagent-gateway:latest

Check whether the container is running:

docker ps --filter name=liveagent-gateway

Read its recent output:

docker logs liveagent-gateway

Optional loopback-only publishing

Docker's -p 3000:8080 syntax commonly publishes the port on host interfaces according to the Docker host's configuration. When the Localtonet client runs on the same machine, a loopback-only binding can reduce direct LAN exposure:

docker run -d \
  --name liveagent-gateway \
  --restart unless-stopped \
  -p 127.0.0.1:3000:8080 \
  ghcr.io/stack-cairn/liveagent-gateway:latest

Use either the standard documented host mapping or the loopback-only variant, not both. Loopback binding is unsuitable when the Localtonet client or another required component must connect from a different machine.

Verify the Gateway locally before exposing it

Local verification should test the same endpoint that Localtonet will later use. On the Docker host, that endpoint is http://127.0.0.1:3000. A successful test confirms that Docker port publishing reaches the Gateway and that its HTTP listener is available.

Check the local HTTP endpoint:

curl -i http://127.0.0.1:3000/

A browser-rendered interface is the clearest WebUI check. The curl result is useful for distinguishing a network refusal from an application-level response, but it does not fully test browser JavaScript or WebSocket behavior.

Understanding WebSocket verification

The Gateway uses WebSocket communication alongside its HTTP interface. A page can load successfully while a WebSocket connection fails, so complete verification should include an interaction that depends on the live connection to the desktop agent. Browser developer tools can help: open the Network panel, filter for WebSocket traffic, and look for a connection that remains open rather than repeatedly disconnecting.

Do not invent a WebSocket path and test it manually. The supplied documentation establishes that the Gateway uses WebSocket and Protobuf, but it does not establish a public path or a standalone protocol test command. Let the official WebUI initiate the connection.

Operate and maintain the Docker container

Once the Gateway works, routine administration should be predictable. Docker can stop, start, restart, inspect, and remove the named container. These operations affect the Gateway service but do not uninstall the LiveAgent desktop client.

Updating the Gateway image

The latest tag can change when a new image is published. Pulling it does not automatically replace an already running container. Updating requires pulling the image, stopping and removing the old container, and recreating it with the intended configuration.

docker pull ghcr.io/stack-cairn/liveagent-gateway:latest
docker stop liveagent-gateway
docker rm liveagent-gateway

After removal, run the selected deployment command again. Before doing so, verify persistent storage and backup requirements. The baseline command in this guide does not guarantee persistence across container replacement. In a production environment, also review release notes before updating and keep a rollback plan appropriate to your storage configuration.

Restart-policy behavior

The documented unless-stopped policy asks Docker to restart the container after a failure or Docker daemon restart unless an administrator intentionally stopped it. This does not make the service highly available, guarantee successful application startup, or recover from invalid configuration. Continue to monitor container state and logs.

A running container is also not proof that the browser workflow is healthy. Repeat the local URL and WebUI checks after upgrades, Docker configuration changes, operating system updates, or changes to the desktop application's remote settings.

Expose the verified Gateway with a Localtonet HTTP tunnel

After the Gateway works at its local address, Localtonet can provide remote access without opening an inbound router port. Our client runs on a device that can reach the Gateway, establishes an outbound connection to a Localtonet relay server, and connects a public address to the local HTTP target.

Use an HTTP tunnel for this workflow because the verified Gateway endpoint serves the WebUI, HTTP API, and WebSocket communication through the same HTTP origin. There is no evidenced need to create additional TCP or UDP tunnels.

HTTP tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. These Process Type choices serve the same local content at a public HTTPS address. Custom-domain DNS requirements must be checked against the current Localtonet documentation before making DNS changes.

For the current dashboard sequence and available options, consult our HTTP tunnel documentation. Do not copy another user's server code, authentication token, or public hostname.

Configure LiveAgent with the public address

The project documentation identifies Settings → Remote as the desktop location for the Gateway address. When a reverse proxy provides HTTPS, it instructs users to enter the HTTPS Gateway URL and use port 443. With a Localtonet HTTP tunnel, use the assigned public HTTPS address as displayed by our platform rather than appending the local port 3000.

Keep the local endpoint for diagnostics. If the public session stops working, first check http://127.0.0.1:3000. If local access also fails, troubleshoot LiveAgent or Docker. If local access works but public access fails, investigate the Localtonet client, device connectivity, tunnel state, target address, and browser behavior.

Security and production-readiness checklist

Exposing an ordinary status page and exposing an AI agent capable of local tool execution are not equivalent. LiveAgent's useful capabilities also increase the consequences of an unauthorized session. Security should be designed around the desktop agent, Gateway, Docker host, Localtonet configuration, model credentials, and any connected MCP servers.

Separate secrets from deployment instructions

Do not paste real API keys or device tokens into support requests. When recording a reproducible configuration, replace credentials with obvious placeholders and remove public URLs if the tunnel is still active. Review container logs before sharing them because application output can contain operational context.

Restrict the agent's working environment

LiveAgent's local tools can read and modify files and execute commands when enabled and requested. Run it in an environment appropriate to that level of access. Avoid granting broad administrative privileges by default. Review which directories, repositories, shells, MCP servers, scheduled tasks, and external services are available to the agent.

Understand tunnel lifecycle

A Localtonet tunnel is not permanently available merely because it exists in the dashboard. The selected device must remain connected and the tunnel must be running. Stopping the tunnel removes public reachability through that address, but it does not stop the Docker container or desktop application. Conversely, stopping the container leaves the tunnel unable to reach its target.

Troubleshooting LiveAgent, Docker, WebSocket, and tunnel problems

The container name is already in use

Docker requires unique container names. Check both running and stopped containers:

docker ps -a --filter name=liveagent-gateway

If the existing container is the deployment you want, start or inspect it instead of creating a duplicate. If it is obsolete, confirm that removing it will not discard required data, then stop and remove it before recreating the deployment.

Host port 3000 is already allocated

Another process or container may already use port 3000. Inspect active containers:

docker ps

Stop the conflicting service only if it is safe to do so. You may publish the Gateway on a different host port while keeping container port 8080, but that would be a deployment choice rather than the documented example. If you change the host port, use the same chosen port in local tests and as the Localtonet target.

The container starts and immediately exits

Show stopped containers and inspect the logs:

docker ps -a --filter name=liveagent-gateway
docker logs liveagent-gateway

Look for architecture errors, image-pull problems, missing resources, or application startup failures. Do not create a tunnel until the container remains running.

The browser reports connection refused locally

Confirm that the container is active and that Docker reports the expected port mapping:

docker port liveagent-gateway
docker inspect liveagent-gateway

Verify that you are testing from the correct machine. 127.0.0.1:3000 works only from the Docker host. If you are testing from another device and used a loopback-only binding, remote LAN connections are intentionally unavailable.

The WebUI loads but the desktop agent does not connect

This usually narrows the problem to the relationship between the browser, Gateway, and desktop application rather than the initial Docker port mapping. Check the Gateway address entered under Settings → Remote, inspect container logs, and use browser developer tools to see whether the WebSocket connection opens or repeatedly fails.

If using the public address, enter the HTTPS URL issued for the tunnel. Do not append :3000 to that public URL. Port 3000 is the local Docker-host port, not necessarily the public-facing port.

Local access works but the public URL does not

Check the problem in layers:

1. Confirm the Localtonet client is running and connected.
2. Confirm the selected device is the device that can reach the Gateway.
3. Confirm the HTTP tunnel has been started, not merely created.
4. Confirm its local target is the correct IP address and port.
5. Retest that target from the Localtonet client device.
6. Inspect browser developer tools for HTTP or WebSocket failures.

If the client runs in a separate container or virtual machine, its 127.0.0.1 is not the Docker host's loopback interface. Use a reachable target appropriate to that network design and verify it directly from the client environment.

The public page loads but live updates fail

A successful initial HTML request does not prove that the WebSocket session works. Use the browser's Network panel to inspect the connection initiated by the official WebUI. Also inspect Gateway logs while reproducing the problem:

docker logs -f liveagent-gateway

Avoid guessing a manual WebSocket path. The verified documentation does not provide one in the supplied evidence. Test through the WebUI so it can use the route and protocol expected by the installed version.

The Gateway stops after a machine reboot

Confirm that Docker itself starts during boot and inspect the container's restart policy:

docker inspect liveagent-gateway

The deployment command uses --restart unless-stopped. If an administrator explicitly stopped the container, Docker preserves that intention. Start it again with docker start liveagent-gateway.

An update appears to have no effect

Pulling a newer image does not modify an existing container. Inspect the currently running container and recreate it with the updated image when appropriate. Resolve persistent storage before removal, because the baseline deployment in this guide does not promise that data stored inside the old container will survive replacement.

Frequently asked questions