Overview

The localcan binary is both a long-lived background daemon and a thin client that talks to it — same executable, different invocations.

Daemon and client

When you run localcan start, the binary runs the daemon: it loads your projects from ~/.localcan/, terminates HTTPS, opens tunnels (Public URLs), and serves traffic. Every other command (status, tunnel ls, license activate, …) is a short-lived client that connects to the running daemon over a local socket and exits as soon as the call returns.

You don't need to think about this most of the time — quick-tunnel commands like localcan http 3000 auto-spawn the daemon for you. But it explains a few things you'll notice:

  • localcan stop kills the daemon. After that, client commands will print "Daemon is not running. Start with: localcan start".
  • Editing files in ~/.localcan/projects/ does not take effect until you run localcan reload (or restart the daemon).
  • Running two instances of the daemon at once is not allowed. The second one fails to bind the socket.

Free mode

LocalCan works without a license key. In free mode the daemon serves .local domains over the HTTP/HTTPS proxy with full request inspection. Public URLs and TCP tunnels require activation.

That means localcan http 3000 and localcan https 3000 work out of the box, publishing a .local URL like swift-falcon.local for your local network. To open a Public URL (or to use localcan tcp), run localcan license activate <key>.

If a license becomes invalid mid-session, LocalCan does not exit. It drops to free mode automatically, the public tunnel goes down, and the .local proxy keeps serving. Re-activate and the tunnel comes back without restarting the daemon.

The first engine command (start, http, https, tcp, restart) asks you to accept the Terms of Service↗. On a headless host or in a script, run localcan accept-terms first (or pass --accept-terms). Free mode never asks about usage data, telemetry is opt-in. See License for the full flow.

Bundled vs standalone

The same binary ships in two shapes:

  • Bundled — packaged inside the LocalCan desktop app on macOS and Windows. The desktop app starts the daemon for you, and updates flow through the desktop app's auto-updater. localcan update is a no-op in this mode.
  • Standalone — installed by itself on Linux. localcan update downloads and replaces the binary in place. You handle daemon lifecycle yourself. macOS and Windows ship bundled-only today. A standalone build for those platforms may come later.

Run localcan version to see which one you have and what version of the daemon is running.

Where state lives

Everything LocalCan persists is under ~/.localcan/:

Text
~/.localcan/
  config.yml         # daemon-wide settings (license key, proxy ports, inspector limits)
  projects/          # one YAML file per project — see Configuration → Projects
  certs/             # generated TLS certificates for local domains
  daemon.sock        # macOS/Linux RPC socket (Windows uses a named pipe)

Run localcan config path to print the directory.

Scripting

Most commands accept --json (or --output json) and emit machine-readable output instead of human-formatted tables — useful for piping into jq, CI scripts, or your own tooling.

Shell
localcan tunnel ls --json | jq '.[] | .tunnel_url'

Next steps

© 2026 LocalCan™. All rights reserved.