# Oysterun

## What Oysterun Is

Oysterun is a deployment and operations platform for working AI agents. It lets
people run Claude Code or Codex on their own Mac or Linux Host, then operate
those agents from an iPhone or web browser with persistent sessions,
scheduling, notifications, reports, websites, local files, and agent skills.

The core idea is that prompts and skills are not enough. A useful agent also
needs a runtime, tools, permissions, scheduled execution, a readable delivery
surface, and a reliable way for its user to intervene. Oysterun brings those
pieces together so an agent can move from "only its author can run it" toward a
complete AgentFolder that another user can install and operate.

## Build Week Scope

### Introduction

Oysterun is an existing platform that was created before OpenAI Build Week. The
submission does not claim that the complete Oysterun Host, client, session,
scheduling, Mail, Website, notification, or skill system was built during the
event.

For this submission, Build Week work is measured from July 14, 2026 at 00:00
Asia/Taipei, equivalent to July 13, 2026 at 09:00 Pacific Time. The final
repository commit before that cutoff is `cf9c8e11` (July 13 at 20:31
Asia/Taipei), and the submission snapshot is `711c0246` (July 20 at 23:39
Asia/Taipei). The range `cf9c8e11..711c0246` contains 39 commits including
merges and changes 159 distinct files.

The work in that measured range focuses on making complete agents easier to
distribute and use:

- **Stock Research Agent:** a cloneable AgentFolder that researches stocks,
  generates readable HTML reports, publishes them through Oysterun Website, and
  can deliver them through Oysterun Mail.
- **GitHub Tracker Agent:** a cloneable AgentFolder that monitors public GitHub
  repositories, runs on a schedule, and publishes update reports.
- **Direct GitHub Agent Store:** a new Oysterun flow that accepts a public
  GitHub repository URL, safely clones the AgentFolder into the Host, resolves
  its configuration, starts a session, and opens the resulting chat.

This Build Week submission demonstrates these new agents and the Agent Store
workflow running on the existing Oysterun platform.

The dated Git history and the submitted Codex `/feedback` Session ID provide
evidence of the work completed during the submission period.

### Evidence

1. Important Commits:
    - SQLite migration and tool-detail integration, July 14: `56690244` through `7a2e304e`
    - Provider aggregation and Telegram delivery follow-ups, July 14:
    `523c68d9` through `f6c66f58`
    - Timeline and pagination recovery, July 16:
    `212a9fd3` through `2caf0fa2`
    - Browser Root AgentFolder registration, July 19: `87e6df47`
    - Direct GitHub Agent Store clone/start demo, July 20: `ba6bbdfa`
2. Team Session:
    1. PM: 019f5761-**1078**-7dc3-a130-64ac66435cc8
    2. Team Lead: 019f5760-ee50-70e3-870e-1d16838305f2
    3. Assistant1: 019f56e8-4c9f-71b2-8ad5-a0232b95686d
    4. Assistant2: 019f552a-3830-7cf3-92ca-dd483fa63cf9
    5. Engineer: 019f56fc-c4cd-7120-a2ff-d2c603ebafa7
    6. Manual Session: 019f05d5-f491-7db3-8bf6-94eba3c89607
3. Other Repo (Agents):
    1. https://github.com/GoatWang/oysterun-ccstock-workenv-en
    2. https://github.com/GoatWang/oysterun-github-tracker

## How Codex And GPT-5.6 Were Used

The work measured from the July 14, 00:00 Asia/Taipei cutoff was developed with
Codex as the primary engineering environment and GPT-5.6 as the reasoning model
for planning, codebase investigation, implementation, verification design,
debugging, and review.

Rather than using Codex only for isolated code generation, Oysterun was
developed by a persistent AI engineering team running through Oysterun itself:

- two Assistants prepared requirements, verification plans, and progress
  summaries;
- one Project Manager coordinated tasks and checked progress every two minutes;
- one Team Lead reviewed architecture, verification evidence, and priorities;
- three Engineers implemented and tested scoped changes;
- every 30 minutes, an Assistant summarized team progress for human review.

The human Owner made the product, security, UX, and release decisions. Codex
traced behavior across the Host, web client, Matrix facade, provider adapters,
skills, and operational scripts; implemented the approved phases; and produced
focused verification evidence. This workflow let the project continue making
measurable progress while the Owner worked full-time and while the Oysterun Host
ran remotely on a Mac mini in Taiwan.

## Judge Quickstart

### Hosted review environment (recommended)

A dedicated Oysterun Host URL and its login password are provided privately in
the project registration form. Judges should follow the access instructions in
that form; it is the authoritative source for the current Host address and
credentials. No local installation or rebuild is required for this path.

Available clients:

1. **iOS app**
   - Install [Oysterun from the App Store](https://apps.apple.com/tw/app/oysterun/id6762069229).
   - Add the Host URL supplied in the registration form.
   - Sign in with the supplied Host password.
2. **Web browser**
   - Open the Host `/app/` URL supplied in the registration form.
   - Sign in with the supplied Host password.

Both clients connect to the same dedicated Host and expose the same sessions.
The password is intentionally not stored in this public repository.

## What Judges Should Test

1. Open the `oysterun-ccstock-workenv-en-da14e` session.
2. Ask any question, then ask the agent to generate a report.
3. Open the website URL returned by the agent.
4. Check the mail box
5. Ask the agent to create a schedule or send you a Mail item.
6. Open the Webiste in the external browser

## Oysterun Skills

The repository includes first-party skills that let Codex operate
Oysterun through its supported CLI rather than direct Host API calls:

- `skills/oysterun-sessions`
- `skills/oysterun-session-chat`
- `skills/oysterun-find-context`
- `skills/oysterun-scheduler`
- `skills/oysterun-notifications`
- `skills/oysterun-mail`
- `skills/oysterun-telegram`
- `skills/oysterun-website`

`skills/Oysterun` is the umbrella skill set used when Oysterun installs or
updates the product skills in an AgentFolder.

------------------------------------OpenAI Build Week------------------------------------

## Runtime Pieces

Oysterun currently has three main runtime pieces:

- `backend/`: the Cloud API written in FastAPI
- `host-service/`: the Host daemon that runs on the Mac mini
- `dev/client/`: the local web client served by the Host service at `/app`

The web client does not have its own frontend server right now. The Host service serves the built HTML file directly.

## Architecture In One Minute

The current product/runtime shape is:

1. start the Host service
2. open the web client from the Host service
3. optionally connect the Host to Oysterun Cloud later

For local repo development, you can still run backend + Host together when you need the Cloud side of the stack.

In code terms:

- the backend owns users, devices, agents, onboarding, Cloud auth, and device route/access-token APIs
- the Host service owns local sessions, provider adapters, transcript/upload storage, the web client, and Host-local config
- the web client is just a Host-served frontend for interacting with the Host service

## Project Layout

```text
Oysterun/
  backend/               FastAPI Cloud backend
  host-service/          Local Host daemon and provider runtime bridge
  dev/client/          Host-served web client source
  docs/                  Product, design, auth, mock, and TODO docs
  local notes            Gitignored working notes, reports, and ad hoc verification files
  temp/                  Local export output from tool_scripts/export_key_files.sh
  test-results/          Playwright output
  tool_scripts/          One-off local utilities
  investigation-repos/   Reference repos used for research only
```

Folders you can usually ignore when reading product code:

- gitignored operational notes: plans, reports, and ad hoc verification files
- `temp/`: export bundles created by `tool_scripts/export_key_files.sh`
- `test-results/`: Playwright run output such as `.last-run.json`, traces, screenshots, and other browser-test artifacts
- `investigation-repos/`: external reference code, not the Oysterun runtime itself

## First-Time Setup

### Backend

```bash
cd <repo-root>/backend
uv sync --extra dev
```

### Host Service

```bash
cd <repo-root>/host-service
npm install
```

### Optional Root Packages

The root `package.json` is mainly for Playwright and repo-level utilities, not for the main app runtime.

```bash
cd <repo-root>
npm install
```

## How To Start The Project

### 1. Optional: start the backend for repo development

```bash
cd <repo-root>/backend
uv run python -m uvicorn app.main:app --reload
```

Default local URLs:

- API root: `http://localhost:8000/`
- health: `http://localhost:8000/health`
- FastAPI docs: `http://localhost:8000/docs`

Notes:

- backend config lives in `backend/app/config.py`
- default DB is SQLite via `sqlite+aiosqlite:///./oysterun.db`
- tables are auto-created on startup in dev by `backend/app/main.py`
- this backend is Oysterun Cloud infrastructure code, not part of the normal Host-only v1 startup path

### 2. Start the Host service

```bash
cd <repo-root>/host-service
npm run setup
npm start
```

Useful commands:

```bash
npm run setup   # first-run Managed Tunnel Host setup
node host-service/setup.mjs   # source-local Direct Host setup
node bin/oysterun.mjs setup --local   # explicit local-only Direct setup
npm start       # plain start, no watch mode
npm run dev     # watch mode for Host JS files
npm run cli     # local CLI client
npm test        # Host-side tests
```

Default local URLs when you run `npm start` or `npm run dev` directly with the canonical home config:

- health: `http://localhost:8802/health`
- web client: `http://localhost:8802/app`

Port notes:

- production default is `8802` in `~/.oysterun/config.json`
- staging uses `9902`
- disposable test slots use `3022`, `3302`, `4022`, and `4402`
- phone app verification can use any running Host port; point the app at the actual user-approved port for that run
- backend URL default is `http://localhost:8000`
- Host config is stored in `~/.oysterun/config.json`
- direct mode can also store an optional `public_base_url` there for manual client connection
- fresh Session Setup runtime defaults, including interface style plus Claude/Codex provider defaults, are stored there under `session_defaults`
- Host Preferences shows the active config path, so `OYSTERUN_CONFIG_DIR` overrides are visible in the UI
- release setup defaults to Oysterun Managed Tunnel
- source-local setup and `oysterun setup --local` retain explicit Direct mode

### Optional: start backend + Host together for repo development

For local repo development, you can launch the backend and Host together with the stack-aware foreground runner:

```bash
cd <repo-root>
./tool_scripts/dev_up.sh
./tool_scripts/dev_up.sh --stack staging
```

What it does:

- rebuilds `dev/client/web/index.html`
- starts the selected development backend in reload mode
- starts the selected Host in watch mode
- uses `staging` by default
- syncs the stack-owned Host port before start
- stops both when you press `Ctrl-C`

This is a repo development helper, not the normal product startup path and not a replacement for a real system service such as `launchd`.

To start the dev stack, register the Host with Cloud, and display the user-onboarding QR code in one command:

```bash
./tool_scripts/dev_up_with_qr.sh
```

The first run automatically installs missing web-chat and Host Node dependencies with `npm ci`. If the active Node version changes, it also rebuilds `better-sqlite3` for the current Node ABI.

### Optional: detached start/stop/restart scripts

If you want the Host to keep running after you close the current terminal, use the background service scripts instead of `tmux`:

```bash
cd <repo-root>
./tool_scripts/start_oysterun.sh
./tool_scripts/stop_oysterun.sh
./tool_scripts/restart_oysterun.sh
```

Convenience wrappers are also available at:

```bash
~/Projects/start_oysterun.sh
~/Projects/stop_oysterun.sh
~/Projects/restart_oysterun.sh
```

Stack-specific usage:

```bash
~/Projects/start_oysterun.sh --stack staging
~/Projects/restart_oysterun.sh --stack staging
~/Projects/stop_oysterun.sh --stack staging
```

What they do:

- rebuild the web client before Host start
- submit launchd-managed background jobs for the Host
- start the selected stack Host only
- do not initialize backend runtime state
- use `production` by default
- keep production Host config under `~/.oysterun/config.json`
- keep staging/test Host config under `~/.oysterun-stacks/<stack>/host/config.json`
- write PID files under `~/.oysterun/run/` or `~/.oysterun-stacks/<stack>/run/`
- write logs under `~/.oysterun/logs/` or `~/.oysterun-stacks/<stack>/logs/`

Important:

- this is more convenient than `tmux` for manual start/stop/restart
- these scripts use temporary `launchctl submit` jobs unless you explicitly install the persistent LaunchAgents
- for persistent login-time auto-start and crash auto-restart on `8802` and `9902`, use `./tool_scripts/install_oysterun_launch_agents.sh`
- these scripts use stable non-watch commands; use `./tool_scripts/dev_up.sh` when you want backend + Host live auto-reload during active repo development
- `./tool_scripts/dev_up.sh` is the only startup path that initializes backend runtime state
- the supported preset stacks are `production`, `staging`, `test1`, `test2`, `test3`, and `test4`
- `production` uses Host `8802`
- `staging` uses Host `9902`
- `test1..test4` use Host `3022`, `3302`, `4022`, and `4402`
- `./tool_scripts/dev_up.sh` is for staging-oriented repo development and uses backend `9000`
- set `OYSTERUN_STAGING_LAN_HOST=<your_lan_ip>` if the staging stack should advertise a different LAN IP than `192.168.0.188`

### 3. Use the web client

For the default production Host, open:

```text
http://localhost:8802/app
```

For staging, open:

```text
http://localhost:9902/app
```

The web client is served by the Host service. There is no separate frontend dev server to start.

## How To Work On The Frontend

Frontend files live here:

- `dev/client/web/src/index.template.html`
- `dev/client/web/src/styles.css`
- `dev/client/web/build-index.mjs`
- `dev/client/web/index.html`

How it works:

- `src/index.template.html` is the main UI source
- `src/styles.css` is injected into the template
- `build-index.mjs` generates `dev/client/web/index.html`
- `host-service/server.mjs` reads `dev/client/web/index.html` and serves it at `/app`

After frontend edits:

```bash
cd <repo-root>
node dev/client/web/build-index.mjs
```

Then restart the Host service.

Why restart is needed:

- the Host service reads `dev/client/web/index.html` at startup and keeps it in memory
- rebuilding the HTML alone does not refresh the running Host process

## How To Restart Things

### Backend restart

If you started it with:

```bash
uv run python -m uvicorn app.main:app --reload
```

then Python code changes should auto-reload.

If you need a clean restart:

1. stop the process with `Ctrl-C`
2. run the same command again

### Host service restart

If you started it with:

```bash
npm run dev
```

then Host `.mjs` code changes should auto-restart the service.

You still need a manual restart when:

- you rebuilt `dev/client/web/index.html`
- you changed non-imported static files that the watch process does not track the way you expect

Manual restart:

1. stop the Host process with `Ctrl-C`
2. run `npm run dev` again

### Detached service restart

If you started the Host background scripts, restart with:

```bash
~/Projects/restart_oysterun.sh
```

or:

```bash
cd <repo-root>
./tool_scripts/restart_oysterun.sh
```

For staging:

```bash
~/Projects/restart_oysterun.sh --stack staging
```

### Frontend restart

There is no separate frontend process.

To refresh frontend changes:

1. rebuild the web client HTML
2. restart the Host service

## Service Structure

### Backend structure

Main entry:

- `backend/app/main.py`

Core modules:

- `backend/app/config.py`: environment-backed settings
- `backend/app/database.py`: SQLAlchemy async engine and session dependency
- `backend/app/models/`: ORM models
- `backend/app/schemas/`: request/response schemas
- `backend/app/services/`: auth, crypto, email helpers
- `backend/app/routers/`: FastAPI route modules
- `backend/tests/`: backend tests

Backend router responsibilities:

- `routers/devices.py`: device register, heartbeat, route, Host access-token
- `routers/agents.py`: agent CRUD, memberships, invites
- `routers/auth.py`: device-link and email login flows
- `routers/onboarding.py`: device onboarding pages and completion
- `routers/sessions.py`: Cloud-side session state and deprecated compatibility stubs
- `routers/users.py`: current user and quota APIs
- `routers/email.py`: email send endpoint

### Host service structure

Main entry:

- `host-service/server.mjs`

Core modules:

- `host-service/session-manager.mjs`: Host-owned session lifecycle
- `host-service/provider-registry.mjs`: provider metadata and capabilities
- `host-service/adapters/claude-code-adapter.mjs`: Claude runtime bridge
- `host-service/adapters/codex-app-server-adapter.mjs`: Codex runtime bridge
- `host-service/agent-config.mjs`: `.oysterun` config layering and workspace policy
- `host-service/browser-root-project-index.mjs`: in-memory Browser Root project discovery
- `host-service/session-history.mjs`: recent session summaries
- `host-service/upload-manager.mjs`: uploaded file persistence
- `host-service/session-assets.mjs`: `~/.oysterun` asset paths
- `host-service/jwt-auth.mjs`: JWT verification
- `host-service/host-authz.mjs`: per-agent capability checks
- `host-service/folder-browser.mjs`: web client folder browsing
- `host-service/config.mjs`: Host config in `~/.oysterun/config.json`
- `host-service/ngrok-agent.mjs`: ngrok route reporting
- `host-service/setup.mjs`: direct-mode Host setup and optional Cloud registration
- `host-service/cli.mjs`: local CLI client

### Web Client structure

Main files:

- `dev/client/web/src/index.template.html`: primary UI markup and client logic
- `dev/client/web/src/styles.css`: web client styles
- `dev/client/web/build-index.mjs`: build step for the served HTML
- `dev/client/web/index.html`: built file served by the Host

## Recommended Code Reading Order

If you are new to the repo, read in this order:

1. `docs/_SPIRIT.md`
2. `docs/_DESIGN.md`
3. `README.md`
4. `backend/app/main.py`
5. `host-service/server.mjs`
6. `dev/client/README.md`
7. the specific service modules for the feature you are touching

Within each service, use this order:

### Backend

1. `app/main.py`
2. `app/config.py`
3. `app/database.py`
4. `app/models/`
5. `app/services/`
6. `app/routers/`
7. `backend/tests/`

### Host service

1. `server.mjs`
2. `session-manager.mjs`
3. `provider-registry.mjs`
4. `adapters/`
5. `agent-config.mjs`
6. transcript/upload/history modules

### Web Client

1. `dev/client/README.md`
2. `dev/client/web/build-index.mjs`
3. `dev/client/web/src/index.template.html`
4. `dev/client/web/src/styles.css`

## Useful Docs

- `docs/_SPIRIT.md`: product intent and direction
- `docs/_DESIGN.md`: confirmed architecture and auth flow
- `docs/_AUTH.md`: auth details
- `docs/_MOCK.md`: known mock/stub behavior
- `docs/_TODO.md`: current implementation backlog

## Tests

Backend:

```bash
cd <repo-root>/backend
uv run pytest
```

Host service:

```bash
cd <repo-root>/host-service
npm test
```

Browser and ad hoc verification artifacts in this repo have usually been kept as gitignored operational notes, not as a permanent full test suite under `tests/`.

## Local Artifact Folders

### `temp/`

`temp/` is mainly used by:

- `tool_scripts/export_key_files.sh`

That script creates export folders and zip files like:

- `temp/key-file-export-<timestamp>/`
- `temp/key-file-export-<timestamp>.zip`

These are manual local export artifacts, not app runtime files.

### `test-results/`

`test-results/` is Playwright output.

It is recreated by Playwright runs such as:

```bash
npx playwright test
```

It can contain files like:

- `.last-run.json`
- traces
- screenshots
- videos