# Accounts and the portal

The optional portal lets you open an instance from [fluksio.com](https://fluksio.com),
including a pip installation with no local dashboard. The instance connects
outward over a WebSocket, so you do not need to open an inbound port.

Flows still run on your instance. The portal serves the interface and carries
API requests, responses and live updates through the connection.

## Connect an instance

1. Sign up or sign in at **fluksio.com**.
2. Open **Instances → Add instance** and copy the code.
3. On the machine running Fluksio, open another terminal in the same directory
   as `fluksio serve` and run:

    ```sh
    fluksio enroll <code>
    ```

The CLI uses `https://hub.fluksio.com` by default. If you started the engine
with `--data-dir` or `--global`, use the same option when enrolling. A running
engine picks up the connection automatically; otherwise start it with
`fluksio serve`.

From a local dashboard, you can instead use **Settings → Remote access**:
leave the default portal URL, paste the code, and press **Connect**.
Enrollment requires a superuser account.

The portal owner's sessions use the local account that enrolled the instance.
Check **Acting as** under Remote access. With several local superusers, the
CLI can choose one explicitly:

```sh
fluksio enroll <code> --as someone@example.com
```

A new valid code replaces an existing connection. An expired or invalid code
leaves the current connection intact. Once connected, open the instance from
the portal's **Instances** list.

## Let someone else in

Each person gets an ordinary local account, with no superuser rights. You can
admit them in either of these ways:

- Share an invitation link from the portal's **Instances** list.
- Ask them for a code from **Instances → Join an instance**. Enter it on your
  local instance under **Settings → Remote access → Add remote user**.

Their account appears under **Admin → Users** with a *Portal* badge. They
sign in through the portal rather than with a local password. Invitations are
time-limited; generate a fresh one if it expires.

## Manage or end remote access

**Settings → Remote access** shows the connection status and the latest
connection error. The instance needs outbound access to the portal, and any
proxy on that route must support WebSockets.

- To remove a person's access, remove them from the portal's sharing dialog
  or edit their account under **Admin → Users** and clear **Is active?**.
- To end all portal access from the instance, press **Disconnect**. This stops
  the connection and invalidates portal credentials locally, without requiring
  the portal to be online.
- To replace the pairing, use **Connect with a new code**. Remote users and
  panels may need to pair again.

Local sign-in and flows continue after disconnecting. Portal requests follow
the instance's normal account permissions, and the instance verifies portal
tokens against the public signing key pinned during enrollment.

## Custom portals

The CLI accepts another compatible portal with `--portal https://<portal-host>`;
the dashboard has the same URL field. HTTPS is required except for a portal on
loopback.

This public repository contains the instance and its connector. The portal
service is not included, so the Docker stack does not start one.

## See also

- [The fluksio command](../code/cli.md): data directories and enrollment options.
- [Dashboards and panels](dashboards.md): pair a wall screen through the portal.
- [Getting started](../getting-started/index.md): install and open your first instance.