Self-Host LiveAgent with Docker and Localtonet

How the desktop agent, Gateway, Docker, and Localtonet fit together

LiveAgent is a local-first AI agent desktop client. Its current project documentation describes multi-model access, local file operations, command execution, managed long-running processes, scheduled tasks, MCP integration, Skills packages, and persistent memory. These capabilities belong to the local agent environment. Installing the Gateway container does not move the complete desktop agent into Docker.

The LiveAgent desktop application works without a server for ordinary local use. The optional Gateway is for controlling the local agent from a browser and supporting the project's remote collaboration workflow. The project describes the Gateway as a Go service with a WebUI that communicates through WebSocket and Protobuf. Readers who only need the desktop interface can use LiveAgent without deploying the Gateway or creating a tunnel.

The official Docker example publishes container port 8080 on host port 3000. That produces a local browser address such as http://127.0.0.1:3000 when the browser is running on the Docker host. The project documentation explicitly labels this mapping for HTTP and WebSocket traffic.

This guide does not make broader claims about an undocumented public HTTP API. It tests the browser interface and the WebSocket session initiated by the installed WebUI. It also does not assume that loading the initial page proves that every live feature works through a tunnel. The final remote test must exercise an actual browser session and inspect the WebSocket connection.

LiveAgent also advertises a built-in TunnelManager capability for exposing local services. That capability already exists in the project and should not be overlooked. This article intentionally demonstrates a Localtonet-specific workflow for teams that want to manage this endpoint through our dashboard or REST API alongside other Localtonet tunnels. It does not claim that Localtonet replaces every project-native tunnel use case.

Keep the installation order local-first. Install and test the desktop application, deploy the Gateway with persistent storage, confirm that the local WebUI reaches the expected agent, and back up its named volume. Only after those checks should you consider a remote tunnel.

Prerequisites and deployment decisions

You need a supported computer for the LiveAgent desktop application, a Docker host for the Gateway, and sufficient permissions to install and operate both. The desktop application and Docker can run on the same computer. If they run on different machines, plan the route between them and remember that 127.0.0.1 always refers to the machine on which the connection originates.

Docker must be able to pull images from GitHub Container Registry, create a named volume, publish a host port, and run a container. The Gateway image is documented as multi-architecture for amd64 and arm64. The supplied project documentation does not establish Gateway image support for other architectures.

Choose the network placement

The simplest arrangement places Docker and the Localtonet client on the same trusted machine. You can then publish the Gateway on loopback and configure the tunnel target as local IP 127.0.0.1 with port 3000. This avoids making the Docker-published port directly reachable across the LAN.

If the Localtonet client runs on another device, the Gateway must be reachable from that device. A loopback-only Docker binding will not work in that arrangement. Use a tested LAN address for the Docker host, account for the host firewall, and verify the address from the Localtonet client device before creating the tunnel. Do not guess the address or assume that one machine's loopback interface reaches another machine.

Decide whether remote access is appropriate

The Gateway controls an agent that can interact with files, execute commands, supervise processes, and connect to additional tools. Remote access should therefore be treated as access to a sensitive administrative interface, not as publication of an ordinary informational website.

Keep secrets outside the deployment record

LiveAgent can connect to model providers and compatible services. Provider keys, Localtonet device tokens, session credentials, private endpoints, and any connected MCP credentials must not appear in Docker commands, tunnel URLs, screenshots, shell history, support messages, or public documentation. This tutorial does not invent environment variables or credential fields that are not established by the supplied project documentation.

Choose a LiveAgent release channel and install the desktop client

LiveAgent installers are published through the project's GitHub Releases page. That page currently presents two distinct choices: a stable release marked Latest and newer v2 builds marked Pre-release. A newer version number does not mean that the release has replaced the stable channel.

The stable Latest release is currently v1.3.7 in the supplied release evidence. The project README describes stable macOS DMG packages for Apple Silicon and Intel as signed and notarized. The newer v2 beta releases remain prereleases and explicitly state that they do not replace the stable Latest release.

The v2 beta release notes also document different macOS packaging. Recent betas provide Apple Silicon and Intel .app.zip preview packages, and some explicitly describe them as unsigned. Their update manifests do not provide automatic macOS installation entries. Do not apply the stable DMG signing instructions to these beta ZIP assets.

Stable package choices documented by the project

For the stable workflow described by the current README, macOS users select the DMG matching Apple Silicon aarch64 or Intel x64. Windows x64 users can choose a setup executable, MSI package, or portable ZIP. Linux x86_64 users can choose AppImage, DEB, or RPM.

Replace each filename placeholder with the exact asset name from the selected release. For the documented stable Linux formats, the basic launch or installation patterns are:

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

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

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

If the package manager reports missing operating system dependencies, resolve them through your distribution's supported package-management process. The current documented Linux desktop requirement is WebKitGTK 4.1. Do not substitute another major API version unless the selected LiveAgent release explicitly supports it.

Deploy the LiveAgent Gateway with its persistent volume

The official image is ghcr.io/stack-cairn/liveagent-gateway:latest. The current README maps host port 3000 to container port 8080, applies the unless-stopped restart policy, and mounts the named Docker volume liveagent-gateway-data at /var/lib.

The mount is not optional in this tutorial. It preserves files the Gateway writes beneath /var/lib when the container is removed and recreated. The supplied evidence does not itemize every file or database stored there, so this guide does not assign undocumented meanings to individual contents. Treat the entire volume as application state and protect it as a unit.

Check Docker:

docker version

Pull the image:

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

Run the current official deployment mapping:

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

Check the container, logs, and recorded mounts:

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

In the inspection output, verify that the source volume is liveagent-gateway-data and its destination is /var/lib. If the container exits, inspect docker ps -a and its logs before attempting any remote access.

Loopback-only publishing on a same-host deployment

If the browser, Docker, and Localtonet client all run on the same trusted machine, you can reduce unnecessary LAN exposure by publishing the port only on loopback:

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

Use either the standard mapping or the loopback-only variant, not both. The loopback form will not accept direct connections from another LAN device. If the desktop application or Localtonet client is on another machine, design and test a suitable private route instead.

Verify the Gateway locally before considering a tunnel

Begin on the Docker host with http://127.0.0.1:3000. This verifies the exact published port that a same-host Localtonet client would later target. If Docker is on another machine, substitute its tested private address instead of using loopback.

Check the local listener:

curl -i http://127.0.0.1:3000/

Do not assume a specific status code, health-check path, response schema, or undocumented API route. The installed version determines the application response. A browser-rendered interface and a functioning interaction provide stronger evidence than a successful curl request alone.

Let the WebUI select the WebSocket route

The project establishes that the remote Gateway uses WebSocket and Protobuf, but the supplied evidence does not define a public WebSocket path for manual testing. Do not invent one. Let the official WebUI initiate the session and inspect the resulting connection in developer tools.

Back up and restore the Gateway named volume

A named volume survives ordinary container removal, but persistence is not the same as backup. Accidental volume deletion, host failure, filesystem damage, or an incompatible application migration can still destroy or invalidate state. Create a backup before replacing the container or updating the image.

For a consistent filesystem-level archive, stop the Gateway before copying the volume. The following example mounts the volume read-only at /data in a temporary Alpine container and writes a compressed archive into the current host directory:

docker stop liveagent-gateway

docker run --rm \
  -v liveagent-gateway-data:/data:ro \
  -v "$PWD":/backup \
  alpine \
  sh -c 'tar -czf /backup/liveagent-gateway-data.tar.gz -C /data .'

docker start liveagent-gateway

Confirm that liveagent-gateway-data.tar.gz exists, store it somewhere protected from loss of the Docker host, and restrict access because the volume may contain sensitive application state. The supplied evidence does not describe the sensitivity of each file, so handle the archive as confidential.

Restore into a separate volume first

Avoid overwriting the only existing volume during a restore test. Create a second named volume, extract the archive into it, and start the Gateway using that restored volume. Keep the original stopped and intact until validation is complete.

docker stop liveagent-gateway
docker rename liveagent-gateway liveagent-gateway-original

docker volume create liveagent-gateway-data-restored

docker run --rm \
  -v liveagent-gateway-data-restored:/data \
  -v "$PWD":/backup:ro \
  alpine \
  sh -c 'tar -xzf /backup/liveagent-gateway-data.tar.gz -C /data'

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

Use the port-binding form appropriate to your original deployment. Verify the WebUI, desktop connection, and a live browser session. If validation succeeds, document which volume is now authoritative. Do not delete the original container or original volume until the restored deployment has been tested and retained long enough for your operational requirements.

To abandon the restore test, stop and remove the new container, rename the original container, and start it again:

docker stop liveagent-gateway
docker rm liveagent-gateway
docker rename liveagent-gateway-original liveagent-gateway
docker start liveagent-gateway

Operate and update the Gateway without discarding state

Routine Docker operations act on the Gateway service, not the desktop application. Stopping the container makes the browser endpoint unavailable but does not uninstall LiveAgent. The named volume remains separate unless it is explicitly removed.

Storage-safe update procedure

The latest tag can point to a newer image after a release. Pulling it does not modify the existing container. A safe replacement process records the old image, creates a stopped-volume backup, retains the old container for rollback, and recreates the service with the same named volume.

1. Read the LiveAgent release notes and decide whether you are staying on stable or intentionally adopting a prerelease.
2. Record the old container's image identifier and configuration.
3. Stop the Gateway and create a backup of liveagent-gateway-data.
4. Pull the new image.
5. Rename the stopped old container instead of deleting it immediately.
6. Create the replacement with the same port mapping and named-volume destination.
7. Repeat the local WebUI, desktop connection, and WebSocket checks.
8. Keep the backup until rollback and migration risks have passed.

Record the existing image and inspect the deployment:

docker inspect --format '{{.Image}}' liveagent-gateway
docker inspect liveagent-gateway

After completing the stopped-volume backup described above, pull the image and retain the previous container:

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

Recreate the service with the complete persistent mount:

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

Adjust only the port-binding form if your validated deployment requires LAN access. Do not omit the volume. After local validation, retain or remove the old stopped container according to your rollback policy. Never run both old and new containers against the same volume at the same time.

If the update fails before changing stored data, stop and remove the replacement, rename the previous container back to liveagent-gateway, and start it. If the new version may have migrated or modified persistent state, restore the pre-update archive into a separate volume and validate that rollback path rather than assuming the old image can read the modified volume.

Understand the restart policy

The unless-stopped policy asks Docker to restart the container after a failure or daemon restart unless an administrator explicitly stopped it. It does not provide high availability, guarantee application health, or recover invalid configuration. Continue checking logs and browser behavior after reboots and updates.

Configure a Localtonet HTTP tunnel after the security gate

Localtonet exposes a locally reachable service without inbound router port forwarding, firewall changes, VPN setup, or a public IP address. Our client establishes an outbound connection to a selected relay server. The resulting tunnel is available only while that client is connected and the tunnel is running.

The LiveAgent README labels the Gateway's Docker mapping for HTTP and WebSocket traffic. This tutorial therefore configures a Localtonet HTTP tunnel to the same local endpoint. However, the supplied evidence does not justify a universal promise that every Gateway release and browser behavior will work transparently through every intermediary. Treat public WebSocket verification as a required acceptance test.

HTTP and File Server tunnels can use a random subdomain, a custom subdomain where supported, or a custom domain. For this HTTP workflow, select the Process Type appropriate to your deployment. All three choices serve the configured local content at a public HTTPS address. Check current DNS requirements before configuring a custom domain.

See our HTTP tunnel documentation for the current dashboard workflow and available options. Never reuse another user's device token, relay code, or public hostname.

Use the assigned public origin as presented

The LiveAgent project documents Settings → Remote as the desktop location for the Gateway address and notes that an HTTPS reverse-proxy deployment uses the HTTPS URL with port 443. For an approved Localtonet deployment, use the public HTTPS address as presented by our platform. Do not append the local Docker port 3000 to that public address.

Retain the local URL for diagnostics. If the public interface fails, test http://127.0.0.1:3000 first. If local access also fails, investigate LiveAgent or Docker. If local access works, inspect the Localtonet client, selected device, tunnel state, target address, HTTP behavior, and WebSocket connection.

Security gate for a Gateway that controls local tools

The decision to publish this Gateway must account for what the connected agent can do. File access, command execution, long-running process management, scheduled tasks, model credentials, and MCP integrations can all increase the effect of an unauthorized session.

Minimum approval questions

• Does current primary documentation for the deployed version describe a supported authentication mechanism?
• Has authentication been enabled and tested from a fresh browser session?
• Can unauthorized users load the interface, open a WebSocket session, or control the agent?
• Are user permissions appropriate for file, command, process, and connected-tool operations?
• Can credentials and sessions be revoked without rebuilding the deployment?
• Are the desktop agent's operating-system permissions limited to the intended workspace?
• Are model provider and MCP credentials protected from the browser and container logs?
• Has the named volume been backed up and has the restore procedure been tested?
• Has the public WebSocket session been verified without exposing an unauthenticated control surface?

A secret or hard-to-guess URL does not satisfy these requirements. URL secrecy is not authentication, and TLS transport does not establish who is authorized to control the agent. If the installed version lacks suitable controls or its behavior cannot be confirmed, leave the Gateway on loopback and do not start the tunnel.

Review the working environment

Limit the directories, repositories, shells, commands, scheduled tasks, MCP servers, model providers, and external services available to the agent. Avoid broad administrative privileges. A containerized Gateway does not sandbox the desktop agent's local capabilities or reduce permissions already granted to that application.

Understand independent lifecycles

The desktop application, Gateway container, Localtonet client, and tunnel have separate lifecycles. Stopping the tunnel removes public reachability through Localtonet but leaves the local Gateway running. Stopping the container leaves the tunnel with no working target. Stopping the desktop agent may leave the WebUI reachable while agent operations are unavailable.

Troubleshooting by deployment layer

The container name is already in use

Check running and stopped containers:

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

Start or inspect the existing container if it is the intended deployment. If it is an old rollback copy, inspect its mounts and confirm that required data is backed up before removing it. Do not remove a container merely to clear the name without first understanding which volume it uses.

Port 3000 is already allocated

Inspect active containers:

docker ps
docker port liveagent-gateway

Another service may already use port 3000. Stop it only if doing so is safe. Docker can publish container port 8080 on a different host port, but that becomes a custom deployment choice. Use the chosen host port consistently in local tests and the Localtonet target.

The container starts and immediately exits

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

Look for image-pull errors, architecture problems, application startup failures, or inaccessible storage. Verify that the Gateway image supports the host architecture and that the mount destination remains /var/lib.

The local browser reports connection refused

docker port liveagent-gateway
docker inspect liveagent-gateway

Confirm that the container is active and that you are testing from the correct machine. A loopback-bound port is reachable only on the Docker host. If you need access from another device, use an intentionally configured private route rather than assuming loopback will work remotely.

The WebUI loads but the desktop agent does not respond

Check the Gateway address configured under Settings → Remote, inspect container logs, and watch the WebSocket connection in browser developer tools. A successful HTML response proves only that the initial HTTP request reached the Gateway.

Let the official WebUI create the WebSocket connection. Do not guess a route or substitute a generic WebSocket client without version-specific protocol documentation, especially because the project describes Protobuf communication.

The public page loads but live updates fail

This indicates that initial HTTP delivery and the live browser session are behaving differently. Reproduce the problem while following logs:

docker logs -f liveagent-gateway

Inspect the WebSocket request, response, close code, and reconnection behavior in the browser. Compare the result with the known-good local session. Do not declare protocol compatibility based only on the page shell loading successfully.

Local access works but the public address does not

1. Confirm that the Localtonet client is running and connected.
2. Confirm that the selected device can reach the tested Gateway address.
3. Confirm that the HTTP tunnel has been started, not merely created.
4. Confirm that the local target IP and port are correct.
5. Retest the target from the environment where the Localtonet client runs.
6. Inspect browser HTTP and WebSocket activity.
7. Stop the tunnel if authentication or authorization does not behave as expected.

If our client runs in a separate container or virtual machine, its 127.0.0.1 refers to that environment, not automatically to the Docker host running LiveAgent Gateway.

The public address opens without authentication

Stop the tunnel immediately. Do not rely on keeping the URL private. Recheck the deployed Gateway version's primary documentation and configuration. If supported authentication and authorization cannot be enabled and verified, keep the service local.

The Gateway stops after a reboot

Confirm that Docker starts during boot and inspect the restart policy:

docker inspect liveagent-gateway

The unless-stopped policy preserves an administrator's explicit stop. Start the existing container with docker start liveagent-gateway when appropriate. Also confirm that the named volume remains mounted at /var/lib.

An image update appears to have no effect

Pulling a new image does not replace an existing container. Use the storage-safe replacement sequence, retain the previous container, and recreate the Gateway with liveagent-gateway-data:/var/lib. Verify the browser and WebSocket session after replacement.

State is missing after container replacement

Inspect the new container and confirm that it mounts the expected named volume:

docker inspect liveagent-gateway
docker volume inspect liveagent-gateway-data

If a different or empty volume was attached, stop the replacement before making further changes. Preserve all candidate volumes, identify the original mount from the retained container inspection, and restore from the protected archive if necessary.

Frequently asked questions