docs: remove internal US VM setup notes
This commit is contained in:
Hunter B
@@ -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>`
|
||||
- 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 <approval_id>` / `/deny <approval_id>`.
|
||||
6. Restart the VM and confirm both services come back.
|
||||
@@ -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
|
||||
|
||||
@@ -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. |
|
||||
|
||||
Reference in New Issue
Block a user