# 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.

#### Unlicensed

LocalCan works without a license key. Unlicensed, the daemon serves `.local` domains over the HTTP/HTTPS proxy with full request inspection. Public URLs and TCP tunnels require activation. To open a Public URL without paying, sign up for the [Free plan](https://www.localcan.com/dashboard/get-started?plan=free) and activate the key it issues.

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 unlicensed automatically, the tunnel goes down, and the `.local` proxy keeps serving. Re-activate and the tunnel comes back without restarting the daemon.

#### First-run consent

The first engine command (`start`, `http`, `https`, `tcp`, `restart`) asks you to accept the [Terms of Service](https://www.localcan.com/terms). On a headless host or in a script, run `localcan accept-terms` first (or pass `--accept-terms`). Without a license the app never asks about usage data, telemetry is opt-in. See [License](/docs/cli/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/`:

```plaintext
~/.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.

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

#### Next steps

- [Quick start](/docs/cli/quick-start): activate a license and open your first tunnel.
- [Quick tunnels](/docs/cli/quick-tunnels): `localcan http`, `localcan https`, `localcan tcp`.
- [Traffic](/docs/cli/traffic): read captured traffic from the command line.
- [Snapshots](/docs/public-urls/snapshots): publish a static copy of your app that stays up at its Public URL while you're offline.
- [Access control](/docs/public-urls/access-control): password-protect a Public URL so only people who have the password can open it.
- [Comments](/docs/public-urls/comments): read and answer the review comments reviewers leave on a Snapshot, from the terminal.
- [AI agents](/docs/ai-agents/overview): let an AI assistant read your traffic, manage your Public URLs, and publish Snapshots over MCP.
- [Reference](/docs/cli/reference): full command listing.