From 0aa48a26d1545aca659251b84d7401229612a3fc Mon Sep 17 00:00:00 2001 From: adeboyedn Date: Mon, 26 Jan 2026 08:07:33 +0100 Subject: [PATCH 1/6] docs: add Northflank deployment guide for Clawdbot --- docs/docs.json | 4 ++++ docs/help/faq.md | 2 ++ docs/northflank.mdx | 51 +++++++++++++++++++++++++++++++++++++++++ docs/platforms/index.md | 2 ++ docs/vps.md | 2 ++ 5 files changed, 61 insertions(+) create mode 100644 docs/northflank.mdx diff --git a/docs/docs.json b/docs/docs.json index 2cc5ae78b..12c6cc36b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -805,6 +805,10 @@ "source": "/install/railway/", "destination": "/railway" }, + { + "source": "/install/northflank/", + "destination": "/northflank" + }, { "source": "/gcp", "destination": "/platforms/gcp" diff --git a/docs/help/faq.md b/docs/help/faq.md index 336b324c9..165895e53 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -566,6 +566,8 @@ Remote access: [Gateway remote](/gateway/remote). We keep a **hosting hub** with the common providers. Pick one and follow the guide: - [VPS hosting](/vps) (all providers in one place) +- [Railway](/railway) (one‑click, browser‑based setup) +- [Northflank](/northflank) (one‑click, browser‑based setup) - [Fly.io](/platforms/fly) - [Hetzner](/platforms/hetzner) - [exe.dev](/platforms/exe-dev) diff --git a/docs/northflank.mdx b/docs/northflank.mdx new file mode 100644 index 000000000..1a53bf2fe --- /dev/null +++ b/docs/northflank.mdx @@ -0,0 +1,51 @@ +--- +title: Deploy on Northflank +--- + +Deploy Clawdbot on Northflank with a one-click template and finish setup in your browser. +This is the easiest “no terminal on the server” path: Northflank runs the Gateway for you, +and you configure everything via the `/setup` web wizard. + +## How to get started + +1. Click [Deploy Clawdbot](https://northflank.com/stacks/deploy-clawdbot) to open the template. +2. Create an [account on Northflank](https://app.northflank.com/signup) if you don’t already have one. +3. Click **Deploy Clawdbot now**. +4. Set the required environment variable: `SETUP_PASSWORD` +5. Click **Deploy stack** to build and run the Clawdbot template. +6. Wait for the deployment to complete, then click **View resources**. +7. Open the Clawdbot service. +8. Open the public Clawdbot URL and complete setup at `/setup`. + +## What you get + +- Hosted Clawdbot Gateway + Control UI +- Web setup wizard at `/setup` (no terminal commands) +- Persistent storage via Northflank Volume (`/data`) so config/credentials/workspace survive redeploys + +## Setup flow + +1) Visit `https:///setup` and enter your `SETUP_PASSWORD`. +2) Choose a model/auth provider and paste your key. +3) (Optional) Add Telegram/Discord/Slack tokens. +4) Click **Run setup**. + +If Telegram DMs are set to pairing, the setup wizard can approve the pairing code. + +## Getting chat tokens + +### Telegram bot token + +1) Message `@BotFather` in Telegram +2) Run `/newbot` +3) Copy the token (looks like `123456789:AA...`) +4) Paste it into `/setup` + +### Discord bot token + +1) Go to https://discord.com/developers/applications +2) **New Application** → choose a name +3) **Bot** → **Add Bot** +4) **Enable MESSAGE CONTENT INTENT** under Bot → Privileged Gateway Intents (required or the bot will crash on startup) +5) Copy the **Bot Token** and paste into `/setup` +6) Invite the bot to your server (OAuth2 URL Generator; scopes: `bot`, `applications.commands`) diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 3a1e87267..69b37090e 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -24,6 +24,8 @@ Native companion apps for Windows are also planned; the Gateway is recommended v ## VPS & hosting - VPS hub: [VPS hosting](/vps) +- Railway (one-click): [Railway](/railway) +- Northflank (one-click): [Northflank](/northflank) - Fly.io: [Fly.io](/platforms/fly) - Hetzner (Docker): [Hetzner](/platforms/hetzner) - GCP (Compute Engine): [GCP](/platforms/gcp) diff --git a/docs/vps.md b/docs/vps.md index 192ab830e..08910733f 100644 --- a/docs/vps.md +++ b/docs/vps.md @@ -11,6 +11,8 @@ deployments work at a high level. ## Pick a provider +- **Railway** (one‑click + browser setup): [Railway](/railway) +- **Northflank** (one‑click + browser setup): [Northflank](/northflank) - **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) From 2a709385f8c74b5c503c58983df8bc5fee253cea Mon Sep 17 00:00:00 2001 From: adeboyedn Date: Mon, 26 Jan 2026 15:05:42 +0100 Subject: [PATCH 2/6] cleanup --- docs/help/faq.md | 2 -- docs/platforms/index.md | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/help/faq.md b/docs/help/faq.md index 165895e53..336b324c9 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -566,8 +566,6 @@ Remote access: [Gateway remote](/gateway/remote). We keep a **hosting hub** with the common providers. Pick one and follow the guide: - [VPS hosting](/vps) (all providers in one place) -- [Railway](/railway) (one‑click, browser‑based setup) -- [Northflank](/northflank) (one‑click, browser‑based setup) - [Fly.io](/platforms/fly) - [Hetzner](/platforms/hetzner) - [exe.dev](/platforms/exe-dev) diff --git a/docs/platforms/index.md b/docs/platforms/index.md index 69b37090e..3a1e87267 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -24,8 +24,6 @@ Native companion apps for Windows are also planned; the Gateway is recommended v ## VPS & hosting - VPS hub: [VPS hosting](/vps) -- Railway (one-click): [Railway](/railway) -- Northflank (one-click): [Northflank](/northflank) - Fly.io: [Fly.io](/platforms/fly) - Hetzner (Docker): [Hetzner](/platforms/hetzner) - GCP (Compute Engine): [GCP](/platforms/gcp) From 99ce47e86af55b524883f674feee1b05e43dcc0a Mon Sep 17 00:00:00 2001 From: adeboyedn Date: Mon, 26 Jan 2026 15:41:19 +0100 Subject: [PATCH 3/6] minor update --- docs/northflank.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/northflank.mdx b/docs/northflank.mdx index 1a53bf2fe..7108278fe 100644 --- a/docs/northflank.mdx +++ b/docs/northflank.mdx @@ -16,6 +16,7 @@ and you configure everything via the `/setup` web wizard. 6. Wait for the deployment to complete, then click **View resources**. 7. Open the Clawdbot service. 8. Open the public Clawdbot URL and complete setup at `/setup`. +9. Open the Control UI at `/clawdbot` ## What you get @@ -29,6 +30,7 @@ and you configure everything via the `/setup` web wizard. 2) Choose a model/auth provider and paste your key. 3) (Optional) Add Telegram/Discord/Slack tokens. 4) Click **Run setup**. +5) Open the Control UI at `https:///clawdbot` If Telegram DMs are set to pairing, the setup wizard can approve the pairing code. From 107f07ad69335c8a877cc0770396dc8c48f1563b Mon Sep 17 00:00:00 2001 From: Clawdbot Maintainers Date: Mon, 26 Jan 2026 15:01:10 -0800 Subject: [PATCH 4/6] docs: add Northflank page to nav + polish copy --- docs/docs.json | 1 + docs/northflank.mdx | 10 +++++----- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/docs.json b/docs/docs.json index 12c6cc36b..c53902451 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -856,6 +856,7 @@ "install/docker", "railway", "render", + "northflank", "install/bun" ] }, diff --git a/docs/northflank.mdx b/docs/northflank.mdx index 7108278fe..aae9c6a22 100644 --- a/docs/northflank.mdx +++ b/docs/northflank.mdx @@ -11,12 +11,12 @@ and you configure everything via the `/setup` web wizard. 1. Click [Deploy Clawdbot](https://northflank.com/stacks/deploy-clawdbot) to open the template. 2. Create an [account on Northflank](https://app.northflank.com/signup) if you don’t already have one. 3. Click **Deploy Clawdbot now**. -4. Set the required environment variable: `SETUP_PASSWORD` -5. Click **Deploy stack** to build and run the Clawdbot template. -6. Wait for the deployment to complete, then click **View resources**. -7. Open the Clawdbot service. +4. Set the required environment variable: `SETUP_PASSWORD`. +5. Click **Deploy stack** to build and run the Clawdbot template. +6. Wait for the deployment to complete, then click **View resources**. +7. Open the Clawdbot service. 8. Open the public Clawdbot URL and complete setup at `/setup`. -9. Open the Control UI at `/clawdbot` +9. Open the Control UI at `/clawdbot`. ## What you get From cd7be58b8ecb03c3249be6f8faefef9083de70e1 Mon Sep 17 00:00:00 2001 From: vignesh07 Date: Mon, 26 Jan 2026 15:10:31 -0800 Subject: [PATCH 5/6] docs: add Northflank deploy guide to changelog (#2167) (thanks @AdeboyeDN) --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fbe151592..a45315b20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,7 @@ Status: unreleased. - Agents: honor tools.exec.safeBins in exec allowlist checks. (#2281) - Docs: tighten Fly private deployment steps. (#2289) Thanks @dguido. - Docs: add migration guide for moving to a new machine. (#2381) +- Docs: add Northflank one-click deployment guide. (#2167) Thanks @AdeboyeDN. - Gateway: warn on hook tokens via query params; document header auth preference. (#2200) Thanks @YuriNachos. - Gateway: add dangerous Control UI device auth bypass flag + audit warnings. (#2248) - Doctor: warn on gateway exposure without auth. (#2016) Thanks @Alex-Alaniz. From 82746973d4fe37ddc727eefdcc408a82697b8eaf Mon Sep 17 00:00:00 2001 From: Dave Lauer Date: Mon, 26 Jan 2026 09:50:26 -0500 Subject: [PATCH 6/6] fix(heartbeat): remove unhandled rejection crash in wake handler The async setTimeout callback re-threw errors without a .catch() handler, causing unhandled promise rejections that crashed the gateway. The error is already logged by the heartbeat runner and a retry is scheduled, so the re-throw served no purpose. Co-Authored-By: Claude Opus 4.5 --- src/infra/heartbeat-wake.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/infra/heartbeat-wake.ts b/src/infra/heartbeat-wake.ts index 9d5a4c4ce..eb26bf499 100644 --- a/src/infra/heartbeat-wake.ts +++ b/src/infra/heartbeat-wake.ts @@ -37,10 +37,10 @@ function schedule(coalesceMs: number) { pendingReason = reason ?? "retry"; schedule(DEFAULT_RETRY_MS); } - } catch (err) { + } catch { + // Error is already logged by the heartbeat runner; schedule a retry. pendingReason = reason ?? "retry"; schedule(DEFAULT_RETRY_MS); - throw err; } finally { running = false; if (pendingReason || scheduled) schedule(coalesceMs);