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.

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.