# Set up Oysterun step by step

This guide takes you from a new Oysterun installation to one useful result:

- A **Host** is the Oysterun service on your own computer or server.
- A **Session** is a working conversation in one project folder.
- An **Agent** is the AI assistant that works in that project folder.
- A **Provider**—Codex, Claude Code, Grok, Antigravity, or OpenCode—runs the Agent.
- **Oysterun Mail** is the product inbox where Agents can deliver reports.

You need one Mac or Ubuntu computer, a browser, and an iPhone for the App. Install only one Provider to begin.

## Check the requirements {#requirements}

The computer that runs the Oysterun Host needs:

- macOS (`sw_vers -productVersion`), or Ubuntu 22.04 or newer (`lsb_release -ds`);
- one processor core (vCPU); check with `getconf _NPROCESSORS_ONLN`;
- 2 GB of memory, or 1 GB plus about 2 GB of swap (Linux shows it as 2 GiB); swap is disk space used when memory is full, and Ubuntu shows it with `free -h`;
- 10 GB of disk space, with at least 2 GiB free during an update; and
- an internet connection for installation, sign-in, and Managed connectivity—the technology that lets you reach the Host from outside without a fixed IP address. Open `https://oysterun.com` to check the connection.

Check disk space with `df -h .`. Node.js runs Oysterun, and npm installs its package; `node -v && npm -v` checks both. The installer handles Node.js 22 on supported systems. On macOS, Homebrew is a package manager (`brew --version` checks it); if both Node.js 22 and Homebrew are missing, the installer stops and points to the official Node.js installer.

### Add Linux swap (only if memory is low) {#add-linux-swap}

If a Linux Host has only 1 GB of memory, it needs at least 2 GiB of swap—disk space used temporarily as memory. If you are not comfortable with terminal administration commands, ask the person who manages the computer. First inspect the current state:

```bash
free -h
swapon --show
```

`/swapfile` is the file that provides swap. `/etc/fstab` records disks and swap that start at boot. If `/swapfile` already exists but is not listed by `swapon --show`, stop and inspect both instead of overwriting it. If it does not exist, an administrator can create it with:

```bash
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
grep -qF '/swapfile none swap sw 0 0' /etc/fstab || echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h
swapon --show
```

Oysterun does not create swap automatically because that requires administrator access.

Success means `swapon --show` lists `/swapfile` at about 2G and the `free -h` **Swap** row shows about 2.0Gi. If a command fails or the result differs, stop: do not repeat the commands or overwrite an existing swap file. Ask the computer administrator or Ubuntu support to inspect `/swapfile` and `/etc/fstab`.

## Install Oysterun {#install-oysterun-host}

Run the installer as the same operating-system user who will run the Host and Provider. The CLI is Oysterun's terminal command, and the npm prefix is the user-owned folder where npm installs that command. Do not use `sudo npm install -g oysterun`.

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

The installer selects the current Oysterun release, installs the CLI under the current user's local npm prefix, and opens guided Host Setup when configuration is missing.

The installer identifies the selected release and prepared package before it opens Setup:

```terminal
  ✓ Oysterun release selected: [current version] ([release channel])
  ✓ Package prepared: [current version]; running Host qualification follows onboarding.
```

A **release channel** is the release track; **Beta** is the current test release. **Onboarding** is the guided Setup you complete next. **Host qualification follows onboarding** means Oysterun checks the Host after Setup.

Success means the package is prepared and guided Setup opens. If it fails, check that the download works, the current user can write to the shown npm prefix, and the OS is supported. If installation succeeds but Setup does not open, run `oysterun setup` as the same user.

## Complete Host Setup {#host-setup}

Setup does not require a Provider. The terminal labels the seven steps and uses this wording:

1. **Host name** — **Name this Host** defaults to `oysterun-<computer name>`. Press Enter to accept it, or type another recognizable name.
2. **Project folders** — **Default Browse Root** defaults to `~/OysterunAgents`. Press Enter to accept the recommended folder, and keep your project folders inside it.
3. **Host password** — set the password used by the browser and App.
4. **Managed connectivity** — Setup registers the Host and allocates its Oysterun Managed Endpoint, the Host's own address for reaching it from outside without a fixed IP address.
5. **Help improve Oysterun?** — **daily telemetry** sends Oysterun one daily count of feature usage to improve the product. It contains feature-use counts only—no conversation content, files, or passwords. It is optional: answer **Enable daily telemetry?**, and change it later in **Host Preferences** if needed.
6. **Phone app** — answer **Show phone app download link and QR code?** if you are ready to pair the App. A QR code is a square pattern the phone camera can scan.
7. **Start Host** — Setup installs and starts the Host service. On Ubuntu, it also reports whether the Host will start automatically after the server restarts.

Setup shows prompts like these. Values in brackets come from your computer or choices:

```terminal
[1/7] Host name
? Name this Host [oysterun-<computer name>]:

[2/7] Project folders
Default Browse Root [~/OysterunAgents]:

[3/7] Host password

[4/7] Managed connectivity
  Registering with backend at https://api.oysterun.com...
  Allocating Oysterun Managed Endpoint...

[5/7] Help improve Oysterun?
? Enable daily telemetry? (Y/n)

  ✓ Cloud registration complete
  Oysterun Managed Endpoint: [your Host URL]

[6/7] Phone app
? Show phone app download link and QR code? (y/N)

[7/7] Start Host
  Installing LaunchAgent and starting Oysterun Host ([Host name])...
  ✓ Oysterun Host is running at [local Host URL]

Oysterun is ready.
Config: [Host config path]
Host URL: [Managed Host URL]
Host configuration, Cloud identity, service health, and endpoint were verified.

[On Ubuntu, one of these results follows:]
Start at boot: enabled. The Host starts by itself after this server restarts.

Start at boot: not enabled yet. Run this once, then the Host starts by itself after a restart:
  sudo loginctl enable-linger [your Ubuntu user]

Start at boot: not set up. Run Setup again (or the installer with --reinstall) to set it up.

Start at boot: this system does not support it (no systemd). After a restart, run: oysterun service:start
```

The last line means Oysterun checked the Host settings, its registration, that the service is running, and the Managed Endpoint.

Ubuntu prints only one **Start at boot** result. For **enabled**, no action is needed. For **not enabled yet**, paste the printed `sudo loginctl enable-linger [your Ubuntu user]` command and press Enter. If asked, type the password you use to log in to this Ubuntu computer; it stays invisible while you type. Then run `loginctl show-user [your Ubuntu user] -p Linger`; success shows `Linger=yes`. For **not set up**, run `oysterun setup` again, or run the installer with `--reinstall`, then follow the new result. If the system does not support it, run `oysterun service:start` after each server restart. macOS does not print this Ubuntu-only result.

Setup reports the Host URL during the guided flow. Keep that URL and the Host password private. A QR code can carry temporary sign-in information, so never publish or save a live QR.

If startup fails, use the last terminal error to correct that step, then run `oysterun setup` again. Installing the CLI alone is not success: continue until **Oysterun is ready** appears and the printed Managed Host URL opens.

## Sign in and pair the phone App {#browser-and-phone}

Open the Host URL in an ordinary browser and sign in with the Host password. On a computer, choose the **Host Preferences** tile under **OYSTERUN**. On a phone, tap the top-left **>|** toggle to open the drawer, then choose **Host Preferences**. Under **Host Identity And Browse Root**, compare **Host Display Name** with the name entered in Setup.

Before any Session exists, this screen shows **No sessions yet**. After your first Session, sign-in opens your last conversation instead. Use **Running Sessions** in the desktop sidebar to find the list; on a phone, open the same drawer with the top-left **>|** toggle.

![The screen shown before any Session exists](media/sessions-ready.png "Before any Session exists, No sessions yet proves the browser reached the new Host through its Managed Endpoint. New Session, Mail, and Host Preferences are under OYSTERUN.")

Install the [Oysterun iOS App](https://apps.apple.com/tw/app/oysterun/id6762069229). Scan the fresh login QR shown in Setup's **Phone app** step. To generate another one later, open **Host Preferences** from the **OYSTERUN** tiles (or the phone drawer), then go to **Connection** → **Login QR code** and choose **Generate Login QR**. Each login QR expires after 15 minutes; generate it only when the phone is ready to scan.

![A login QR generated in Host Preferences](media/login-qr.png "A login QR expires after 15 minutes. Never share an active login QR with anyone.")

![The Oysterun App sign-in screen on an iPhone Simulator](media/app-sign-in.png "The App accepts a Host URL and password, or opens the QR scanner with Scan QR code.")

The App can also use the same Host URL and Host password. The browser and phone are two ways to use the same Host and the same Sessions; pairing the phone does not create another Host.

If either screen shows a different Host name or address, close it and copy the correct Managed Endpoint from the Setup success output. If a security warning remains, do not enter the password; report the warning text and system version directly in [Oysterun Issues](https://github.com/GoatWang/OysterunCore/issues). Find the macOS version in **Apple menu → About This Mac**, the Ubuntu version with `lsb_release -a`, or the iOS version in **Settings → General → About**. Never include a password, QR code, or token.

If the password is rejected, return to sign-in and enter the Host password set in Setup. If the URL is unreachable, copy the Managed Host URL from the Setup success output again and check the internet connection; if it still does not open, run `oysterun setup` and finish the failed Host step.

## Install and sign in to one Provider {#choose-provider}

A Provider runs the Agent inside each Session. Oysterun supports five equal alternatives. Install only one to continue, using the account you use to sign in to this Mac or Ubuntu computer—not an Oysterun account.

### [Codex](https://developers.openai.com/codex/cli/) {#install-codex}

Install:
```bash
npm install -g @openai/codex
```
After you run the command below, your browser opens; choose **Sign in with ChatGPT** or the sign-in method you normally use, finish the browser flow, then return to Terminal:
```bash
codex login
```
Confirm the active sign-in method:
```bash
codex login status
```

### [Claude Code](https://code.claude.com/docs/en/setup) {#install-claude-code}

Install:
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
After you run the command below, your browser opens; use your Claude account. When Terminal shows **Login successful**, press Enter:
```bash
claude auth login
```
Confirm that the status says you are logged in:
```bash
claude auth status --text
```

### [Grok](https://x.ai/cli) {#install-grok}

Install:
```bash
npm install -g @xai-official/grok
```
After you run the command below, your browser opens; complete the Grok sign-in, then return to Terminal:
```bash
grok login
```
Confirm by opening Grok. You are signed in when its interactive screen opens without asking you to authenticate; exit it, then return to Oysterun:
```bash
grok
```

### [Antigravity](https://antigravity.google/docs/getting-started?tab=cli) {#install-antigravity}

Install:
```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```
After you run the command below, your browser opens. Follow the [Google sign-in flow](https://antigravity.google/docs/install?tab=cli): choose Google OAuth for a personal Google Account, or the Google Cloud option your organization uses, finish the browser flow, then return to Terminal:
```bash
agy
```
You are signed in when Antigravity opens its main interface and shows your account email in the header instead of asking you to sign in.

Oysterun does not require a specific minimum Antigravity version.

### [OpenCode](https://opencode.ai/docs/) {#install-opencode}

Install with OpenCode's official installer:
```bash
curl -fsSL https://opencode.ai/v2/install | bash
```
Sign in from Terminal, following the [official sign-in guide](https://opencode.ai/docs/cli/providers). Choose the model service (for example OpenAI or Anthropic) and the sign-in method; for OAuth, finish the browser or authorization-code flow, then return to Terminal:
```bash
opencode auth login
```
Confirm that the service you signed in to appears in the list:
```bash
opencode auth list
```

Oysterun does not require a specific minimum OpenCode version.

If your first Oysterun conversation shows **Login required**, return to this section and sign in to that tool again.

From the desktop sidebar, choose the **New Session** tile under **OYSTERUN** to open **Session Setup**. On a phone, first open the drawer with the top-left **>|** toggle. You can also press **⌘⇧P** on macOS to open the command palette and choose **Open New Session**. Select the Provider and press **Refresh provider models**. A model is the AI version the Provider uses to answer and work. A running Host uses that button to find a newly installed Provider and build its model list; without it, discovery happens at the next Host start. **Installed: version … (found automatically)** means it is ready. **Not installed** means install and sign in, then refresh. **Update required: …** means update from that Provider's official link above, then refresh again.

## Start your first Session {#first-session}

From the desktop sidebar, choose **New Session** under **OYSTERUN**. On a phone, open the drawer with **>|** first. This opens **Session Setup**:

1. Choose the Provider you just signed in to.
2. Choose an available model and reasoning effort—how much time and computation the Agent spends thinking.
3. Give the Agent and Session recognizable names.
4. Select the exact project folder you want the Agent to use.
5. Keep **Install/Overwrite Oysterun Skills** selected. It installs or updates only Oysterun instruction files for the Agent; it never overwrites project files.
6. Choose **Start Session**.

Success opens the new chat and lists it under **Running Sessions** in the sidebar. If it does not start: install and sign in for **Not installed**; update for **Update required**; press **Refresh provider models** when no model is available; or select a project inside the Default Browse Root for a folder error. For another error, report the text and system version directly in [Oysterun Issues](https://github.com/GoatWang/OysterunCore/issues). Find the macOS version in **Apple menu → About This Mac**, the Ubuntu version with `lsb_release -a`, or the iOS version in **Settings → General → About**. Never include passwords or tokens.

If an existing Session is missing the product Skills, open that Session and press **⌘⇧P** on macOS or **Ctrl+Shift+P** on Windows and Linux, then choose **Open Session Profile**. In **Oysterun Skills**, choose **Install/Update Oysterun Skills** before asking it to use Mail.

![The Oysterun Skills control selected in Session Setup](media/session-skills.png "Keep Install/Overwrite Oysterun Skills selected for the first Session.")

Send a small, read-only first request:

> Read this project without changing files. Tell me the project folder name and summarize what it contains in three bullets.

![The first read-only request ready to send](media/first-prompt.png "This small first request asks the Agent to read without changing files.")

Wait for the final reply. **Connected** only means the browser or App reached the Host. **Typing** or **Working** means the Agent is still processing. The task is complete when the full reply appears at the bottom of the conversation and Typing/Working is gone.

![The first Session while Codex is still typing](media/session-working.png "Typing or Working is progress, not the completed answer.")

In the desktop sidebar, open **Running Sessions** and choose the same Session. On a phone, first open the drawer with the top-left **>|** toggle. If the Session has stopped, expand **Stopped**, open that row's **•••** menu, and choose **Resume Chat**. Its name, Agent, project folder, and earlier reply should still match. Reopen that Session instead of creating a duplicate when you want to continue the same work.

## Receive your first Mail report {#first-mail-report}

Ask the Agent in that Session to turn its result into a short report and send it through the Oysterun Mail Skill:

> Create a short webpage-style report (HTML) from your project summary. Give it a clear title and one-sentence summary, include no private data, and send it to my Oysterun Mail using the Oysterun Mail Skill.

Wait for the Agent to confirm that the report was sent.

**Phone**:

1. Tap the top-left **>|** toggle to open the drawer.
2. Under **OYSTERUN**, tap **Mail**.
3. Find the new report at the top of **Inbox**.

**Desktop**:

1. Under **OYSTERUN** in the left sidebar, select **Mail**.
2. Find the new report at the top of **Inbox**.

If the Agent has not confirmed sending, wait for it to finish. If it confirmed but no item appears, choose the **Mail** tile again. If the Agent reports missing Skills, open the command palette with **⌘⇧P** on macOS or **Ctrl+Shift+P** on Windows and Linux, choose **Open Session Profile**, install or update Oysterun Skills, and send the request again. Oysterun Mail is not an external email message.

![The first report in the Oysterun Mail inbox](media/mail-inbox.png "The Mail tile opens Inbox, which shows the new report title and one-sentence summary.")

![The opened Getting Started Demo report](media/mail-report.png "Open the Mail item to read the complete report.")

## What to read next {#what-to-read-next}

Continue with the [Guides](/guides/en/index.html) for task-focused instructions and explanations.

## Uninstall Oysterun {#uninstall-oysterun}

In a terminal, as the operating-system user who runs the Host, preview the exact removal plan first:

```bash
oysterun uninstall --dry-run --confirm DELETE
```

Read the preview before continuing. It must name the Host service, configuration, and Oysterun terminal command installed for this user; stop if any item is unexpected.

To remove the selected Host service, its configuration, and the Oysterun terminal command installed for this user, run:

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

The default browse root, Agent folders, projects, Node.js, npm, and unrelated global packages are preserved. To remove the service while retaining Oysterun configuration and its terminal command, use `oysterun uninstall --keep-config` instead; do not combine it with `--confirm DELETE`.

Success says **Complete uninstall succeeded: service removed, configuration removed, CLI removed; user data preserved.** A check-before-removal error means Oysterun could not confirm the files or permissions it would remove. **Complete uninstall failed at …** means removal stopped at the named step. Keep the complete output and correct that step. If the cause is unclear, report it directly in [Oysterun Issues](https://github.com/GoatWang/OysterunCore/issues). Find the macOS version in **Apple menu → About This Mac**, the Ubuntu version with `lsb_release -a`, or the iOS version in **Settings → General → About**. Never include passwords or tokens.
