Oysterun
Menu
繁中 EN
Back to Docs

Docs

Set up and understand your Oysterun Host

Complete the current supported Host setup, then use visible product state to distinguish the Host, a Session, its AgentFolder, its Agent ID, and a Website shared link.

On this page Article start

Set up one Oysterun Host on the computer that will run your work, open its dashboard, and then read each visible identity from the screen that owns it. A Host, Session, AgentFolder, Agent ID, and shared Website link can contain similar words without being interchangeable.

1. Prepare the computer and authority

Use a normal terminal as the same operating-system user who will run Oysterun. Before installing, prepare:

  • a supported macOS or Linux computer that can remain on while you use the Host;
  • Node.js 20 or newer and its matching npm command;
  • Claude Code or Codex installed and signed in for that same user if you want to start Sessions immediately;
  • one existing folder to use as Default Browse Root;
  • a new Host password that you can enter twice; and
  • outbound HTTPS access for normal Managed connectivity.

2. Install Oysterun and enter setup

Install the public Oysterun command, then run it:

npm install -g oysterun
oysterun

When required Host settings are missing or incomplete, oysterun enters setup automatically. To reopen the setup questions later, use:

oysterun setup

Before step 1, Oysterun checks whether Claude or Codex is available. If neither is found, it shows Continue setup without an agent provider?

  • Choose No, or press Enter for the default No, to stop safely. The terminal should end with Installation cancelled; no changes were made.
  • Choose Yes only when you intentionally want to configure the Host before installing a provider. The Host can be set up, but new Sessions still require Claude Code or Codex for the same operating-system user.

3. Complete the setup steps that appear

Complete task-owned terminal setup checkpoint with the oysterun setup command, numbered Host name and Project folders context, provider preflight, and the Start Oysterun Host now question visible without password input or shell history.
Setup checkpoint: the real oysterun setup flow shows its numbered context from Host name and Project folders through provider detection and the step 7 Start Host question; no password input or unrelated shell history is visible.
Inspect full-size screenshot

1. Host name

At Name this Host, enter a recognizable display name for this computer. It identifies the Host in product lists; it is not a Session Name or Agent ID.

2. Project folders

Choose an existing Default Browse Root. This is the Host’s project-discovery boundary and does not start a Session. It seeds Start Folder when a new Session has no explicit folder, so confirm or change the visible Start Folder in Session Setup before you start that Session.

3. Host password

Create and confirm the password. Input is hidden. The dashboard sign-in form asks for this Host password without a username field.

4. Managed connectivity

Oysterun registers or resumes this Host and allocates or reuses its stable Managed Endpoint. Normal setup does not ask you for a public IP, router port, domain, third-party tunnel, or Cloud token.

5. Help improve Oysterun?

Read the daily aggregate-report explanation and choose whether to send it. This consent does not change the Host, Session, or folder identity.

6. Phone app

Normal interactive setup asks Show phone app download link and QR code? Choose No, the default, to continue to step 7 without showing them. Choose Yes only when you want the download link and QR. Phone pairing is not required to finish the Host and web dashboard setup.

7. Start Host

For a new managed service, choose whether to start the Host now. If a managed Host is already running, the prompt becomes Restart Oysterun Host now?; stop unless the exact restart is currently authorized. A successful start may open the dashboard automatically.

4. Confirm that the intended Host is ready

Complete task-owned setup terminal after a successful Host start, with Oysterun Host is running, Managed Tunnel is ready, the Managed Endpoint, and the local Host URL visible together.
Ready checkpoint: the same setup run finishes with the task-owned Host running, a ready Managed Tunnel and Managed Endpoint, and the Direct/local fallback URL visible in one terminal frame.
Inspect full-size screenshot
  1. After a successful Managed start, find Managed Tunnel is ready and the printed Managed Endpoint. Setup also prints a local or Direct Host URL.
  2. Open the Managed Endpoint when it is ready. On the same trusted network, the Direct Host URL is the bounded fallback while Managed provisioning is pending.
  3. Enter the Host password and choose Open Oysterun.
  4. Wait for Sessions and confirm Connected.
  5. Open the Oysterun menu, choose Host Preferences, and find Host Identity And Browse Root. Confirm Host Display Name and Default Browse Root match setup.

If you deliberately chose not to start in step 7, the supported explicit start command is oysterun service:start. Run it only when starting that configured Host is authorized.

5. Keep the five visible identities separate

Full Host Preferences identity view for the connected task-owned Direct Host, showing Host Display Name, the complete short Default Browse Root, Active Config File, and the Claude Code default runtime.
Host identity checkpoint: Host Preferences identifies P131 A-P05 Host, keeps Connected and Direct Host context visible, and shows the complete macOS-resolved task root /private/tmp/p131-a5 with its folder control and default runtime.
Inspect full-size screenshot

Host

The Oysterun service on one computer. Read its Host Display Name, Default Browse Root, and connection addresses in Host Preferences. An endpoint opens this Host; it is not a Session or a public Website link.

Session

One conversation and provider runtime on that Host. The human-facing Session Name appears in Sessions and Chat. Its exact immutable Session ID appears in Session Profile.

AgentFolder

The exact working folder selected as Start Folder and later shown as Working Directory. It owns the Session’s files. One folder can be used by more than one Session; that does not merge those Sessions.

Agent ID

A visible grouping and attribution label entered in Session Setup and shown in Session Profile. It does not choose the folder, replace the Session ID, identify the Host, or form a Website URL.

The URL copied with Website Copy link or the Website browser’s Copy browser link. Its /sites/…/ route points to the Website resolved from the project folder. Do not invent it from Agent ID, Session Name, or Session ID.

6. Create one Session and read its identity back

Complete Session Setup for the connected task-owned Direct Host, showing Agent ID p131-a5-agent, Session Name P131 A5 Identity, the full Start Folder /tmp/p131-a5, and Claude selected as Agent Runtime.
Session Setup checkpoint: the new P131 A5 Identity Session has Agent ID p131-a5-agent, full Start Folder /tmp/p131-a5, and Claude selected, while the header confirms the connected Direct Host.
Inspect full-size screenshot
Complete Session Profile identity for P131 A5 Identity, showing its Agent ID, separate Session ID, full macOS-resolved Working Directory, and matching Workspace Policy Root.
Session Profile checkpoint: the same P131 A5 Identity Session shows Agent ID p131-a5-agent, its separate generated Session ID, and the complete macOS-resolved Working Directory and Workspace Policy Root /private/tmp/p131-a5.
Inspect full-size screenshot
  1. From Sessions, choose New Session.
  2. In Session Setup, enter a recognizable Agent ID and a unique Session Name.
  3. Choose the intended Start Folder. Do not assume it is the entire Default Browse Root.
  4. Review the available provider settings, then choose Start Session.
  5. When Chat opens, choose the top-bar Open Session Profile control for that live Session.
  6. Compare Agent ID with your entry, Working Directory with the chosen Start Folder, and note that Session ID is a separate generated value.

Visible checkpoint: the Chat top bar exposes Open Session Profile only for the current live Session; the profile then shows the Agent ID, Working Directory, and separate Session ID used for this comparison.

Checkpoint: the Host contains the Session; the Session uses the AgentFolder; Agent ID labels attribution; and Session ID still identifies the exact Session. Matching text never makes them the same authority.

Complete task-owned Website row for p128-website-folder, showing Ready and Available states, the /sites/p128-website-folder/ route, the copy control, and its visible copied-link result.
Shared-link checkpoint: the task-owned p128-website-folder row is Ready and Available at /sites/p128-website-folder/; its copy control has produced the visible “Copied link for p128-website-folder” result.
Inspect full-size screenshot
  1. Continue only if the intended folder has an enabled Website and appears on the Website surface.
  2. Confirm that the Website row shows the intended folder and a visible /sites/…/ entry path.
  3. Choose Copy link, or open the Website and choose Copy browser link.
  4. Open the copied URL as the intended audience and confirm that it shows the Website for that folder.

If the Website row is absent, unavailable, or belongs to another folder, stop. Do not substitute the Host endpoint, Agent ID, Session Name, Session ID, or a local file path as a shared link.

Recover safely and know when to stop

  • No provider is detected: cancel with the default No for a no-change result, or continue knowingly and install/sign in to Claude Code or Codex for the Host’s operating-system user before creating a Session.
  • Managed connectivity remains pending: use Direct access only on the same trusted network, then rerun setup after the network prerequisite is fixed. Do not reset the Host identity.
  • Setup asks to restart an existing Host: stop without current permission for that exact Host and action. Do not replace it with a service or terminal restart from this guide.
  • Host Display Name or Default Browse Root is wrong: stop before starting a Session. Correct the visible Host Preferences value and choose Save, or use Reset/Reload before saving when you need to discard or reread the draft; do not edit hidden configuration.
  • Agent ID or Working Directory is wrong: stop before relying on the Session for attribution or files. Return to Sessions and create the intended Session through Session Setup; do not rewrite a Website route or private record to disguise the mismatch.
  • No valid Website link is visible: no shared Website identity has been proved. Return to the intended Website row and resolve its visible availability instead of constructing a link.

Safe stop: ordinary work begins only after the intended Host is Connected, its Host Preferences match setup, the Session Profile matches the chosen AgentFolder and Agent ID, and every shared link resolves to the intended folder-owned Website.