Oysterun
繁中 EN

Getting Started

Go from Host readiness to one useful Session.

Follow one phone-first path while keeping the Host identity, browser path, selected folder, and finished response explicit.

Oysterun is Beta software. Provider, operating-system, and Host support depends on the current configuration; this path proves only the choices you verify now and is not a roadmap promise.

  1. Install Oysterun Host

    Prerequisites: Ubuntu 22.04+ with Bash, or macOS with Bash or zsh. Download requires curl. On Ubuntu, direct root can run apt-get update && apt-get install -y curl; an ordinary administrator can run sudo apt-get update && sudo apt-get install -y curl. macOS normally includes /usr/bin/curl; if it is missing, stop and restore it through macOS Software Update or Apple Support. Use administrator access only for these bounded prerequisites or when the installer explicitly requests it.

    The installer checks Node.js and npm in the target-user context, keeps Node.js 22, and replaces a missing or different major runtime with Node.js 22 where supported. On macOS without Homebrew it stops before mutation and directs you to the official Node.js installer. Never use sudo npm install -g oysterun.

    macOS

    The installer retains the current macOS user. It uses existing Homebrew for an old Node.js runtime, or stops before mutation with official Node.js guidance when Homebrew is absent.

    Download, inspect, and run

    curl -fsSL https://oysterun.com/install.sh | bash

    Expected result: $HOME/.local/npm

    Linux (Ubuntu)

    An ordinary or sudo launch retains the original user. Only a direct-root Linux server creates or reuses the dedicated oysterun user.

    Download, inspect, and run

    curl -fsSL https://oysterun.com/install.sh | bash

    Expected result: $HOME (direct-root: /home/oysterun); $HOME/.local/npm

    Next: connect a phone or browser

    After setup finishes and status is healthy, download the Oysterun iOS app and scan the fresh QR shown by this Host. Or open the same Host URL in an ordinary browser and sign in with the current Host password. Treat the QR and bootstrap token like a temporary password: do not save or publish them.

    Download the Oysterun iOS app

  2. Complete guided Host setup

    The universal installer opens oysterun after installation, and missing configuration starts the guided setup automatically. Reopen it later with oysterun setup. Complete the seven guided choices: Host name, Default Browse Root, Host password, Managed connectivity, telemetry and privacy, phone app, and Start Host.

  3. Confirm the Host started successfully

    Wait for setup to report that the intended Host is running, then record its current URL and generate a fresh QR only if you will connect a phone. If setup reports an error or the Host identity differs from your choices, resolve that result before continuing. A successful install alone does not prove that Host setup completed.

  4. Optionally prepare a Session provider

    A provider is not required to install and configure the Host. To create Sessions, choose any provider currently shown as supported, install and authenticate it for the same operating-system user, and confirm its readiness. No single provider is mandatory. Resolve any login, trust, model, or readiness warning before starting a Session.

  5. Open the same Host from phone and browser

    On the phone, scan the fresh QR generated after Host success or enter the exact shown Host URL and current Host password. In an ordinary browser, open the same exact Host URL. The phone and browser are two Clients for one Host identity and the same Session state, not two Hosts. Stop if either Client shows a different Host identity, unexpected address, or security warning.

  6. Enter through the current sign-in path

    Use the Host's current password-only sign-in screen; device pairing and notification permission do not replace Host authentication. The visible success checkpoint is the locale-independent Sessions destination for the Host you just matched. A reachable page proves the route only, not that a provider Session can finish work.

  7. Create one bounded provider Session

    From Sessions, open a new Session Setup, choose a provider only while its readiness state is current, set a recognizable Agent ID and Session Name, and select the exact Start Folder. Start the Session, then send this reviewed prompt: Read only the current folder. Reply with the folder name and one sentence describing what it contains. Do not edit, create, delete, move, rename, or execute any file. Stop if the selected provider or folder differs from what you reviewed.

  8. Wait for the completed response

    Connected, a reachable chat, or a Working indicator is not a completed answer. Wait until the working state clears and the provider's final response is visible. The bounded checkpoint is a response that names the selected folder and describes its current contents without asking to change them; a login, approval, tool, or readiness warning and a still-working turn are nonterminal stop states.

  9. Recognize and return to the Session

    Record the Session Name and stable identity shown by Oysterun. Leave the chat, return to Sessions, and open that same row; confirm the same Agent ID, exact folder, and prior response before continuing. This is the return path to the existing Session—do not create a duplicate when the recognized Session is already available.