---
name: oysterun-host-startup
description: Use when an Oysterun worker must understand, debug, verify, or change Host startup, stack selection, port/config sync, dashboard credential readiness, or provider command bootstrap.
metadata:
  short-description: Oysterun Host startup and stack config flow
---

# Oysterun Host Startup

Use this skill before changing or debugging Host startup, stack config, port selection, dashboard credential readiness, or provider command bootstrap.

## Product Skill Source

Canonical product skill source lives at `skills/oysterun-host-startup/`. The repo-local Codex mirror at `.codex/skills/oysterun-host-startup/` and the Host packaged asset at `host-service/assets/product-skills/oysterun-host-startup/` are generated mirrors. Run `node tool_scripts/sync_product_skills_to_codex.mjs` after changing this skill and `node tool_scripts/check_product_skill_mirrors.mjs` before review.

## Canonical Sources

Read these from the active worktree. If a doc disagrees with code, the scripts and Host config code win.

```text
Worker contract:
AGENTS.md

Stack / port / config-dir truth:
tool_scripts/oysterun_service_common.sh

Host lifecycle commands:
tool_scripts/start_oysterun.sh
tool_scripts/restart_oysterun.sh
tool_scripts/stop_oysterun.sh

Startup overview:
docs/_STARTUP_SCRIPTS.md

Host config schema and normalization:
host-service/config.mjs
```

## Supported Commands

Use the repo wrappers for real stacks:

```bash
./tool_scripts/start_oysterun.sh --stack <stack>
./tool_scripts/restart_oysterun.sh --stack <stack>
./tool_scripts/stop_oysterun.sh --stack <stack>
```

Do not start a real stack with ad hoc `cd host-service && npm start` commands unless the task explicitly routes an isolated direct Host experiment.

## Startup Order

The detached Host path is:

1. `tool_scripts/start_oysterun.sh`
2. `configure_stack_runtime`
3. `sync_host_stack_port_config`
4. `tool_scripts/sync_host_stack_config.mjs`
5. `ensure_stack_dashboard_credentials`
6. `tool_scripts/stack_dashboard_credentials.mjs ensure`
7. build web client and Route C web-chat static app
8. start Host through launchctl with `OYSTERUN_CONFIG_DIR`, `OYSTERUN_PORT`, and `OYSTERUN_REPO_ROOT`
9. wait for `/health`
10. write Host origin/readiness proof

`tool_scripts/restart_oysterun.sh` runs stop, then start. It does not have a separate startup path.

## Stack Config Sync

`sync_host_stack_port_config` is the shell entry point, despite the older name. It calls:

```text
tool_scripts/sync_host_stack_config.mjs
```

That helper:

- writes/syncs `port` from `OYSTERUN_PORT`
- fills `claude_command` and `codex_command` only when missing and detectable
- does not overwrite existing provider command values
- uses `OYSTERUN_CONFIG_DIR` as the Host config root

Treat missing or invalid `OYSTERUN_PORT` as a startup bug. Do not silently fall back to a guessed port.

## Dashboard Credentials

`ensure_stack_dashboard_credentials` calls:

```text
tool_scripts/stack_dashboard_credentials.mjs ensure
```

Credential behavior:

- if `dashboard_user` and `dashboard_password_hash` already exist, preserve them
- for `test1`..`test4` and `test_w*`, bootstrap the current verification credential hash when missing
- for `production`, do not invent credentials; use existing config only
- for custom stacks, require explicit `OYSTERUN_STACK_DASHBOARD_USER` and `OYSTERUN_STACK_DASHBOARD_PASSWORD` unless credentials already exist
- never persist plaintext dashboard passwords
- proof files must redact tokens, cookies, and plaintext secrets

## Phone App Identity

Capacitor app identity is config-driven, not hardcoded per worktree.

Common beta runtime values live in the beta stack config:

```text
~/.oysterun-stacks/beta/host/config.json
port: 9903
capacitor_app_id: com.oysterun.phone.beta
capacitor_app_name: OysterunBeta
```

Use the sync helper or an explicit Host config path:

```bash
./tool_scripts/sync_routec_capacitor_ios.sh --stack beta --port 9903 --app-id com.oysterun.phone.beta --app-name OysterunBeta
OYSTERUN_CAPACITOR_HOST_CONFIG=~/.oysterun-stacks/beta/host/config.json npm run cap:sync:ios
```

Do not hardcode beta app identity into generic P6 source.

## Verification Checklist

For startup/config changes, run focused checks before commit:

```bash
bash -n tool_scripts/start_oysterun.sh
bash -n tool_scripts/restart_oysterun.sh
bash -n tool_scripts/oysterun_service_common.sh
node --check tool_scripts/sync_host_stack_config.mjs
node --check tool_scripts/stack_dashboard_credentials.mjs
```

When behavior changes, add an isolated temporary `OYSTERUN_CONFIG_DIR` smoke test instead of mutating a real stack first.
