diff --git a/docs/docs.json b/docs/docs.json index 389adbe51..9d54c8471 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -815,11 +815,19 @@ }, { "source": "/gcp", - "destination": "/platforms/gcp" + "destination": "/platforms/google-cloud" }, { "source": "/gcp/", - "destination": "/platforms/gcp" + "destination": "/platforms/google-cloud" + }, + { + "source": "/platforms/gcp", + "destination": "/platforms/google-cloud" + }, + { + "source": "/platforms/gcp/", + "destination": "/platforms/google-cloud" } ], "navigation": { @@ -1090,10 +1098,12 @@ "platforms/android", "platforms/windows", "platforms/linux", + "platforms/digitalocean", + "platforms/exe-dev", "platforms/fly", + "platforms/google-cloud", "platforms/hetzner", - "platforms/gcp", - "platforms/exe-dev" + "platforms/oracle" ] }, { diff --git a/docs/platforms/digitalocean.md b/docs/platforms/digitalocean.md index e890c2c9f..3281686c2 100644 --- a/docs/platforms/digitalocean.md +++ b/docs/platforms/digitalocean.md @@ -11,24 +11,7 @@ read_when: Run a persistent Moltbot Gateway on DigitalOcean for **$6/month** (or $4/mo with reserved pricing). -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 | 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 | - -**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)) - ---- +If you want a $0/month option and don't mind ARM + provider-specific setup, see the [Oracle Cloud guide](/platforms/oracle). ## Prerequisites @@ -36,6 +19,15 @@ If you want a $0/month option and don’t mind ARM + provider-specific setup, se - SSH key pair (or willingness to use password auth) - ~20 minutes +## Quick Path + +1) Create Droplet (Ubuntu 24.04, $6/mo plan) +2) SSH in and install Node.js + Moltbot +3) Run `moltbot onboard --install-daemon` +4) Access via SSH tunnel or Tailscale + +--- + ## 1) Create a Droplet 1. Log into [DigitalOcean](https://cloud.digitalocean.com/) @@ -190,6 +182,23 @@ tar -czvf moltbot-backup.tar.gz ~/.clawdbot ~/clawd --- +## Cost + +| Provider | Plan | Specs | Price/mo | Notes | +|----------|------|-------|----------|-------| +| Oracle Cloud | Always Free ARM | up to 4 OCPU, 24GB RAM | $0 | ARM, limited capacity / signup quirks | +| 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 | + +**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)) + +--- + ## Oracle Cloud Free Alternative Oracle Cloud offers **Always Free** ARM instances that are significantly more powerful than any paid option here — for $0/month. @@ -237,7 +246,5 @@ free -h ## See Also -- [Hetzner guide](/platforms/hetzner) — cheaper, more powerful -- [Docker install](/install/docker) — containerized setup -- [Tailscale](/gateway/tailscale) — secure remote access -- [Configuration](/gateway/configuration) — full config reference +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/platforms/exe-dev.md b/docs/platforms/exe-dev.md index 796ddc374..594498840 100644 --- a/docs/platforms/exe-dev.md +++ b/docs/platforms/exe-dev.md @@ -11,7 +11,7 @@ Goal: Moltbot Gateway running on an exe.dev VM, reachable from your laptop via: This page assumes exe.dev's default **exeuntu** image. If you picked a different distro, map packages accordingly. -## Beginner quick path +## Quick Path 1) [https://exe.new/moltbot](https://exe.new/moltbot) 2) Fill in your auth key/token as needed @@ -19,7 +19,7 @@ This page assumes exe.dev's default **exeuntu** image. If you picked a different 4) ??? 5) Profit -## What you need +## Prerequisites - exe.dev account - `ssh exe.dev` access to [exe.dev](https://exe.dev) virtual machines (optional) @@ -123,3 +123,59 @@ moltbot health ``` Guide: [Updating](/install/updating) + +--- + +## Persistence + +All state lives in: +- `~/.clawdbot/` — config, credentials, session data +- `~/clawd/` — workspace (SOUL.md, memory, artifacts) + +Keep the VM **stateful**. Back up periodically: +```bash +tar -czvf moltbot-backup.tar.gz ~/.clawdbot ~/clawd +``` + +--- + +## Cost + +exe.dev pricing varies. Check [exe.dev](https://exe.dev) for current rates. + +| 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 | +| **exe.dev** | **VM** | **Varies** | **Varies** | **Built-in HTTPS proxy** | + +--- + +## Troubleshooting + +**Gateway won't start** + +```bash +moltbot gateway status +moltbot doctor --non-interactive +``` + +**nginx proxy issues** + +Verify the nginx config and restart: +```bash +sudo nginx -t +sudo systemctl restart nginx +``` + +**Can't reach Control UI** + +Check that nginx is forwarding port 8000 to 18789 and the Gateway is running. + +--- + +## See Also + +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/platforms/fly.md b/docs/platforms/fly.md index 02d24e84a..8d379a3ee 100644 --- a/docs/platforms/fly.md +++ b/docs/platforms/fly.md @@ -7,14 +7,14 @@ description: Deploy Moltbot on Fly.io **Goal:** Moltbot Gateway running on a [Fly.io](https://fly.io) machine with persistent storage, automatic HTTPS, and Discord/channel access. -## What you need +## Prerequisites - [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/) installed - Fly.io account (free tier works) - Model auth: Anthropic API key (or other provider keys) - Channel credentials: Discord bot token, Telegram token, etc. -## Beginner quick path +## Quick Path 1. Clone repo → customize `fly.toml` 2. Create app + volume → set secrets @@ -456,6 +456,22 @@ The ngrok tunnel runs inside the container and provides a public webhook URL wit - Persistent data lives on the volume at `/data` - Signal requires Java + signal-cli; use a custom image and keep memory at 2GB+. +## Persistence + +All state lives on the mounted volume at `/data`: +- `moltbot.json` — config +- Credentials and session data +- Agent workspace + +Back up periodically: +```bash +fly ssh console --command "tar -czvf /tmp/backup.tar.gz /data" +fly sftp shell +> get /tmp/backup.tar.gz ./moltbot-backup.tar.gz +``` + +--- + ## Cost With the recommended config (`shared-cpu-2x`, 2GB RAM): @@ -463,3 +479,10 @@ With the recommended config (`shared-cpu-2x`, 2GB RAM): - Free tier includes some allowance See [Fly.io pricing](https://fly.io/docs/about/pricing/) for details. + +--- + +## See Also + +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/platforms/gcp.md b/docs/platforms/google-cloud.md similarity index 91% rename from docs/platforms/gcp.md rename to docs/platforms/google-cloud.md index 6ad3825de..f11dd3b91 100644 --- a/docs/platforms/gcp.md +++ b/docs/platforms/google-cloud.md @@ -1,12 +1,12 @@ --- -summary: "Run Moltbot Gateway 24/7 on a GCP Compute Engine VM (Docker) with durable state" +summary: "Run Moltbot Gateway 24/7 on a Google Cloud Compute Engine VM (Docker) with durable state" read_when: - - You want Moltbot running 24/7 on GCP + - You want Moltbot running 24/7 on Google Cloud - You want a production-grade, always-on Gateway on your own VM - You want full control over persistence, binaries, and restart behavior --- -# Moltbot on GCP Compute Engine (Docker, Production VPS Guide) +# Moltbot on Google Cloud (Docker, Production VPS Guide) ## Goal @@ -34,7 +34,7 @@ For the generic Docker flow, see [Docker](/install/docker). --- -## Quick path (experienced operators) +## Quick Path 1) Create GCP project + enable Compute Engine API 2) Create Compute Engine VM (e2-small, Debian 12, 20GB) @@ -47,9 +47,9 @@ For the generic Docker flow, see [Docker](/install/docker). --- -## What you need +## Prerequisites -- GCP account (free tier eligible for e2-micro) +- Google Cloud account (free tier eligible for e2-micro) - gcloud CLI installed (or use Cloud Console) - SSH access from your laptop - Basic comfort with SSH + copy/paste @@ -398,7 +398,7 @@ Paste your gateway token. --- -## What persists where (source of truth) +## Persistence Moltbot runs in Docker, but Docker is not the source of truth. All long-lived state must survive restarts, rebuilds, and reboots. @@ -431,6 +431,20 @@ docker compose up -d --- +## Cost + +| 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 | +| **Google Cloud** | **e2-small** | **2 vCPU, 2GB RAM** | **~$12/mo** | **Recommended** | +| Google Cloud | e2-micro | 2 vCPU (shared), 1GB RAM | Free tier eligible | May OOM under load | + +Pricing varies by region. The e2-micro is part of the [GCP Free Tier](https://cloud.google.com/free) but may struggle under load. + +--- + ## Troubleshooting **SSH connection refused** @@ -491,8 +505,7 @@ See https://cloud.google.com/iam/docs/understanding-roles for IAM role details. --- -## Next steps +## See Also -- Set up messaging channels: [Channels](/channels) -- Pair local devices as nodes: [Nodes](/nodes) -- Configure the Gateway: [Gateway configuration](/gateway/configuration) +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/platforms/hetzner.md b/docs/platforms/hetzner.md index 695e72c7d..80be69737 100644 --- a/docs/platforms/hetzner.md +++ b/docs/platforms/hetzner.md @@ -33,7 +33,7 @@ For the generic Docker flow, see [Docker](/install/docker). --- -## Quick path (experienced operators) +## Quick Path 1) Provision Hetzner VPS 2) Install Docker @@ -46,7 +46,7 @@ For the generic Docker flow, see [Docker](/install/docker). --- -## What you need +## Prerequisites - Hetzner VPS with root access - SSH access from your laptop @@ -306,7 +306,7 @@ Paste your gateway token. --- -## What persists where (source of truth) +## Persistence Moltbot runs in Docker, but Docker is not the source of truth. All long-lived state must survive restarts, rebuilds, and reboots. @@ -323,3 +323,51 @@ All long-lived state must survive restarts, rebuilds, and reboots. | Node runtime | Container filesystem | Docker image | Rebuilt every image build | | OS packages | Container filesystem | Docker image | Do not install at runtime | | Docker container | Ephemeral | Restartable | Safe to destroy | + +--- + +## Cost + +| 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 | +| Google Cloud | e2-small | 2 vCPU, 2GB RAM | ~$12/mo | Free tier eligible (e2-micro) | + +Hetzner offers excellent price/performance for VPS hosting. + +--- + +## Troubleshooting + +**Gateway won't start** + +```bash +docker compose logs -f moltbot-gateway +``` + +Check for port conflicts or missing environment variables. + +**Out of memory (OOM)** + +If the container keeps restarting, increase RAM or add swap: + +```bash +fallocate -l 2G /swapfile +chmod 600 /swapfile +mkswap /swapfile +swapon /swapfile +echo '/swapfile none swap sw 0 0' >> /etc/fstab +``` + +**SSH connection issues** + +Verify your SSH key is added to the VPS and firewall allows port 22. + +--- + +## See Also + +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 65eeac2ed..b07d17d50 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -26,7 +26,7 @@ Native companion apps for Windows are also planned; the Gateway is recommended v - VPS hub: [VPS hosting](/vps) - Fly.io: [Fly.io](/platforms/fly) - Hetzner (Docker): [Hetzner](/platforms/hetzner) -- GCP (Compute Engine): [GCP](/platforms/gcp) +- Google Cloud (Compute Engine): [Google Cloud](/platforms/google-cloud) - exe.dev (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev) ## Common links diff --git a/docs/platforms/oracle.md b/docs/platforms/oracle.md index b77117054..434d973e7 100644 --- a/docs/platforms/oracle.md +++ b/docs/platforms/oracle.md @@ -12,29 +12,27 @@ read_when: Run a persistent Moltbot Gateway on Oracle Cloud's **Always Free** ARM tier. -Oracle’s free tier can be a great fit for Moltbot (especially if you already have an OCI account), but it comes with tradeoffs: +Oracle's free tier can be a great fit for Moltbot (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 +## Quick Path + +1) Create OCI ARM instance (VM.Standard.A1.Flex, Ubuntu 24.04) +2) Connect via SSH and install Tailscale +3) Install Moltbot via install script +4) Configure Gateway with token auth + Tailscale Serve +5) Lock down VCN security to Tailscale-only + +--- + ## 1) Create an OCI Instance 1. Log into [Oracle Cloud Console](https://cloud.oracle.com/) @@ -282,10 +280,19 @@ tar -czvf moltbot-backup.tar.gz ~/.clawdbot ~/clawd --- +## Cost + +| 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 | + +--- + ## 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 +- [Channels](/channels) +- [Gateway configuration](/gateway/configuration) diff --git a/docs/vps.md b/docs/vps.md index 91c5c3ca3..8bf779ea3 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -16,7 +16,7 @@ deployments work at a high level. - **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) +- **Google Cloud (Compute Engine)**: [Google Cloud](/platforms/google-cloud) - **exe.dev** (VM + HTTPS proxy): [exe.dev](/platforms/exe-dev) - **AWS (EC2/Lightsail/free tier)**: works well too. Video guide: https://x.com/techfrenAJ/status/2014934471095812547