Quick start


LocalCan Access puts company sign-in in front of a web app on your own server, such as Metabase, Grafana, n8n, Umami or a tool your team built. People sign in with Google, Microsoft, GitHub or your own identity provider, and they install nothing.

The app stays where it runs. A small connector next to it holds the only connection to LocalCan, and one CNAME record points a hostname on your own domain at LocalCan. Everyone who opens that hostname signs in first, and only the people your rules allow get through.

LocalCan Access is in preview.

NOTE

Three features share a name. LocalCan Access protects a tool on a server for your team. Access control protects a Public URL (also called a tunnel) to your own machine with a password, a secret link or IP rules. SSO & SCIM is how your team signs in to LocalCan itself.

Before you start

  • LocalCan Access on the team. The team owner adds it in the dashboard↗ under Billing: Buy LocalCan Access on the Free plan, or Add LocalCan Access on a paid plan. It comes in three tiers: Starter (3 apps), Growth (10 apps) and Scale (30 apps). Before that, you can set up 3 apps, but they let nobody in, and the Apps page shows them as Blocked. During a trial, you can add LocalCan Access once your plan is paid. A team that has it included during the preview sees Included during the preview under Billing, with nothing to buy.
  • An owner or admin account with two-factor sign-in. Changes to LocalCan Access need two-factor sign-in on your account. Turn it on under Account Settings → Security.
  • A Linux server that reaches the app, with Docker or systemd.
  • A hostname on a domain you control, such as metabase.example.com, and access to its DNS records.

1. Add the app

In the dashboard, open LocalCan Access → Apps and select Add app:

  • Preset: Your own app, Metabase OSS, Umami, Grafana or n8n. A preset fills in the upstream and the public paths the tool needs. You can change both later.
  • Name and Hostname: the app's name in the dashboard, and the address people will open, on your own domain.
  • Upstream (as the connector reaches it): the app's address from the connector's side, such as http://metabase:3000 on a shared Docker network, or http://localhost:3000 on the same machine.
  • Connector: for your first app, choose New connector on this server and name the server. Later apps on the same server choose that connector. One connector serves every app on its server.

Creating the app shows the connector key once. Copy it before you close the dialog. A lost key can't be shown again: select Rotate key in the connector's menu on the Connectors page instead, and the connector that still runs with the old key stops within 5 minutes.

2. Run the connector

Keep the key in a file only the connector can read. The connector also accepts the key in the LOCALCAN_CONNECTOR_KEY environment variable, but a key passed that way ends up in your shell history and in docker inspect.

Docker

Save the key in a file. The connector image runs as user 65532, so the file belongs to that user:

Bash
sudo install -d -m 0755 /etc/localcan
sudo install -m 0400 -o 65532 -g 65532 /dev/stdin /etc/localcan/connector.key
# paste the key, press Enter, then Ctrl-D

Run the connector on the Docker network your app is on, so it reaches the app's upstream:

Bash
docker run -d --name localcan-connector --restart unless-stopped \
  --network <your app's network> \
  -v localcan-connector:/data \
  -v /etc/localcan/connector.key:/run/secrets/connector_key:ro \
  -e LOCALCAN_CONNECTOR_KEY_FILE=/run/secrets/connector_key \
  ghcr.io/localcan/connector:1
Docker Compose

Save the key in a file as above, then add the connector to your app's Compose file, so it shares the app's network:

YAML
services:
  localcan-connector:
    image: ghcr.io/localcan/connector:1
    restart: unless-stopped
    environment:
      LOCALCAN_CONNECTOR_KEY_FILE: /run/secrets/connector_key
    secrets:
      - connector_key
    volumes:
      - localcan-connector:/data

secrets:
  connector_key:
    file: /etc/localcan/connector.key

volumes:
  localcan-connector:

The image is built for linux/amd64 and linux/arm64. The :1 tag follows the latest 1.x release.

systemd

On a Linux server, as root. The installer adds the localcan command, a localcan system user and the localcan-connector service, then you save the key and start it:

Bash
curl -fsSL https://localcan.com/install.sh | sudo sh -s -- --service systemd
sudo install -m 0600 -o localcan -g localcan /dev/stdin /etc/localcan/connector.key
# paste the key, press Enter, then Ctrl-D
sudo systemctl start localcan-connector

Installing the service accepts the Terms of Service↗. The app's upstream is its address as seen from this server, such as http://localhost:3000.

To check the connector, see Troubleshooting. It reports active once it is connected.

3. Point the hostname at LocalCan

Open the app in the dashboard. Its Domain section shows a CNAME target that ends in .cname.localcan.dev. At your DNS provider, add a CNAME record from your hostname to that target. A CNAME of your own in between is fine, as long as the chain ends at that target.

Once the CNAME resolves and the connector is connected, LocalCan gets a certificate for the hostname from Let's Encrypt. Until it has one, browsers show a TLS error on that hostname for a few minutes. If the hostname already serves something, lower its DNS TTL well before you switch, and switch at a quiet hour.

An app whose hostname never gets a certificate is removed 14 days after you created it.

4. Choose who may sign in

A new app lets nobody in. Open the app and add rules under Who may sign in, for example your company's Google Workspace domain or a list of email addresses. See Sign-in methods and rules.

5. Open the app

Open the hostname in a browser. LocalCan sends you to your sign-in method and back. The first time someone signs in to an app with Google, Microsoft or GitHub, a LocalCan page shows them what the team will see and asks them to continue.

Grafana and apps that verify the identity header sign people in from it, so there is no second login. Metabase, Umami and n8n keep their own login behind LocalCan Access.

Close the other ways in

LocalCan Access protects the traffic that arrives through the hostname. Close every other way to reach the app from the internet, such as a published port or a reverse proxy that still answers for another name.

Update the connector

The connector doesn't update itself. Its menu on the Connectors page shows the version it last connected with, and the changelog lists each release.

With Docker, pull the new image and remove the container, then start it again with the docker run command from step 2:

Bash
docker pull ghcr.io/localcan/connector:1
docker rm -f localcan-connector

With Docker Compose:

Bash
docker compose pull localcan-connector
docker compose up -d localcan-connector

With systemd, run the installer again. It keeps the key, and restarts the service only if it was running:

Bash
curl -fsSL https://localcan.com/install.sh | sudo sh -s -- --service systemd

The connector keeps its identity in the localcan-connector volume, or in /var/lib/localcan-connector with systemd. An updated connector that comes back from the same IP address counts as a restart, not a takeover. Its apps are unavailable for a few seconds while it restarts.

The localcan update command doesn't update a connector.

Change the tier or remove LocalCan Access

The team owner does both under Billing, from the Manage menu on the LocalCan Access row:

  • Change tier moves to another tier. A smaller tier keeps every app working, but you can't add an app until you're under its limit.
  • Remove LocalCan Access ends it at once and credits the unused time to future invoices. Your apps stay set up but stop serving.

On the Free plan, Cancel LocalCan Access ends it at the end of the billing period. Cancelling a paid plan ends LocalCan Access with it, and the apps are removed 30 days later unless you reactivate.

While a subscription includes LocalCan Access, switching between monthly and yearly billing, moving to a smaller plan, or moving a Free team to a paid plan goes through support@localcan.com↗.

© 2026 LocalCan™. All rights reserved.