From 10d5ea5de6acacfe0169072cd9689203b1218c1e Mon Sep 17 00:00:00 2001 From: Frank Harris Date: Mon, 26 Jan 2026 14:23:11 -0500 Subject: [PATCH] docs: Add Oracle Cloud (OCI) platform guide (#2333) * docs: Add Oracle Cloud (OCI) platform guide - Add comprehensive guide for Oracle Cloud Always Free tier (ARM) - Cover VCN security, Tailscale Serve setup, and why traditional hardening is unnecessary - Update vps.md to list Oracle as top provider option - Update digitalocean.md to link to official Oracle guide instead of community gist Co-Authored-By: Claude Opus 4.5 * Keep community gist link, remove unzip * Fix step order: lock down VCN after Tailscale is running * Move VCN lockdown to final step (after verifying everything works) * docs: make Oracle/Tailscale guide safer + tone down DO copy * docs: fix Oracle guide step numbering * docs: tone down VPS hub Oracle blurb * docs: add Oracle Cloud guide (#2333) (thanks @hirefrank) --------- Co-authored-by: Claude Opus 4.5 Co-authored-by: Pocket Clawd --- CHANGELOG.md | 1 + docs/platforms/digitalocean.md | 34 +-- docs/platforms/oracle.md | 291 +++++++++++++++++++++ docs/vps.md | 3 +- src/discord/monitor/presence-cache.test.ts | 7 +- 5 files changed, 308 insertions(+), 28 deletions(-) create mode 100644 docs/platforms/oracle.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 16c1a05ff..ffcd26721 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,7 @@ Status: unreleased. - Docs: add Render deployment guide. (#1975) Thanks @anurag. - Docs: add Claude Max API Proxy guide. (#1875) Thanks @atalovesyou. - Docs: add DigitalOcean deployment guide. (#1870) Thanks @0xJonHoldsCrypto. +- Docs: add Oracle Cloud (OCI) platform guide + cross-links. (#2333) Thanks @hirefrank. - Docs: add Raspberry Pi install guide. (#1871) Thanks @0xJonHoldsCrypto. - Docs: add GCP Compute Engine deployment guide. (#1848) Thanks @hougangdev. - Docs: add LINE channel guide. Thanks @thewilloftheshadow. diff --git a/docs/platforms/digitalocean.md b/docs/platforms/digitalocean.md index 632057c84..afefe3676 100644 --- a/docs/platforms/digitalocean.md +++ b/docs/platforms/digitalocean.md @@ -1,5 +1,5 @@ --- -summary: "Clawdbot on DigitalOcean (cheapest paid VPS option)" +summary: "Clawdbot on DigitalOcean (simple paid VPS option)" read_when: - Setting up Clawdbot on DigitalOcean - Looking for cheap VPS hosting for Clawdbot @@ -11,22 +11,22 @@ read_when: Run a persistent Clawdbot Gateway on DigitalOcean for **$6/month** (or $4/mo with reserved pricing). -If you want something even cheaper, see [Oracle Cloud (Free Tier)](#oracle-cloud-free-alternative) at the bottom — it's **actually free forever**. +If you want a $0/month option and don’t mind ARM + provider-specific setup, see the [Oracle Cloud guide](/platforms/oracle). ## Cost Comparison (2026) | Provider | Plan | Specs | Price/mo | Notes | |----------|------|-------|----------|-------| -| **Oracle Cloud** | Always Free ARM | 4 OCPU, 24GB RAM | **$0** | Best value, requires ARM-compatible setup | -| **Hetzner** | CX22 | 2 vCPU, 4GB RAM | €3.79 (~$4) | Cheapest paid, EU datacenters | -| **DigitalOcean** | Basic | 1 vCPU, 1GB RAM | $6 | Easy UI, good docs | -| **Vultr** | Cloud Compute | 1 vCPU, 1GB RAM | $6 | Many locations | -| **Linode** | Nanode | 1 vCPU, 1GB RAM | $5 | Now part of Akamai | +| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0 | ARM, limited capacity / signup quirks | +| Hetzner | CX22 | 2 vCPU, 4GB RAM | €3.79 (~$4) | Cheapest paid option | +| DigitalOcean | Basic | 1 vCPU, 1GB RAM | $6 | Easy UI, good docs | +| Vultr | Cloud Compute | 1 vCPU, 1GB RAM | $6 | Many locations | +| Linode | Nanode | 1 vCPU, 1GB RAM | $5 | Now part of Akamai | -**Recommendation:** -- **Free:** Oracle Cloud ARM (if you can handle the signup process) -- **Paid:** Hetzner CX22 (best specs per dollar) — see [Hetzner guide](/platforms/hetzner) -- **Easy:** DigitalOcean (this guide) — beginner-friendly UI +**Picking a provider:** +- DigitalOcean: simplest UX + predictable setup (this guide) +- Hetzner: good price/perf (see [Hetzner guide](/platforms/hetzner)) +- Oracle Cloud: can be $0/month, but is more finicky and ARM-only (see [Oracle guide](/platforms/oracle)) --- @@ -192,7 +192,7 @@ tar -czvf clawdbot-backup.tar.gz ~/.clawdbot ~/clawd ## Oracle Cloud Free Alternative -Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful: +Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful than any paid option here — for $0/month. | What you get | Specs | |--------------|-------| @@ -201,19 +201,11 @@ Oracle Cloud offers **Always Free** ARM instances that are significantly more po | **200GB storage** | Block volume | | **Forever free** | No credit card charges | -### Quick setup: -1. Sign up at [oracle.com/cloud/free](https://www.oracle.com/cloud/free/) -2. Create a VM.Standard.A1.Flex instance (ARM) -3. Choose Oracle Linux or Ubuntu -4. Allocate up to 4 OCPU / 24GB RAM within free tier -5. Follow the same Clawdbot install steps above - **Caveats:** - Signup can be finicky (retry if it fails) - ARM architecture — most things work, but some binaries need ARM builds -- Oracle may reclaim idle instances (keep them active) -For the full Oracle guide, see the [community docs](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd). +For the full setup guide, see [Oracle Cloud](/platforms/oracle). For signup tips and troubleshooting the enrollment process, see this [community guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd). --- diff --git a/docs/platforms/oracle.md b/docs/platforms/oracle.md new file mode 100644 index 000000000..d8006754b --- /dev/null +++ b/docs/platforms/oracle.md @@ -0,0 +1,291 @@ +--- +summary: "Clawdbot on Oracle Cloud (Always Free ARM)" +read_when: + - Setting up Clawdbot on Oracle Cloud + - Looking for low-cost VPS hosting for Clawdbot + - Want 24/7 Clawdbot on a small server +--- + +# Clawdbot on Oracle Cloud (OCI) + +## Goal + +Run a persistent Clawdbot Gateway on Oracle Cloud's **Always Free** ARM tier. + +Oracle’s free tier can be a great fit for Clawdbot (especially if you already have an OCI account), but it comes with tradeoffs: + +- ARM architecture (most things work, but some binaries may be x86-only) +- Capacity and signup can be finicky + +## Cost Comparison (2026) + +| Provider | Plan | Specs | Price/mo | Notes | +|----------|------|-------|----------|-------| +| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0 | ARM, limited capacity | +| Hetzner | CX22 | 2 vCPU, 4GB RAM | ~ $4 | Cheapest paid option | +| DigitalOcean | Basic | 1 vCPU, 1GB RAM | $6 | Easy UI, good docs | +| Vultr | Cloud Compute | 1 vCPU, 1GB RAM | $6 | Many locations | +| Linode | Nanode | 1 vCPU, 1GB RAM | $5 | Now part of Akamai | + +--- + +## Prerequisites + +- Oracle Cloud account ([signup](https://www.oracle.com/cloud/free/)) — see [community signup guide](https://gist.github.com/rssnyder/51e3cfedd730e7dd5f4a816143b25dbd) if you hit issues +- Tailscale account (free at [tailscale.com](https://tailscale.com)) +- ~30 minutes + +## 1) Create an OCI Instance + +1. Log into [Oracle Cloud Console](https://cloud.oracle.com/) +2. Navigate to **Compute → Instances → Create Instance** +3. Configure: + - **Name:** `clawdbot` + - **Image:** Ubuntu 24.04 (aarch64) + - **Shape:** `VM.Standard.A1.Flex` (Ampere ARM) + - **OCPUs:** 2 (or up to 4) + - **Memory:** 12 GB (or up to 24 GB) + - **Boot volume:** 50 GB (up to 200 GB free) + - **SSH key:** Add your public key +4. Click **Create** +5. Note the public IP address + +**Tip:** If instance creation fails with "Out of capacity", try a different availability domain or retry later. Free tier capacity is limited. + +## 2) Connect and Update + +```bash +# Connect via public IP +ssh ubuntu@YOUR_PUBLIC_IP + +# Update system +sudo apt update && sudo apt upgrade -y +sudo apt install -y build-essential +``` + +**Note:** `build-essential` is required for ARM compilation of some dependencies. + +## 3) Configure User and Hostname + +```bash +# Set hostname +sudo hostnamectl set-hostname clawdbot + +# Set password for ubuntu user +sudo passwd ubuntu + +# Enable lingering (keeps user services running after logout) +sudo loginctl enable-linger ubuntu +``` + +## 4) Install Tailscale + +```bash +curl -fsSL https://tailscale.com/install.sh | sh +sudo tailscale up --ssh --hostname=clawdbot +``` + +This enables Tailscale SSH, so you can connect via `ssh clawdbot` from any device on your tailnet — no public IP needed. + +Verify: +```bash +tailscale status +``` + +**From now on, connect via Tailscale:** `ssh ubuntu@clawdbot` (or use the Tailscale IP). + +## 5) Install Clawdbot + +```bash +curl -fsSL https://clawd.bot/install.sh | bash +source ~/.bashrc +``` + +When prompted "How do you want to hatch your bot?", select **"Do this later"**. + +> Note: If you hit ARM-native build issues, start with system packages (e.g. `sudo apt install -y build-essential`) before reaching for Homebrew. + +## 6) Configure Gateway (loopback + token auth) and enable Tailscale Serve + +Use token auth as the default. It’s predictable and avoids needing any “insecure auth” Control UI flags. + +```bash +# Keep the Gateway private on the VM +clawdbot config set gateway.bind loopback + +# Require auth for the Gateway + Control UI +clawdbot config set gateway.auth.mode token +clawdbot doctor --generate-gateway-token + +# Expose over Tailscale Serve (HTTPS + tailnet access) +clawdbot config set gateway.tailscale.mode serve +clawdbot config set gateway.trustedProxies '["127.0.0.1"]' + +systemctl --user restart clawdbot-gateway +``` + +## 7) Verify + +```bash +# Check version +clawdbot --version + +# Check daemon status +systemctl --user status clawdbot-gateway + +# Check Tailscale Serve +tailscale serve status + +# Test local response +curl http://localhost:18789 +``` + +## 8) Lock Down VCN Security + +Now that everything is working, lock down the VCN to block all traffic except Tailscale. OCI's Virtual Cloud Network acts as a firewall at the network edge — traffic is blocked before it reaches your instance. + +1. Go to **Networking → Virtual Cloud Networks** in the OCI Console +2. Click your VCN → **Security Lists** → Default Security List +3. **Remove** all ingress rules except: + - `0.0.0.0/0 UDP 41641` (Tailscale) +4. Keep default egress rules (allow all outbound) + +This blocks SSH on port 22, HTTP, HTTPS, and everything else at the network edge. From now on, you can only connect via Tailscale. + +--- + +## Access the Control UI + +From any device on your Tailscale network: + +``` +https://clawdbot..ts.net/ +``` + +Replace `` with your tailnet name (visible in `tailscale status`). + +No SSH tunnel needed. Tailscale provides: +- HTTPS encryption (automatic certs) +- Authentication via Tailscale identity +- Access from any device on your tailnet (laptop, phone, etc.) + +--- + +## Security: VCN + Tailscale (recommended baseline) + +With the VCN locked down (only UDP 41641 open) and the Gateway bound to loopback, you get strong defense-in-depth: public traffic is blocked at the network edge, and admin access happens over your tailnet. + +This setup often removes the *need* for extra host-based firewall rules purely to stop Internet-wide SSH brute force — but you should still keep the OS updated, run `clawdbot security audit`, and verify you aren’t accidentally listening on public interfaces. + +### What's Already Protected + +| Traditional Step | Needed? | Why | +|------------------|---------|-----| +| UFW firewall | No | VCN blocks before traffic reaches instance | +| fail2ban | No | No brute force if port 22 blocked at VCN | +| sshd hardening | No | Tailscale SSH doesn't use sshd | +| Disable root login | No | Tailscale uses Tailscale identity, not system users | +| SSH key-only auth | No | Tailscale authenticates via your tailnet | +| IPv6 hardening | Usually not | Depends on your VCN/subnet settings; verify what’s actually assigned/exposed | + +### Still Recommended + +- **Credential permissions:** `chmod 700 ~/.clawdbot` +- **Security audit:** `clawdbot security audit` +- **System updates:** `sudo apt update && sudo apt upgrade` regularly +- **Monitor Tailscale:** Review devices in [Tailscale admin console](https://login.tailscale.com/admin) + +### Verify Security Posture + +```bash +# Confirm no public ports listening +sudo ss -tlnp | grep -v '127.0.0.1\|::1' + +# Verify Tailscale SSH is active +tailscale status | grep -q 'offers: ssh' && echo "Tailscale SSH active" + +# Optional: disable sshd entirely +sudo systemctl disable --now ssh +``` + +--- + +## Fallback: SSH Tunnel + +If Tailscale Serve isn't working, use an SSH tunnel: + +```bash +# From your local machine (via Tailscale) +ssh -L 18789:127.0.0.1:18789 ubuntu@clawdbot +``` + +Then open `http://localhost:18789`. + +--- + +## Troubleshooting + +### Instance creation fails ("Out of capacity") +Free tier ARM instances are popular. Try: +- Different availability domain +- Retry during off-peak hours (early morning) +- Use the "Always Free" filter when selecting shape + +### Tailscale won't connect +```bash +# Check status +sudo tailscale status + +# Re-authenticate +sudo tailscale up --ssh --hostname=clawdbot --reset +``` + +### Gateway won't start +```bash +clawdbot gateway status +clawdbot doctor --non-interactive +journalctl --user -u clawdbot-gateway -n 50 +``` + +### Can't reach Control UI +```bash +# Verify Tailscale Serve is running +tailscale serve status + +# Check gateway is listening +curl http://localhost:18789 + +# Restart if needed +systemctl --user restart clawdbot-gateway +``` + +### ARM binary issues +Some tools may not have ARM builds. Check: +```bash +uname -m # Should show aarch64 +``` + +Most npm packages work fine. For binaries, look for `linux-arm64` or `aarch64` releases. + +--- + +## Persistence + +All state lives in: +- `~/.clawdbot/` — config, credentials, session data +- `~/clawd/` — workspace (SOUL.md, memory, artifacts) + +Back up periodically: +```bash +tar -czvf clawdbot-backup.tar.gz ~/.clawdbot ~/clawd +``` + +--- + +## See Also + +- [Gateway remote access](/gateway/remote) — other remote access patterns +- [Tailscale integration](/gateway/tailscale) — full Tailscale docs +- [Gateway configuration](/gateway/configuration) — all config options +- [DigitalOcean guide](/platforms/digitalocean) — if you want paid + easier signup +- [Hetzner guide](/platforms/hetzner) — Docker-based alternative diff --git a/docs/vps.md b/docs/vps.md index d57205922..192ab830e 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -1,5 +1,5 @@ --- -summary: "VPS hosting hub for Clawdbot (Fly/Hetzner/GCP/exe.dev)" +summary: "VPS hosting hub for Clawdbot (Oracle/Fly/Hetzner/GCP/exe.dev)" read_when: - You want to run the Gateway in the cloud - You need a quick map of VPS/hosting guides @@ -11,6 +11,7 @@ deployments work at a high level. ## Pick a provider +- **Oracle Cloud (Always Free)**: [Oracle](/platforms/oracle) — $0/month (Always Free, ARM; capacity/signup can be finicky) - **Fly.io**: [Fly.io](/platforms/fly) - **Hetzner (Docker)**: [Hetzner](/platforms/hetzner) - **GCP (Compute Engine)**: [GCP](/platforms/gcp) diff --git a/src/discord/monitor/presence-cache.test.ts b/src/discord/monitor/presence-cache.test.ts index 8cdf8cefa..007d0548a 100644 --- a/src/discord/monitor/presence-cache.test.ts +++ b/src/discord/monitor/presence-cache.test.ts @@ -1,11 +1,6 @@ import { beforeEach, describe, expect, it } from "vitest"; import type { GatewayPresenceUpdate } from "discord-api-types/v10"; -import { - clearPresences, - getPresence, - presenceCacheSize, - setPresence, -} from "./presence-cache.js"; +import { clearPresences, getPresence, presenceCacheSize, setPresence } from "./presence-cache.js"; describe("presence-cache", () => { beforeEach(() => {