# 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](/docs/public-urls/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](/docs/sso/overview) 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](https://www.localcan.com/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](/docs/access/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](https://www.localcan.com/terms). The app's upstream is its address as seen from this server, such as `http://localhost:3000`.

To check the connector, see [Troubleshooting](/docs/access/troubleshooting#the-connector). 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](/docs/access/sign-in-methods).

#### 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](/docs/access/identity-header#grafana) and apps that verify the [identity header](/docs/access/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](/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](mailto:support@localcan.com).

