# Connect The Oysterun App To Your Host

This guide helps you sign in from the Oysterun app without mixing up the Host
password, Cloud pairing, and browser login. By the end, the app should open
your Host and show the same Sessions screen you see in the Host dashboard.

## Prerequisites

Before you start, make sure you have:

- an Oysterun Host that has completed setup and is running;
- the Host password, or a one-time setup QR/bootstrap code shown by your Host;
- network access from the app device to the Host through the shown Direct Host
  address or through the available Cloud-assisted pairing path; and
- the Oysterun app installed on the device you want to pair.

Start from the Host setup screen or the Host dashboard screen that shows the
Host connection details. If setup is still running, finish the setup prompts
first and keep the terminal or dashboard open until it shows the Host is ready.

## Start From The Host Connection Details

1. On the Host, find the connection details shown after setup or in the Host
   dashboard. The normal first connection path shows a Direct Host URL and, when
   available, a QR or bootstrap option.
2. On the device, open the Oysterun app.
3. Choose the app's Host connection option. Use the QR/bootstrap path if the
   Host shows one. If you enter the Host manually, type the Host URL exactly as
   shown by the Host.

You should see the app move to the Host sign-in step instead of asking for a
Cloud account password. Oysterun keeps Host product login separate from the
device's app installation identity.

## Sign In To The Host

1. Enter the Host password when the app asks for Host login.
2. Submit the sign-in form.
3. If the app asks for notification permission, choose the option that matches
   how you want to receive alerts. Notification permission is separate from Host
   sign-in.

The visible success checkpoint is the Sessions page. You should be able to see
the Host's Sessions screen after sign-in. If notifications are enabled, later
notifications can return you to the saved Host and focus the related Session or
message when the Host is reachable.

## Check What Is Connected

After sign-in, use these visible checks:

- The app opens the Host instead of a generic Cloud account page.
- The Host dashboard and the app agree on the Host you connected to.
- Manual Host URL entry preserves explicit `http://` or `https://` schemes.
- A bare IP address or `localhost` uses `http://` and port `8802` when no port
  is entered.
- A bare domain without a port uses `https://`.
- A domain with a port asks you to add `http://` or `https://` so the scheme is
  explicit.
- Email-like input is rejected as an email address, not treated as a Host URL.
- The normalized Host entry exposes a Health URL ending in `/health` with a
  copy control so you can test Host reachability in a browser.

## Recover If Sign-In Or Pairing Fails

If the app cannot reach the Host, first copy the Health URL and open it in a
browser on the same device. If the browser cannot reach it either, check that
the Host is running, that the device is on the right network, and that the Host
URL includes the correct scheme and port.

If the password is rejected, use the current Host password. App installation
identity and notification permission do not replace Host product login.

If QR or bootstrap pairing has expired, return to the Host setup or dashboard
and use the current connection details. Do not reuse an old screenshot of a QR
or one-time code.

If notifications do not arrive, keep using the app through the Host connection
while you check device notification permission and network reachability.
Notification delivery is a separate checkpoint from the successful Host
sign-in.

## What Oysterun Keeps Separate

Oysterun separates these identities so recovery stays clear:

- Host product login: the Host password or a current one-time QR/bootstrap
  token.
- App installation identity: the app's device pairing identity, used for Cloud
  pairing and notification registration.
- Cloud notification delivery: the path that lets the Host ask Oysterun Cloud
  to deliver a bounded notification to paired app installations.

The app installation identity is not a Host password. Host Cloud pairing does
not make the Cloud password field editable in Host Preferences, and the app
should not hard-code a review or deployment Host URL into the login screen.

Older Hosts may be normalized during startup so Cloud identity material is kept
separate from ordinary Host preferences. For normal users, the important
visible result is simple: Host Preferences keeps user-editable Host settings,
while Cloud pairing and notification identity stay out of the editable
preference fields.