Set Up Arcane Docker Web UI Access with Localtonet

How the Arcane and Localtonet setup works

Arcane runs as a single container and provides a browser-based management interface for Docker. In the documented Compose deployment, the container listens on port 3552, stores its application data in a named Docker volume, mounts a directory containing Compose projects, and receives access to the host Docker socket. That socket access is what allows Arcane to inspect and manage Docker resources on the same host.

Localtonet serves a separate role. After Arcane is working locally, the Localtonet client on the same machine, or on another device that can reach the Arcane host, establishes an outbound connection to one of our relay servers. An HTTP tunnel then forwards requests from its public HTTPS address to Arcane's local IP address and port. The public endpoint remains available only while the selected Localtonet client is connected and the tunnel is running.

This separation is important. Arcane manages Docker, while Localtonet provides the remote path to Arcane's existing web service. A tunnel does not install Arcane, fix an unhealthy container, configure Docker permissions, or replace Arcane's own authentication. Verify each layer independently: Docker first, Arcane second, local browser access third, and the Localtonet tunnel last.

Prerequisites and deployment decisions

For the Docker Compose path, start with a machine that has a functioning Docker installation and Docker Compose support. Your account must be able to run Docker commands and create the directories that will hold your Compose projects. You also need a browser for the initial local sign-in and a Localtonet client on a device that can reach the completed Arcane service.

Confirm Docker and Compose before creating the Arcane configuration:

docker version
docker compose version

Both commands should return version information without a connection or permission error. If the Docker client cannot connect to the daemon, resolve that host-level problem before continuing. A Localtonet tunnel cannot make an unavailable Docker daemon or failed Arcane container operational.

Choose the projects directory

Arcane needs an absolute directory for Compose projects. The official example uses /opt/docker. You may retain that path or substitute another absolute path appropriate for your machine. If projects already exist, choose the directory that contains them. If this is a new installation, choose the directory in which you want Arcane to create and manage projects.

The documented example mounts the projects directory at the same path inside the container:

- /opt/docker:/opt/docker

It then sets:

- PROJECTS_DIRECTORY=/opt/docker

Matching host and container paths makes relative mounts such as ./config resolve consistently for Arcane and Docker. A different container path is supported, but it introduces path translation that should be configured deliberately. For a first installation, keeping the paths identical is easier to understand and troubleshoot.

Choose the host UID and GID

The official images begin as root only to prepare the container and then run as a non-root user. The PUID and PGID values determine the host UID and GID that own files created by Arcane. The documented example uses 1000 for both, but those values must match the intended account on your own host rather than being copied without checking.

On a Linux host, these commands display the current user's numeric identifiers:

id -u
id -g

If PUID and PGID are omitted, Arcane uses its built-in user 65532:65532. Whichever method you choose, the resulting user must be able to work with the mounted projects directory.

Decide where the Localtonet client will run

The simplest target is a Localtonet client on the same host as Arcane. In that arrangement, the HTTP tunnel can target 127.0.0.1 on port 3552. If the client runs on a different machine, use an Arcane host address that is reachable from that client device. Test that network path locally before creating the tunnel.

Install Arcane with Docker Compose

Arcane's documented Docker Compose installation has three primary steps: generate the required encryption key, create compose.yaml, and start the service. Perform these actions in a dedicated directory so later Compose commands use the same project configuration.

1. Generate the encryption key

Arcane documents three supported generation methods. You need to use only one. If Docker is already available, the temporary-container method avoids installing another utility:

docker run --rm ghcr.io/getarcaneapp/manager:latest /app/arcane generate secret

If OpenSSL is installed, the documented alternative is:

openssl rand -hex 32

If the Arcane CLI is already installed, it can generate the value as well:

arcane-cli generate secret

Save the output somewhere protected while preparing the deployment. Arcane does not use JWT_SECRET. If an older configuration still defines that variable, Arcane logs a warning during startup, and it should be removed. Session tokens are signed using an ML-DSA-87 key that Arcane generates and stores itself.

2. Create compose.yaml

Create a deployment directory, enter it, and create compose.yaml. The following is the documented Arcane Compose structure. Replace <your-encryption-key> before starting it. Also replace the projects path and numeric user identifiers if the example values do not match your host.

services:
  arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    ports:
      - '3552:3552'
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data
      - /opt/docker:/opt/docker
    environment:
      - APP_URL=http://localhost:3552
      - PUID=1000
      - PGID=1000
      - ENCRYPTION_KEY=<your-encryption-key>
      - PROJECTS_DIRECTORY=/opt/docker
    cgroup: host
    restart: unless-stopped

volumes:
  arcane-data:

Preserve valid YAML indentation. Tabs, misplaced list markers, and an incorrectly indented top-level volumes section can prevent Compose from parsing the file. You can ask Docker Compose to render and validate the effective configuration before starting:

docker compose config

Review the output carefully because it may contain the encryption key. Do not copy the rendered configuration into a public issue or shared log.

3. Start the service

From the directory containing compose.yaml, run:

docker compose up -d

Detached mode returns control to the shell while Arcane continues running. On the first start, Docker may need to download the image, and Arcane may need time to initialize its database.

Alternative: use the Linux installation script

Arcane also documents a Linux convenience script that sets up Docker and Arcane:

curl -fsSL https://getarcane.app/install.sh | sudo bash

A command that downloads a script and immediately runs it with elevated privileges should be used only after you have reviewed and accepted that workflow. The Compose method gives you an explicit configuration file to inspect before execution, while the convenience script can help on a Linux machine that does not yet have Docker configured. Do not run both methods for the same deployment unless the current Arcane documentation specifically directs you to migrate between them.

Understand Arcane's important configuration

A working installation is easier to maintain when each mount and environment variable has a clear purpose. The base configuration is enough to start Arcane, but directory ownership, project path handling, health checks, and Docker access deserve deliberate review before remote access is enabled.

Project path translation

Matching paths, such as /opt/docker:/opt/docker, are the clearest arrangement because both the host and container refer to the project directory by the same name. Arcane can also work when the container path differs. For example, a host path could be mounted at another path inside the container, and Arcane can read its own mounts to translate project paths for Compose.

If you need to state the mapping explicitly, Arcane supports:

PROJECTS_DIRECTORY=<containerPath>:<hostPath>

Do not use a relative value such as opt/docker. The projects path must be absolute.

Optional build and backup folders

Arcane supports an optional /builds folder for Dockerfiles and build contexts used by the Build Workspace. It also supports an optional /backups folder for exported volume backups. These folders are not required for the initial deployment.

If you enable them, use either an intentional host bind mount or a declared named volume. A host path makes the storage location directly visible on the machine. A named volume leaves management to Docker and must also be declared in the top-level volumes section.

Container health check

Arcane includes an arcane health command that calls its local /api/health endpoint and exits with a nonzero status if the server is not responding. The documented health-check configuration is:

healthcheck:
  test: ['CMD', './arcane', 'health', '--timeout', '2s']
  interval: 10s
  timeout: 3s
  retries: 5
  start_period: 15s

Add this under the Arcane service at the same indentation level as image, ports, and volumes. The start_period allows time for first-start database migrations before failed checks begin counting against the retry limit.

SQLite and external PostgreSQL

Arcane stores data in a SQLite file inside arcane-data by default, and its documentation identifies that arrangement as suitable for most setups. Arcane can instead use PostgreSQL through DATABASE_URL. A database migration is an operational project of its own, so do not switch merely because remote access is being enabled. The Localtonet tunnel targets the Arcane HTTP interface and does not require direct access to SQLite or PostgreSQL.

SELinux hosts

On an SELinux host, Arcane recommends using a Docker socket proxy and adding :z to the projects-directory mount. If a direct socket mount is necessary, the documented alternative disables SELinux labeling for the Arcane container and relabels the projects mount:

services:
  arcane:
    image: ghcr.io/getarcaneapp/manager:latest
    container_name: arcane
    ports:
      - '3552:3552'
    security_opt:
      - label:disable
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - arcane-data:/app/data
      - /opt/docker:/opt/docker:z
    environment:
      - PROJECTS_DIRECTORY=/opt/docker

This excerpt illustrates only the SELinux-specific changes and is not a replacement for the complete deployment configuration. Prefer the socket-proxy approach when you need to limit Arcane's access to the Docker API.

Verify Arcane locally before creating a tunnel

Local verification establishes a known-good baseline. If Arcane does not work directly on the host or local network, adding a public endpoint only creates another layer to investigate.

Check the container state

Run the following from the directory containing compose.yaml:

docker compose ps

The Arcane service should be running. If it exits, inspect its recent output:

docker compose logs arcane

Look for direct errors concerning the encryption key, port binding, project-directory permissions, Docker socket access, YAML configuration, or database initialization. Correct the underlying setting rather than repeatedly restarting the same invalid configuration.

Open the web interface

On the Arcane host, open:

http://localhost:3552

If the browser is on another machine in the same trusted network, use the Arcane host's reachable local address with port 3552. Whether that path is available depends on the host's Docker port publication, local firewall, and network policy.

Complete the first sign-in

The documented initial credentials are:

Username: arcane
Password: arcane-admin

Arcane prompts you to change the password during the first sign-in. Complete that change before exposing the interface remotely. Confirm that the new credential works and store it using an appropriate password manager or other approved credential-management process.

Confirm Docker visibility

After signing in, the dashboard should summarize the environment and its resource usage. Confirm that Arcane can see the Docker resources you expect. If the application page loads but Docker information is missing or operations fail, focus on Docker socket access, the selected deployment mode, SELinux handling, and container logs.

Validate the exact path the Localtonet client will use

If Localtonet will run on the Arcane host, verify http://127.0.0.1:3552 from that host. If the Localtonet client will run elsewhere, open the Arcane URL from the client device using the Arcane host's reachable local IP address. This test distinguishes an Arcane problem from a route or firewall problem before a tunnel is involved.

Secure Arcane before remote access

Publishing an administrative application changes its exposure. The safest approach is to expose only the web port, retain Arcane's authentication, minimize Docker permissions where practical, and keep secrets out of the tunnel configuration.

Replace the default password first

Never start remote access while the documented arcane and arcane-admin combination is still active. The first-login password change is a required security step, not optional cleanup. Use a unique password that is not shared with Docker registries, the host account, Localtonet, or other applications.

Review Arcane users and permissions

Use separate user identities where Arcane's current access controls support your intended team workflow. Grant only the level of access each administrator needs. Remove accounts that are no longer required and keep at least one controlled recovery path for authorized administrators.

Treat Docker socket access as privileged

The standard installation mounts /var/run/docker.sock. This gives Arcane the ability to manage Docker, but it also means that compromise of the Arcane application or an administrator account can have consequences beyond the web interface. Arcane's documentation recommends a socket proxy when Docker access should be restricted. Evaluate that design before exposing a production host or a host containing sensitive workloads.

Limit local port exposure when appropriate

The documented mapping 3552:3552 publishes Arcane through the Docker host. If the Localtonet client runs on the same machine and no other local device needs direct access, Docker supports binding a published port to loopback:

ports:
  - '127.0.0.1:3552:3552'

This is a general Docker networking choice rather than an Arcane requirement. Use it only when the Localtonet client runs on the same host, because another device cannot reach a loopback-only listener. If the client runs elsewhere, retain a reachable host binding and enforce access with the host firewall and network policy.

Keep secrets out of public configuration

Do not place the Arcane encryption key, login credentials, Docker registry credentials, database password, Localtonet device token, or private endpoint details in screenshots or public examples. A Localtonet device token identifies the client device and must not be guessed, reused casually, or exposed.

Keep both products current

Arcane releases can include authentication, authorization, Docker-operation, backup, and general reliability changes. Review current release notes before updates, especially when the interface manages important workloads. Keep the Localtonet client current through the supported installation and update process for its operating system.

Expose the verified Arcane web UI with Localtonet

Once Arcane works locally and its initial credentials have been changed, create a Localtonet HTTP tunnel. HTTP is the appropriate family because Arcane presents a browser-based web application. A raw TCP tunnel is not needed for the normal web UI workflow.

HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. The exact options available can vary by current product configuration or plan. To avoid unsupported DNS assumptions, begin with an available generated address. If you later need a custom domain, verify its current DNS requirements in our documentation and dashboard.

For the current dashboard workflow, see our Localtonet HTTP tunnel documentation. Use the current values shown in the dashboard rather than copying a server code, domain option, or device token from an unrelated example.

Select the correct local target

Do not assume that localhost always refers to the Arcane host. It refers to the network context in which the Localtonet client runs. If the client itself is in a container, 127.0.0.1 normally refers to that client container, not automatically to the host or Arcane container. Use an explicitly tested route rather than guessing a container hostname or gateway address.

Verify the remote session safely

Test from a network path that is genuinely remote, such as a separate internet connection, rather than relying only on the same browser and LAN used for local setup. Confirm that the assigned HTTPS address loads Arcane, authentication is required, the old default password no longer works, and the replacement credential succeeds.

After verification, stop the tunnel whenever remote administration is not needed. Stopping a tunnel removes the public route while leaving Arcane running locally. Deleting it removes the tunnel configuration. These actions do not uninstall Arcane or delete its Docker volume.

Routine operation, updates, backups, and removal

Check status and logs

Run Compose commands from the directory containing the Arcane configuration:

docker compose ps
docker compose logs arcane

To follow new log output while reproducing a problem:

docker compose logs -f arcane

Avoid publishing complete logs without reviewing them. Logs may contain hostnames, paths, user identifiers, project names, image names, or other deployment details.

Stop and restart Arcane

To stop the Compose application while retaining its configuration and persistent volume:

docker compose down

Start it again with:

docker compose up -d

If Arcane is down, the Localtonet client may remain connected and the tunnel may remain marked as running, but the local target will not answer successfully. This is why tunnel status alone is not proof of application health.

Update the container image

The documented Compose example uses the latest image tag. Before updating a host that manages important workloads, review Arcane's current release information, protect application data, and account for any migration instructions. A standard Compose refresh for the configured image is:

docker compose pull
docker compose up -d

Verify the local sign-in and Docker dashboard again after the update. Then test the public address. This sequence identifies whether a regression is inside the application or only on the remote path.

Protect persistent data

The arcane-data volume contains Arcane's built-in SQLite database and other application data in the default setup. Compose project files live in the projects directory, not necessarily in that named volume. Optional exported volume backups can use /backups when configured.

A complete recovery plan must account for Arcane's persistent data, project files, any optional build or backup directories, external database data if PostgreSQL is used, and the encryption key. Test recovery procedures rather than assuming that the existence of a volume is equivalent to a usable backup.

Stop or delete remote access independently

Use the Localtonet dashboard to stop the tunnel when temporary remote work is complete. Arcane will remain available through its local address. Delete the tunnel if the public endpoint is no longer required. If the Localtonet client device is being retired, handle its device-specific token according to the current account workflow and do not transfer or expose it casually.

Uninstall Arcane

Arcane's recommended uninstall script asks before removing Arcane data, the Arcane user and group, or Docker:

curl -fsSL https://getarcane.app/uninstall.sh -o /tmp/arcane-uninstall.sh && sudo bash /tmp/arcane-uninstall.sh

Review downloaded administrative scripts before execution. Arcane also documents a noninteractive removal command:

curl -fsSL https://getarcane.app/uninstall.sh | sudo bash -s -- --force --remove-all

Troubleshoot Arcane and Localtonet systematically

Begin at the lowest layer and move outward. First confirm Docker, then the Arcane container, then local HTTP access, then connectivity from the Localtonet client, and finally the public tunnel. This avoids changing a correct tunnel to compensate for a failed container or incorrect local route.

The container starts but the browser cannot connect

Check docker compose ps and verify that port 3552 is published. Then test http://127.0.0.1:3552 on the host. If loopback works but another device cannot connect, investigate the port binding, host firewall, and LAN route. If loopback fails, inspect Arcane's logs and health before changing Localtonet.

The Localtonet client runs in a container

A container has its own network namespace. In that context, 127.0.0.1 points back to the Localtonet client container. It does not automatically point to the Docker host or the Arcane container. The correct target depends on the container network design. Because host gateway names and addresses differ by platform and configuration, this guide does not invent a universal value. Establish and test a reachable address from the client's actual network context.

Sign-in or redirect behavior differs through the public URL

First confirm that direct local sign-in still works. Then review the browser's exact URL and Arcane's current reverse-proxy and networking guidance. The installation example defines APP_URL=http://localhost:3552, but changing an application's canonical URL can affect redirects, cookies, callback URLs, or integrations. Do not guess a replacement value. Confirm the requirement against the current Arcane version and configuration documentation before modifying production settings.

The tunnel stopped after a reboot

Arcane's Compose configuration includes restart: unless-stopped, but that setting applies to the Arcane container, not automatically to the Localtonet client or tunnel. Confirm that the Localtonet client is running and connected after the reboot, and confirm that the tunnel itself is started. Container uptime and tunnel uptime are separate states.

Health checks fail during first startup

Arcane may run database migrations during its first boot. The documented health configuration includes a 15-second start_period so early failures do not immediately count against the retry limit. If failures continue beyond initialization, inspect the logs for a direct cause rather than indefinitely increasing health-check delays.

Frequently asked questions