# Set Up Your Oysterun Host

Use this guide to install Oysterun for the first time, start your Host, and
open the Oysterun dashboard. By the end, you will have a Host password, a
project-folder boundary, a browser address for Oysterun, and an optional phone
pairing path.

## Before you install

Make sure you have:

- a macOS or Linux computer that will stay on while you use Oysterun;
- Node.js 20 or newer, with `npm` available in a normal terminal;
- a folder where your projects live, for the **Default Browse Root** question;
- a Host password that you can enter twice during setup; and
- outbound HTTPS access to `https://api.oysterun.com` for Managed connectivity.

If Managed connectivity is unavailable, setup still gives you a local
**Direct Host URL** for recovery on the same network. You can finish local
setup first and retry Managed connectivity later with `oysterun setup`.

## Install Oysterun for the first time

Open a normal terminal on the computer that will run the Oysterun Host, then
run:

```bash
npm install -g oysterun
oysterun
```

The first command installs the public Oysterun command. The second command
starts setup automatically when required Host settings are missing. You can
also reopen the wizard later with:

```bash
oysterun setup
```

## Complete the seven setup steps

The terminal shows seven clearly labelled steps.

### 1. Host name

Enter a name that helps you recognise this computer in Oysterun.

### 2. Project folders

Choose **Default Browse Root**, the folder that contains the projects you want
to find in Explorer. Choosing it does not start a Session. You choose a
separate **Start Folder** when you create a Session.

### 3. Host password

Enter the same Host password twice. Password input is hidden. The dashboard
sign-in page asks only for this password; there is no username field.

### 4. Managed connectivity

Oysterun connects the Host to its stable **Managed Endpoint**. You do not need
to provide a public IP address, open a router port, choose a DNS provider, or
enter a Cloud API token.

If the Managed Endpoint is not ready, setup keeps the same Host identity and
shows a pending state. The Direct Host URL remains available so you can
continue on the same network.

### 5. Help improve Oysterun?

Read the telemetry and privacy explanation, then choose whether to share daily
usage telemetry.

### 6. Phone app

Setup asks whether to show the Oysterun phone-app download link and QR code.
Choose yes if you want to prepare phone pairing, or no to continue directly to
starting the Host. The download link is `https://oysterun.com`.

### 7. Start Host

Setup asks whether to start the Host now. If this Browser Root already has a
running Oysterun Host, it asks whether to restart it and warns that live work
will be interrupted. Chat history remains, and supported Sessions can be
resumed from Sessions after restart.

When startup succeeds, setup prints the Direct Host URL, the Managed Endpoint
when it is ready, a login QR when available, and the next action. If you choose
not to start immediately, the terminal prints the command to use later.

## Open the dashboard

Open the Managed Endpoint or Direct Host URL printed by setup. The sign-in card
asks only for the Host password. Enter it and choose `Open Oysterun`.

![Oysterun password-only login card showing no username field.](assets/p121/f01/p121-f01-c16-password-only-login-card.png)

After sign-in, Oysterun opens on `Sessions`.

![Logged-in Oysterun Sessions landing with private origin and task history masked.](assets/p121/f01/p121-f01-c17-sessions-landing-masked.png)

If the password is wrong, the same card shows `Invalid credentials`. Re-enter
the Host password and choose `Open Oysterun` again.

![Oysterun password-only login card showing an invalid credentials error.](assets/p121/f01/p121-f01-c19-wrong-password-error.png)

The password-only flow also remains visible in a narrow phone-sized browser.

![Mobile-width Oysterun password-only login card.](assets/p121/f01/p121-f01-c20-mobile-password-only-login.png)

## Pair a phone or another device

When Managed connectivity is healthy, setup may show a Cloud onboarding QR.
If no onboarding QR is available, open the Managed Endpoint and sign in with
the Host password.

Direct setup can show a one-time QR for the local Host URL. The token in that
QR expires after 15 minutes. Treat it like a temporary password: do not post
it, save it in documentation, or send it to another person.

To create a fresh QR later, use the generate-login-QR action in Host
Preferences or run:

```bash
oysterun show-qr
```

In the phone app you can scan a QR, enter a Managed or Direct Host URL and
password manually, or open a saved Host.

## Recover when Managed connectivity is pending

Managed setup needs outbound HTTPS access to `https://api.oysterun.com`. If a
firewall, proxy, VPN, or network allowlist blocks that address:

1. Use the Direct Host URL on the same network.
2. Check diagnostics with `oysterun service:logs`.
3. Fix the network rule.
4. Run `oysterun setup` again.

The retry reuses the same Host identity instead of creating another one. The
Direct Host URL stays available while Managed connectivity is pending.

For an intentionally local-only setup, use:

```bash
oysterun setup --local
```

For the advanced Cloud-registered Direct path, use:

```bash
oysterun setup --enable-cloud-direct
```

Neither advanced option is required for the normal Managed setup.

## Keep Oysterun running

Use these commands to manage the Host service:

```bash
oysterun service:start
oysterun service:stop
oysterun service:restart
oysterun service:restart --restore-sessions
oysterun service:logs
oysterun show-qr
```

`oysterun service:restart --restore-sessions` prepares eligible Sessions for
resume before restarting. Work already in progress is marked interrupted and
is not replayed automatically.

If setup changes a setting that needs a restart, it tells you and offers the
restart action. It does not stop unrelated processes.

## Check connection settings

Host Preferences shows the read-only Managed Endpoint and current connection
state. Direct Host URL remains available as an advanced recovery setting.

When Managed access cannot complete, `Managed Tunnel Status` can show
`Disabled`, `Managed Relay Usage` can show `--`, and Direct access remains
available. Retry after the network prerequisite is fixed.

![Host Preferences Connection panel showing Direct Host access, Managed Tunnel Status disabled, and Managed Relay Usage unavailable with the task Host URL masked.](assets/p121/f01/p121-f01-c13-managed-status-direct-fallback-masked.png)

## Browser notification sound

Browser Notifications keeps web sound and app sound as separate preferences.
Changing a preference does not by itself prove browser permission or delivery;
use the visible notification actions to check those separately.

![Host Preferences Browser Notifications settings showing web sound enabled, app sound disabled, and notification actions visible.](assets/p121/f03/p121-f03-029-app-sound-toggle-masked.png)

## Check for updates

For a supported global npm installation, Host Preferences can show the current
version, selected update channel, `Check for updates`, and `Update now`.
Updates do not run automatically on startup.

When an update is available:

1. Choose `Check for updates`.
2. Choose `Update now`.
3. Review the target version and restart warning.
4. Confirm only when you are ready for the Host to restart.

The warning explains that live runtime Sessions and loops will close, chat
history remains, and supported Sessions can be resumed. Treat the update dialog
shown here as an example of the confirmation flow, not a public release announcement.

![Update confirmation dialog showing current and target versions, restore preparation warning, Cancel, and Confirm Update & Restart.](assets/p121/f03/p121-f03-024-update-confirmation-masked.png)

## Uninstall Oysterun

To remove the managed Host service while preserving the Default Browse Root,
agent folders, and other project data, run:

```bash
oysterun uninstall
```

To remove the saved Oysterun configuration as well, the command requires the
exact confirmation token:

```bash
oysterun uninstall --confirm DELETE
```

The uninstall command must not delete the configured Default Browse Root or
agent folders. Those project folders are preserved for intentional manual
removal only. macOS removes the launchd LaunchAgent and clears managed pid and
origin state. Linux has no launchd LaunchAgent; it still clears the managed
pid/origin state and reports that no launchd service existed.

To remove the globally installed command after uninstalling the Host, run:

```bash
npm uninstall -g oysterun
```