# Daemon

###### Manage the long-lived `localcan` background process.

#### `start`

```sh
localcan start              # foreground (stays attached, logs to stderr)
localcan start --detach     # background (returns immediately)
localcan start -v           # verbose / debug logging
```

Foreground mode is convenient when you want to see daemon logs in your terminal, for example while debugging a tunnel that won't connect. Press Ctrl+C to stop. Detached mode is what you want most of the time on Linux servers.

> [!TIP]
> On macOS and Windows the bundled desktop app starts the daemon for you. Use `localcan start` from the terminal only after `localcan stop`, or when running a standalone install.

If a daemon is already running, `start` exits with an error. Use `restart` to replace the running instance.

On macOS and Windows the bundled desktop app starts the daemon automatically when it launches. You only need `localcan start` from the terminal if you've explicitly stopped it (`localcan stop`) or if you're running standalone.

#### `stop`

```sh
localcan stop
```

Tells the running daemon to shut down. Open tunnels close, the socket is removed, and the process exits.

#### `restart`

```sh
localcan restart            # foreground
localcan restart --detach   # background
```

Stops the running daemon (if any), waits for the socket to clean up, and starts a fresh one. Useful after a `localcan update` to start running the new binary.

#### `reload`

```sh
localcan reload
```

Tells the running daemon to re-read every file under `~/.localcan/projects/`. New project files are picked up, edited ones are re-applied, and removed ones are torn down, all without dropping connections to projects you didn't touch. This is the right command after editing YAML by hand.

#### `status`

```sh
localcan status
```

Prints daemon version, RPC protocol, project count, and the address it's listening on (a Unix socket path on macOS/Linux, a named pipe on Windows). When something needs attention (license updates expired, a newer CLI is available) `status` adds one line of guidance at the bottom.

```plaintext
Status     running
Version    1.0.0
Protocol   1
Projects   2
Address    /Users/you/.localcan/daemon.sock

CLI update available: 1.0.1 — run 'localcan update' to install
```

Pass `--json` to get the same data as a structured object for scripting.

#### Logs

Foreground daemons write to stderr. Detached daemons (and the bundled desktop daemon) discard stdout/stderr. To see what's happening, run `localcan stop && localcan start -v` in a terminal you can watch.