From a98852c938a30716d02daeb811da852371081385 Mon Sep 17 00:00:00 2001 From: Mislav Ivanda <72461767+mislavivanda@users.noreply.github.com> Date: Mon, 3 Aug 2026 08:17:18 +0200 Subject: [PATCH] docs: add Daytona hosting guide (#116411) Adds a Daytona hosting guide covering sandbox creation, onboarding, secure preview-URL dashboard access, channel setup, updates, and troubleshooting, and links it from the hosting navigation. Prepared head SHA: 4faf05211b452884fa7f879c113b65f0ec5e489f Co-authored-by: Mislav Ivanda <72461767+mislavivanda@users.noreply.github.com> Co-authored-by: Shakker <165377636+shakkernerd@users.noreply.github.com> Reviewed-by: @shakkernerd --- docs/.i18n/glossary.zh-CN.json | 12 ++ docs/docs.json | 1 + docs/install/daytona.md | 312 +++++++++++++++++++++++++++++++++ docs/platforms/index.md | 9 +- docs/vps.md | 1 + 5 files changed, 331 insertions(+), 4 deletions(-) create mode 100644 docs/install/daytona.md diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index 4bc968088388..b71b57ea3193 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -1702,5 +1702,17 @@ { "source": "Automations (cron)", "target": "自动化 (cron)" + }, + { + "source": "Daytona", + "target": "Daytona" + }, + { + "source": "Gateway remote access", + "target": "Gateway 远程访问" + }, + { + "source": "Updating OpenClaw", + "target": "更新 OpenClaw" } ] diff --git a/docs/docs.json b/docs/docs.json index 9d483de69ca2..7fe4d8ea8527 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1110,6 +1110,7 @@ "group": "Hosting", "pages": [ "install/azure", + "install/daytona", "install/digitalocean", "install/docker-vm-runtime", "install/exe-dev", diff --git a/docs/install/daytona.md b/docs/install/daytona.md new file mode 100644 index 000000000000..8e530fd39131 --- /dev/null +++ b/docs/install/daytona.md @@ -0,0 +1,312 @@ +--- +summary: "Run OpenClaw in a Daytona cloud sandbox with SSH access and signed preview URLs" +read_when: + - Running OpenClaw in a Daytona sandbox + - You want a cloud sandbox for OpenClaw without managing a VPS +title: "Daytona" +--- + +Run a persistent OpenClaw Gateway in a [Daytona](https://www.daytona.io) cloud +sandbox: an isolated Linux environment with SSH access and built-in preview +URLs, no VPS management required. OpenClaw comes pre-installed in the +`daytona-medium` snapshot, so setup starts immediately after SSH. + +Keep the Gateway on loopback and reach the dashboard through Daytona's signed +preview URLs. Do not expose the Gateway port directly to the public internet. + +## What you need + +- [Daytona account](https://app.daytona.io) (free tier available) +- Daytona API key from the [Daytona dashboard](https://app.daytona.io/dashboard/keys) +- API key for your model provider (Anthropic, OpenAI, etc.) + +## Install the Daytona CLI + + + + ```bash + brew install daytonaio/cli/daytona + ``` + + + ```powershell + powershell -Command "irm https://get.daytona.io/windows | iex" + ``` + + + +Verify the installation: + +```bash +daytona --version +``` + +Older CLI versions miss newer sandbox commands; keep it current (for example +`brew upgrade daytonaio/cli/daytona`). + +## Authenticate + +```bash +daytona login --api-key=YOUR_API_KEY +``` + +## Create a sandbox + +```bash +daytona sandbox create --name openclaw --snapshot daytona-medium --auto-stop 0 +``` + +| Flag | Why | +| --------------------------- | -------------------------------------------------- | +| `--snapshot daytona-medium` | Provides enough memory headroom to run the Gateway | +| `--auto-stop 0` | Keeps the sandbox running until manually stopped | + +## Connect via SSH + +```bash +daytona ssh openclaw +``` + +## Run onboarding + +Inside the sandbox, configure OpenClaw in one command: + +```bash +openclaw onboard --non-interactive --accept-risk \ + --anthropic-api-key YOUR_ANTHROPIC_KEY \ + --skip-daemon --skip-channels --skip-skills --skip-hooks --skip-health +``` + +`--skip-daemon` matters: Daytona sandboxes do not run a service manager, so +you start the Gateway manually below. Swap the key flag for your provider +(`--openai-api-key`, `--openrouter-api-key`, and so on); `openclaw onboard +--help` lists them all. Channels, skills, and hooks are skipped here and +configured later. + +Running `openclaw onboard` without flags starts a conversational setup +assistant instead and requires an interactive terminal; +`openclaw onboard --classic` runs the older step-by-step wizard. + +Onboarding configures a gateway auth token. Print it any time from the +sandbox: + +```bash +node -p "require(process.env.HOME + '/.openclaw/openclaw.json').gateway.auth.token" +``` + +`openclaw config get gateway.auth.token` returns `__OPENCLAW_REDACTED__` +rather than the value, because the CLI masks secrets in its output. + +## Allow the preview URL origin + +The Gateway accepts browser connections only from allowed origins, and +Daytona's preview proxy sits in front of it. Configure both before starting +the Gateway. + +From your **local terminal** (not the sandbox SSH session), generate a signed +preview URL for the Gateway port: + +```bash +daytona preview-url openclaw --port 18789 +``` + +Copy the URL it prints. Back in the sandbox SSH session, allow that origin and +trust the in-sandbox preview proxy, replacing the example URL with your own: + +```bash +openclaw config set gateway.controlUi.allowedOrigins '["PASTE_YOUR_PREVIEW_URL"]' +openclaw config set gateway.trustedProxies '["127.0.0.1"]' +``` + +Paste the URL exactly as printed: scheme and host only, with no trailing slash +and no path. The Gateway compares the browser origin literally, and browsers +send `https://host` without a trailing slash, so `https://host/` fails to +match and the connection is rejected. Browser address bars often display that +trailing slash, so copy from the terminal instead. + +## Start the Gateway + +```bash +nohup openclaw gateway run > /tmp/gateway.log 2>&1 & +``` + +The Gateway runs in the background and survives SSH disconnects. Verify it is +up: + +```bash +openclaw gateway health +``` + +The command reports the Gateway status, so `OK` means you are good to +continue. + +To restart the Gateway later (after config changes or updates): + +```bash +pkill -f "openclaw gateway" || true +nohup openclaw gateway run > /tmp/gateway.log 2>&1 & +``` + +## Open the dashboard + +Open the preview URL you generated earlier in your browser. The Control UI +asks for the gateway token on first connect; paste the value you printed +after onboarding. + +### Approve your device + +The first browser connection queues a device pairing request. Back in your +sandbox SSH session: + +```bash +# List pending requests and copy the request id +openclaw devices list + +# Approve it +openclaw devices approve REQUEST_ID +``` + +## Security + +Access to the Gateway is protected in three layers: + +| Layer | Description | +| --------------- | ------------------------------------------------------ | +| Preview URL | Time-limited signed URL (expires after 1 hour) | +| Gateway token | Required to connect via the Control UI | +| Device approval | Each new browser or client must be explicitly approved | + +Keep your gateway token and preview URLs private. The Gateway stays bound to +loopback; Daytona's preview proxy handles external access. + +## Channel setup + +Unknown senders require pairing approval by default; see +[Pairing](/channels/pairing). + +### Telegram + +Create a bot with [@BotFather](https://t.me/botfather) (`/newbot`), copy the +token, then configure OpenClaw from the sandbox SSH session: + +```bash +openclaw config set channels.telegram.enabled true +openclaw config set channels.telegram.botToken YOUR_BOT_TOKEN +``` + +Restart the Gateway (see above), send your bot a DM, then approve the pairing +code it reports: + +```bash +openclaw pairing list telegram +openclaw pairing approve telegram PAIRING_CODE +``` + +Pairing codes expire after 1 hour. Full reference: [Telegram](/channels/telegram). + +### WhatsApp + +WhatsApp ships as a separate plugin, so install and enable it first: + +```bash +openclaw plugins install clawhub:@openclaw/whatsapp --acknowledge-clawhub-risk +openclaw plugins enable whatsapp +``` + +Installing does not enable a plugin, so the `enable` step is required; +otherwise the Gateway reports the channel as configured but untrusted. Running +the login command below without installing first prompts you to download the +plugin from ClawHub or npm instead. + +Then link the account by scanning a QR code from the sandbox SSH session: + +```bash +openclaw channels login --channel whatsapp +``` + +On your phone: **Settings → Linked Devices → Link a Device**, then scan the QR +code shown in the terminal. Restart the Gateway after linking, then message +yourself on WhatsApp and OpenClaw replies in that chat. + +No pairing approval is needed: with no allowlist configured, the linked +account's own number is allowed by default. Pairing applies to unknown +senders, which is why Telegram needs it and self-chat does not. Allowlists, +personal-number mode, and self-chat details: [WhatsApp](/channels/whatsapp). + +## Updating + +The snapshot's global npm tree is owned by root, so plain `openclaw update` +cannot write to it. Update from the sandbox SSH session with: + +```bash +sudo env "PATH=$PATH" npm install --global openclaw@latest +openclaw doctor +``` + +`openclaw doctor` migrates any older config after the update. Restart the +Gateway afterwards (see above). + +## Stop and resume the sandbox + +```bash +# Stop +daytona sandbox stop openclaw + +# Resume +daytona sandbox start openclaw +``` + +Sandbox state persists across stop/start cycles, but the Gateway process does +not auto-start. After a resume, reconnect and start it again: + +```bash +daytona ssh openclaw +nohup openclaw gateway run > /tmp/gateway.log 2>&1 & +``` + +## Troubleshooting + +### Gateway not running after sandbox restart + +The Gateway process does not survive a sandbox restart. Reconnect with +`daytona ssh openclaw` and start it again with the `nohup` command above. + +### Preview URL expired + +Preview URLs are time-limited (default 3600 seconds). Regenerate from your +local terminal, optionally with a longer expiry: + +```bash +daytona preview-url openclaw --port 18789 --expires 86400 +``` + +Each generated URL has a different host, so it is a new origin. After +regenerating, update `gateway.controlUi.allowedOrigins` with the new URL and +restart the Gateway, or the Control UI is rejected with `origin not allowed`. + +### Sandbox auto-stopped + +If the sandbox was created without `--auto-stop 0`, it stops automatically +when idle. Resume it with `daytona sandbox start openclaw`. + +### Gateway port not reachable + +Confirm the Gateway is running and listening: + +```bash +openclaw gateway health +tail -20 /tmp/gateway.log +``` + +If you changed the Gateway port, pass the same port to `daytona preview-url`. + +## Notes + +- For programmatic sandbox provisioning, see the + [Daytona OpenClaw SDK guide](https://www.daytona.io/docs/en/guides/openclaw/openclaw-sdk-sandbox/) + +## Related + +- [Gateway remote access](/gateway/remote) +- [Gateway security](/gateway/security) +- [Updating OpenClaw](/install/updating) diff --git a/docs/platforms/index.md b/docs/platforms/index.md index e6178c187f84..25a1cf020f32 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -27,12 +27,13 @@ Linux-compatible Gateway runtime. ## VPS and hosting - VPS hub: [VPS hosting](/vps) -- Fly.io: [Fly.io](/install/fly) -- Hetzner (Docker): [Hetzner](/install/hetzner) -- GCP (Compute Engine): [GCP](/install/gcp) - Azure (Linux VM): [Azure](/install/azure) -- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev) +- Daytona (cloud sandbox): [Daytona](/install/daytona) - EasyRunner (Podman + Caddy): [EasyRunner](/platforms/easyrunner) +- exe.dev (VM + HTTPS proxy): [exe.dev](/install/exe-dev) +- Fly.io: [Fly.io](/install/fly) +- GCP (Compute Engine): [GCP](/install/gcp) +- Hetzner (Docker): [Hetzner](/install/hetzner) ## Common links diff --git a/docs/vps.md b/docs/vps.md index 99e82893458b..6b5ce16d8223 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -16,6 +16,7 @@ tuning that applies everywhere. Linux VM + Cloud sandbox with preview URLs Simple paid VPS VM with HTTPS proxy Fly Machines