From 854274de1de4d5bbf8223f50718e8b2875756adc Mon Sep 17 00:00:00 2001 From: Hunter B Date: Tue, 9 Jun 2026 23:23:03 -0700 Subject: [PATCH] docs: remove internal US VM setup notes --- docs/REMOTE_VM_US.md | 172 ----------------------------- docs/TENCENT_CLOUD_REMOTE_FIRST.md | 3 - docs/V0_9_0_RELEASE_ACCEPTANCE.md | 2 +- 3 files changed, 1 insertion(+), 176 deletions(-) delete mode 100644 docs/REMOTE_VM_US.md diff --git a/docs/REMOTE_VM_US.md b/docs/REMOTE_VM_US.md deleted file mode 100644 index 321ce063..00000000 --- a/docs/REMOTE_VM_US.md +++ /dev/null @@ -1,172 +0,0 @@ -# US Remote VM Quickstart - -This is the default remote-phone setup for US-based users who want the least -cloud ceremony. Use this path unless you specifically need the Tencent/CNB/ -Feishu workflow in `docs/TENCENT_CLOUD_REMOTE_FIRST.md`. - -## Recommendation - -Use a small persistent Ubuntu VPS/VM, not a serverless/container platform, for -the main CodeWhale host. - -Good defaults: - -- DigitalOcean Droplet: 2 vCPU / 4 GB RAM / 80 GB SSD, Ubuntu. -- AWS Lightsail: 2 vCPU / 4 GB RAM / 80 GB SSD, Ubuntu. - -Minimum for a smoke test: - -- 2 vCPU / 2 GB RAM / 60 GB SSD. - -Better for Rust builds, subagents, and longer sessions: - -- 4 vCPU / 8 GB RAM / 160 GB SSD. - -## Why Not Railway First - -Railway is fine for a tiny relay service, but the main CodeWhale runtime wants: - -- a persistent checkout and worktrees -- shell access -- systemd or equivalent long-running service supervision -- predictable local disk paths -- direct SSH recovery when the agent or bridge is unhealthy - -That maps more cleanly to a VM. Use Railway later only if you want a public web -status page or a small bridge relay in front of a VM-hosted runtime. - -## Provider Choice - -- Choose DigitalOcean if you want the simplest VPS control panel and predictable - developer workflow. -- Choose AWS Lightsail if you already use AWS billing or want the AWS free-trial - path while staying in a simple VPS product. -- Avoid raw EC2 for the first setup unless you already know AWS networking, - IAM, security groups, and EBS. -- Avoid Lambda/ECR/Load Balancers for the first setup; they are not the - persistent interactive host CodeWhale needs. - -## Target Architecture - -```text -Laptop - -> git push / SSH - -DigitalOcean or AWS Lightsail Ubuntu VM - -> /opt/whalebro/codewhale - -> /opt/whalebro/worktrees - -> codewhale-runtime.service on 127.0.0.1:7878 - -> codewhale-telegram-bridge.service - -Telegram phone DM - -> Telegram Bot API long polling - -> local runtime API with CODEWHALE_RUNTIME_TOKEN -``` - -The runtime API must stay on `127.0.0.1`. Telegram long polling does not need -an inbound public webhook port. - -## Setup Shape - -Create an Ubuntu VM with SSH-key login. Open SSH only. Then: - -```bash -sudo apt-get update -sudo apt-get install -y git - -export CODEWHALE_BRANCH=codex/v0.8.53 -export CODEWHALE_REPO_URL=https://github.com/Hmbown/CodeWhale.git - -git clone --branch "$CODEWHALE_BRANCH" "$CODEWHALE_REPO_URL" /tmp/codewhale -cd /tmp/codewhale -sudo CODEWHALE_REPO_URL="$CODEWHALE_REPO_URL" \ - CODEWHALE_REPO_BRANCH="$CODEWHALE_BRANCH" \ - bash scripts/tencent-lighthouse/bootstrap-ubuntu.sh -``` - -The bootstrap script is named for the older Tencent runbook, but it now creates -CodeWhale-primary paths and env files: - -- `/etc/codewhale/runtime.env` -- `/etc/codewhale/feishu-bridge.env` -- `/opt/whalebro` -- `/opt/codewhale` - -Install Rust for the `codewhale` user, then build: - -```bash -sudo -iu codewhale -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs -o /tmp/rustup-init.sh -sed -n '1,120p' /tmp/rustup-init.sh -sh /tmp/rustup-init.sh -y --profile minimal -. "$HOME/.cargo/env" -rustup default stable -cd /opt/whalebro/codewhale -cargo install --path crates/cli --locked --force -cargo install --path crates/tui --locked --force -exit -``` - -Install the Telegram bridge service: - -```bash -cd /opt/whalebro/codewhale -sudo CODEWHALE_BRIDGE=telegram bash scripts/tencent-lighthouse/install-services.sh -``` - -Create a bot with Telegram's `@BotFather`, then edit: - -```bash -sudoedit /etc/codewhale/runtime.env -sudoedit /etc/codewhale/telegram-bridge.env -``` - -Required values: - -- `/etc/codewhale/runtime.env` - - `CODEWHALE_RUNTIME_TOKEN` - - `CODEWHALE_RUNTIME_PORT=7878` - - `CODEWHALE_PROVIDER=` - - provider API key such as `ARCEE_API_KEY`, `DEEPSEEK_API_KEY`, or - `XIAOMI_MIMO_API_KEY` -- `/etc/codewhale/telegram-bridge.env` - - `TELEGRAM_BOT_TOKEN` - - `CODEWHALE_RUNTIME_TOKEN` matching runtime.env - - `CODEWHALE_WORKSPACE=/opt/whalebro` - -For first pairing, temporarily set `TELEGRAM_ALLOW_UNLISTED=true`, DM the bot -`/status`, copy the returned `chat_id` into `TELEGRAM_CHAT_ALLOWLIST`, then set -`TELEGRAM_ALLOW_UNLISTED=false`. - -Validate and start: - -```bash -sudo -u codewhale node /opt/codewhale/telegram-bridge/scripts/validate-config.mjs \ - --env /etc/codewhale/telegram-bridge.env \ - --runtime-env /etc/codewhale/runtime.env \ - --workspace-root /opt/whalebro \ - --check-filesystem - -sudo systemctl start codewhale-runtime -sudo systemctl start codewhale-telegram-bridge -sudo CODEWHALE_BRIDGE=telegram bash /opt/whalebro/codewhale/scripts/tencent-lighthouse/doctor.sh -``` - -Useful logs: - -```bash -sudo journalctl -u codewhale-runtime -f -sudo journalctl -u codewhale-telegram-bridge -f -``` - -## First Smoke Test - -From Telegram: - -1. Send `/status`. -2. Send `/menu` and confirm the tappable control panel appears. -3. Send `summarize git status in /opt/whalebro/codewhale`. -4. Send `/threads` and test a `Resume` button. -5. Start a prompt that requires shell approval, then test both approval buttons - and the text fallback `/allow ` / `/deny `. -6. Restart the VM and confirm both services come back. diff --git a/docs/TENCENT_CLOUD_REMOTE_FIRST.md b/docs/TENCENT_CLOUD_REMOTE_FIRST.md index 18d85bf3..dd84a50b 100644 --- a/docs/TENCENT_CLOUD_REMOTE_FIRST.md +++ b/docs/TENCENT_CLOUD_REMOTE_FIRST.md @@ -8,9 +8,6 @@ It complements the local install path. If you only want to use `codewhale` on a laptop, start with the README quickstart. If you want "CodeWhale as a remote workbench I can control from my phone", start here. -For US-based users who do not need Tencent/CNB/Feishu, start with -`docs/REMOTE_VM_US.md` instead. - ## Default Stack ```text diff --git a/docs/V0_9_0_RELEASE_ACCEPTANCE.md b/docs/V0_9_0_RELEASE_ACCEPTANCE.md index dfcd95e5..186d6803 100644 --- a/docs/V0_9_0_RELEASE_ACCEPTANCE.md +++ b/docs/V0_9_0_RELEASE_ACCEPTANCE.md @@ -70,7 +70,7 @@ config source, result, and follow-up issue or PR. | Gate | Owner | Ship/defer decision | Evidence | | --- | --- | --- | --- | -| Remote workbench is marked included, experimental, or deferred | remote steward | defer runtime / ship setup docs only | `docs/REMOTE_VM_US.md`, `docs/REMOTE_SETUP_DESIGN.md`, and `docs/TENCENT_LIGHTHOUSE_HK.md` document possible VM/Telegram/Lark setup patterns, but no v0.9 remote workbench runtime is included. | +| Remote workbench is marked included, experimental, or deferred | remote steward | defer runtime / ship setup docs only | `docs/rfcs/REMOTE_SETUP_DESIGN.md` and `docs/TENCENT_LIGHTHOUSE_HK.md` document possible VM/Telegram/Lark setup patterns, but no v0.9 remote workbench runtime is included. | | If included: VM install smoke passes | remote steward | defer | Not applicable while remote workbench runtime is deferred; no v0.9 VM install smoke is required before tagging. | | If included: Telegram bridge smoke passes | remote steward | defer | Not applicable while remote workbench runtime is deferred; Telegram bridge docs remain design/setup guidance only. | | If deferred: release notes avoid implying remote workbench availability | remote steward | ship | Acceptance matrix and changelog wording must say setup/design docs only, not a shipped remote workbench feature. |