Oysterun lets you run Codex or Claude Code on your own Mac or Linux computer and operate that agent from an iPhone or web browser. This tutorial takes you from a clean machine to a verified first session.

1. Choose the computer that will run your Host

The Host is the Mac or Linux computer where Oysterun, your provider, projects, and agent processes run. Start with your current computer, or use an always-on Mac mini, Mini PC, or VPS later.

Operating system: a current macOS or Linux release.
Node.js: version 20 or newer.
Memory: 2 GB or more is recommended for an always-on Host.
Client: the Oysterun iPhone app or a modern web browser.
Provider: Codex or Claude Code installed and authenticated for the same operating-system user that will run Oysterun.

During setup, Oysterun asks how your phone or browser will reach this Host. Use localhost for a browser on the Host itself, a LAN address when both devices share a reachable network, or an existing VPN/tunnel address for remote access. You do not need to expose an unprotected Oysterun port to the public internet.

Checkpoint

node --version
npm --version
whoami

Confirm that Node reports version 20 or newer and that you will use this same user for the provider and Oysterun.

2. Install and sign in to Codex or Claude Code

Choose one provider. If it is already installed and logged in for this user, verify its status and continue.

Codex with Device Code

npm install -g @openai/codex@latest
codex --version
codex login --device-auth
codex login status

Open the device authorization page shown by Codex, enter the current one-time Device Code, and approve only the expected OpenAI Codex access. Do not publish or record the Device Code.

Claude Code

npm install -g @anthropic-ai/claude-code@latest
claude --version
claude auth login --claudeai
claude auth status

If authentication asks for an unexpected account, scope, password, MFA challenge, CAPTCHA, or security-warning bypass, stop and inspect the request before continuing.

3. Install the Oysterun Host

Install Oysterun globally for the same user. Do not use a different root account for either the provider or Oysterun.

npm install -g oysterun@latest --prefer-online
oysterun --version
oysterun

On the first run, oysterun detects that setup is incomplete and opens the guided setup automatically. You can rerun the wizard later with:

oysterun setup

4. Complete the guided setup

Host name: choose the name that will identify this computer.
Host port: accept port 8802 unless it is already in use.
Connection URL and projects: select the URL your client can reach, then choose a Default Browse Root where Explorer should begin.
Host password: create and confirm the password used for browser login. Input is hidden.
Telemetry: choose whether to share bounded daily diagnostics.
Phone app: optionally open the Oysterun download page before pairing.
Start Host: accept the default start action and wait for Host health.

The Default Browse Root is only Explorer's starting point. You still choose the exact working folder when creating a session.

Checkpoint

Setup should finish with a healthy Host, the selected Host URL, and either a short-lived login QR or instructions for password login. In an SSH terminal it prints the URL instead of forcing a local browser to open.

5. Connect from the iPhone app or a browser

Install Oysterun from the App Store if you want the native phone experience.

Oysterun listing in the App Store — Install the app before displaying the one-time Host login QR.

Phone: scan the QR printed after the Host starts, then open the saved Host.
Browser: open the reachable Host URL selected during setup and enter the Host password.

The QR is a short-lived login credential. Keep it out of screenshots and recordings. If it expires, create a new one without repeating setup:

oysterun show-qr

6. Start your first agent session

Create or choose a project folder inside the area you want the agent to access.
Open Sessions and choose New Session.
Select Codex or Claude Code.
Select the project folder as the session Start Folder.
Start the session and send a small verification prompt, such as List the files in this folder and tell me what this project contains.
Wait for one complete provider response before trying a larger task.

Oysterun chat page with controls for an active agent session — The same session can be opened from the phone app or Host web interface.

7. Check status and solve common first-run problems

The Host does not open

oysterun service:status
oysterun service:logs

Confirm that the service is running. If another device cannot reach the Host, verify that the selected URL is reachable from that device and rerun oysterun setup to choose a LAN, VPN, or tunnel address.

The provider is unavailable

codex login status
# or
claude auth status

Authenticate the provider as the same operating-system user that runs Oysterun, then create a new session or restart the existing session.

The QR expired

oysterun show-qr

Generate a fresh QR. Do not reuse or share an expired recording frame.

What to try next

After the first response succeeds, try a real project task. From Oysterun you can continue the session, stop runaway work, browse generated files, open HTML reports and websites, schedule recurring work, and receive notifications when the agent needs attention.