Overview

LocalCan keeps everything it persists in ~/.localcan/. The desktop UI and the CLI both read and write the same files.

Layout

~/.localcan/
  config.yml         # daemon-wide settings (license, proxy ports, inspector limits)
  projects/          # one file per project — see Projects
    my-app.yml
    api.yml
    _quick_http_3000_8a3f.yml   # transient, written by `localcan http`
  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.

One file per project

Each YAML file under projects/ is a single project. The project ID is the filename without .yml:

projects/my-app.yml      → project "my-app"
projects/team-api.yml    → project "team-api"

Project IDs must be alphanumeric (plus -, _, .). The _ext_ prefix is reserved, and _quick_*.yml files are managed by the quick tunnel commands — don't edit them by hand.

Hot-reload

The daemon does not watch the filesystem. After you add, edit, or delete a file under projects/, run:

localcan reload

The reload is non-disruptive: only projects that actually changed get rebuilt. Tunnels you didn't touch keep their connections.

Version control

Every file under projects/ is plain YAML and safe to commit — checking ~/.localcan/projects/<id>.yml into a dotfiles repo or copying it from a private one is the pragmatic path today. A dedicated "external project" mechanism that lets you keep project files inside your app's own repo and point LocalCan at them is in development for a future release.

Reference

• Daemon config — every key in config.yml.
• Projects — every key in projects/<id>.yml.
• Headers — header rewriting in detail.
• Basic auth — protecting endpoints with a password.