Merge branch 'main' into feat/tools-alsoAllow
This commit is contained in:
Shakker
GitHub
@@ -10,13 +10,14 @@ Status: ready for DM and guild text channels via the official Discord bot gatewa
|
||||
|
||||
## Quick setup (beginner)
|
||||
1) Create a Discord bot and copy the bot token.
|
||||
2) Set the token for Clawdbot:
|
||||
2) In the Discord app settings, enable **Message Content Intent** (and **Server Members Intent** if you plan to use allowlists or name lookups).
|
||||
3) Set the token for Clawdbot:
|
||||
- Env: `DISCORD_BOT_TOKEN=...`
|
||||
- Or config: `channels.discord.token: "..."`.
|
||||
- If both are set, config takes precedence (env fallback is default-account only).
|
||||
3) Invite the bot to your server with message permissions.
|
||||
4) Start the gateway.
|
||||
5) DM access is pairing by default; approve the pairing code on first contact.
|
||||
4) Invite the bot to your server with message permissions (create a private server if you just want DMs).
|
||||
5) Start the gateway.
|
||||
6) DM access is pairing by default; approve the pairing code on first contact.
|
||||
|
||||
Minimal config:
|
||||
```json5
|
||||
|
||||
@@ -26,6 +26,7 @@ Text is supported everywhere; media and reactions vary by channel.
|
||||
- [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
|
||||
- [Nostr](/channels/nostr) — Decentralized DMs via NIP-04 (plugin, installed separately).
|
||||
- [Tlon](/channels/tlon) — Urbit-based messenger (plugin, installed separately).
|
||||
- [Twitch](/channels/twitch) — Twitch chat via IRC connection (plugin, installed separately).
|
||||
- [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).
|
||||
- [Zalo Personal](/channels/zalouser) — Zalo personal account via QR login (plugin, installed separately).
|
||||
- [WebChat](/web/webchat) — Gateway WebChat UI over WebSocket.
|
||||
|
||||
366
docs/channels/twitch.md
Normal file
366
docs/channels/twitch.md
Normal file
@@ -0,0 +1,366 @@
|
||||
---
|
||||
summary: "Twitch chat bot configuration and setup"
|
||||
read_when:
|
||||
- Setting up Twitch chat integration for Clawdbot
|
||||
---
|
||||
# Twitch (plugin)
|
||||
|
||||
Twitch chat support via IRC connection. Clawdbot connects as a Twitch user (bot account) to receive and send messages in channels.
|
||||
|
||||
## Plugin required
|
||||
|
||||
Twitch ships as a plugin and is not bundled with the core install.
|
||||
|
||||
Install via CLI (npm registry):
|
||||
|
||||
```bash
|
||||
clawdbot plugins install @clawdbot/twitch
|
||||
```
|
||||
|
||||
Local checkout (when running from a git repo):
|
||||
|
||||
```bash
|
||||
clawdbot plugins install ./extensions/twitch
|
||||
```
|
||||
|
||||
Details: [Plugins](/plugin)
|
||||
|
||||
## Quick setup (beginner)
|
||||
|
||||
1) Create a dedicated Twitch account for the bot (or use an existing account).
|
||||
2) Generate credentials: [Twitch Token Generator](https://twitchtokengenerator.com/)
|
||||
- Select **Bot Token**
|
||||
- Verify scopes `chat:read` and `chat:write` are selected
|
||||
- Copy the **Client ID** and **Access Token**
|
||||
3) Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
|
||||
4) Configure the token:
|
||||
- Env: `CLAWDBOT_TWITCH_ACCESS_TOKEN=...` (default account only)
|
||||
- Or config: `channels.twitch.accessToken`
|
||||
- If both are set, config takes precedence (env fallback is default-account only).
|
||||
5) Start the gateway.
|
||||
|
||||
**⚠️ Important:** Add access control (`allowFrom` or `allowedRoles`) to prevent unauthorized users from triggering the bot. `requireMention` defaults to `true`.
|
||||
|
||||
Minimal config:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
enabled: true,
|
||||
username: "clawdbot", // Bot's Twitch account
|
||||
accessToken: "oauth:abc123...", // OAuth Access Token (or use CLAWDBOT_TWITCH_ACCESS_TOKEN env var)
|
||||
clientId: "xyz789...", // Client ID from Token Generator
|
||||
channel: "vevisk", // Which Twitch channel's chat to join (required)
|
||||
allowFrom: ["123456789"] // (recommended) Your Twitch user ID only - get it from https://www.streamweasels.com/tools/convert-twitch-username-to-user-id/
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## What it is
|
||||
|
||||
- A Twitch channel owned by the Gateway.
|
||||
- Deterministic routing: replies always go back to Twitch.
|
||||
- Each account maps to an isolated session key `agent:<agentId>:twitch:<accountName>`.
|
||||
- `username` is the bot's account (who authenticates), `channel` is which chat room to join.
|
||||
|
||||
## Setup (detailed)
|
||||
|
||||
### Generate credentials
|
||||
|
||||
Use [Twitch Token Generator](https://twitchtokengenerator.com/):
|
||||
- Select **Bot Token**
|
||||
- Verify scopes `chat:read` and `chat:write` are selected
|
||||
- Copy the **Client ID** and **Access Token**
|
||||
|
||||
No manual app registration needed. Tokens expire after several hours.
|
||||
|
||||
### Configure the bot
|
||||
|
||||
**Env var (default account only):**
|
||||
```bash
|
||||
CLAWDBOT_TWITCH_ACCESS_TOKEN=oauth:abc123...
|
||||
```
|
||||
|
||||
**Or config:**
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
enabled: true,
|
||||
username: "clawdbot",
|
||||
accessToken: "oauth:abc123...",
|
||||
clientId: "xyz789...",
|
||||
channel: "vevisk"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If both env and config are set, config takes precedence.
|
||||
|
||||
### Access control (recommended)
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
|
||||
allowedRoles: ["moderator"] // Or restrict to roles
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Available roles:** `"moderator"`, `"owner"`, `"vip"`, `"subscriber"`, `"all"`.
|
||||
|
||||
**Why user IDs?** Usernames can change, allowing impersonation. User IDs are permanent.
|
||||
|
||||
Find your Twitch user ID: https://www.streamweasels.com/tools/convert-twitch-username-%20to-user-id/ (Convert your Twitch username to ID)
|
||||
|
||||
## Token refresh (optional)
|
||||
|
||||
Tokens from [Twitch Token Generator](https://twitchtokengenerator.com/) cannot be automatically refreshed - regenerate when expired.
|
||||
|
||||
For automatic token refresh, create your own Twitch application at [Twitch Developer Console](https://dev.twitch.tv/console) and add to config:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
clientSecret: "your_client_secret",
|
||||
refreshToken: "your_refresh_token"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The bot automatically refreshes tokens before expiration and logs refresh events.
|
||||
|
||||
## Multi-account support
|
||||
|
||||
Use `channels.twitch.accounts` with per-account tokens. See [`gateway/configuration`](/gateway/configuration) for the shared pattern.
|
||||
|
||||
Example (one bot account in two channels):
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
accounts: {
|
||||
channel1: {
|
||||
username: "clawdbot",
|
||||
accessToken: "oauth:abc123...",
|
||||
clientId: "xyz789...",
|
||||
channel: "vevisk"
|
||||
},
|
||||
channel2: {
|
||||
username: "clawdbot",
|
||||
accessToken: "oauth:def456...",
|
||||
clientId: "uvw012...",
|
||||
channel: "secondchannel"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Each account needs its own token (one token per channel).
|
||||
|
||||
## Access control
|
||||
|
||||
### Role-based restrictions
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
accounts: {
|
||||
default: {
|
||||
allowedRoles: ["moderator", "vip"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Allowlist by User ID (most secure)
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
accounts: {
|
||||
default: {
|
||||
allowFrom: ["123456789", "987654321"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Combined allowlist + roles
|
||||
|
||||
Users in `allowFrom` bypass role checks:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
accounts: {
|
||||
default: {
|
||||
allowFrom: ["123456789"],
|
||||
allowedRoles: ["moderator"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Disable @mention requirement
|
||||
|
||||
By default, `requireMention` is `true`. To disable and respond to all messages:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
accounts: {
|
||||
default: {
|
||||
requireMention: false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
First, run diagnostic commands:
|
||||
|
||||
```bash
|
||||
clawdbot doctor
|
||||
clawdbot channels status --probe
|
||||
```
|
||||
|
||||
### Bot doesn't respond to messages
|
||||
|
||||
**Check access control:** Temporarily set `allowedRoles: ["all"]` to test.
|
||||
|
||||
**Check the bot is in the channel:** The bot must join the channel specified in `channel`.
|
||||
|
||||
### Token issues
|
||||
|
||||
**"Failed to connect" or authentication errors:**
|
||||
- Verify `accessToken` is the OAuth access token value (typically starts with `oauth:` prefix)
|
||||
- Check token has `chat:read` and `chat:write` scopes
|
||||
- If using token refresh, verify `clientSecret` and `refreshToken` are set
|
||||
|
||||
### Token refresh not working
|
||||
|
||||
**Check logs for refresh events:**
|
||||
```
|
||||
Using env token source for mybot
|
||||
Access token refreshed for user 123456 (expires in 14400s)
|
||||
```
|
||||
|
||||
If you see "token refresh disabled (no refresh token)":
|
||||
- Ensure `clientSecret` is provided
|
||||
- Ensure `refreshToken` is provided
|
||||
|
||||
## Config
|
||||
|
||||
**Account config:**
|
||||
- `username` - Bot username
|
||||
- `accessToken` - OAuth access token with `chat:read` and `chat:write`
|
||||
- `clientId` - Twitch Client ID (from Token Generator or your app)
|
||||
- `channel` - Channel to join (required)
|
||||
- `enabled` - Enable this account (default: `true`)
|
||||
- `clientSecret` - Optional: For automatic token refresh
|
||||
- `refreshToken` - Optional: For automatic token refresh
|
||||
- `expiresIn` - Token expiry in seconds
|
||||
- `obtainmentTimestamp` - Token obtained timestamp
|
||||
- `allowFrom` - User ID allowlist
|
||||
- `allowedRoles` - Role-based access control (`"moderator" | "owner" | "vip" | "subscriber" | "all"`)
|
||||
- `requireMention` - Require @mention (default: `true`)
|
||||
|
||||
**Provider options:**
|
||||
- `channels.twitch.enabled` - Enable/disable channel startup
|
||||
- `channels.twitch.username` - Bot username (simplified single-account config)
|
||||
- `channels.twitch.accessToken` - OAuth access token (simplified single-account config)
|
||||
- `channels.twitch.clientId` - Twitch Client ID (simplified single-account config)
|
||||
- `channels.twitch.channel` - Channel to join (simplified single-account config)
|
||||
- `channels.twitch.accounts.<accountName>` - Multi-account config (all account fields above)
|
||||
|
||||
Full example:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
twitch: {
|
||||
enabled: true,
|
||||
username: "clawdbot",
|
||||
accessToken: "oauth:abc123...",
|
||||
clientId: "xyz789...",
|
||||
channel: "vevisk",
|
||||
clientSecret: "secret123...",
|
||||
refreshToken: "refresh456...",
|
||||
allowFrom: ["123456789"],
|
||||
allowedRoles: ["moderator", "vip"],
|
||||
accounts: {
|
||||
default: {
|
||||
username: "mybot",
|
||||
accessToken: "oauth:abc123...",
|
||||
clientId: "xyz789...",
|
||||
channel: "your_channel",
|
||||
enabled: true,
|
||||
clientSecret: "secret123...",
|
||||
refreshToken: "refresh456...",
|
||||
expiresIn: 14400,
|
||||
obtainmentTimestamp: 1706092800000,
|
||||
allowFrom: ["123456789", "987654321"],
|
||||
allowedRoles: ["moderator"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Tool actions
|
||||
|
||||
The agent can call `twitch` with action:
|
||||
- `send` - Send a message to a channel
|
||||
|
||||
Example:
|
||||
|
||||
```json5
|
||||
{
|
||||
"action": "twitch",
|
||||
"params": {
|
||||
"message": "Hello Twitch!",
|
||||
"to": "#mychannel"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Safety & ops
|
||||
|
||||
- **Treat tokens like passwords** - Never commit tokens to git
|
||||
- **Use automatic token refresh** for long-running bots
|
||||
- **Use user ID allowlists** instead of usernames for access control
|
||||
- **Monitor logs** for token refresh events and connection status
|
||||
- **Scope tokens minimally** - Only request `chat:read` and `chat:write`
|
||||
- **If stuck**: Restart the gateway after confirming no other process owns the session
|
||||
|
||||
## Limits
|
||||
|
||||
- **500 characters** per message (auto-chunked at word boundaries)
|
||||
- Markdown is stripped before chunking
|
||||
- No rate limiting (uses Twitch's built-in rate limits)
|
||||
@@ -23,3 +23,4 @@ clawdbot onboard --mode remote --remote-url ws://gateway-host:18789
|
||||
Flow notes:
|
||||
- `quickstart`: minimal prompts, auto-generates a gateway token.
|
||||
- `manual`: full prompts for port/bind/auth (alias of `advanced`).
|
||||
- Fastest first chat: `clawdbot dashboard` (Control UI, no channel setup).
|
||||
|
||||
@@ -43,6 +43,18 @@ Start with the smallest access that still works, then widen it as you gain confi
|
||||
|
||||
If you run `--deep`, Clawdbot also attempts a best-effort live Gateway probe.
|
||||
|
||||
## Credential storage map
|
||||
|
||||
Use this when auditing access or deciding what to back up:
|
||||
|
||||
- **WhatsApp**: `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
|
||||
- **Discord bot token**: config/env (token file not yet supported)
|
||||
- **Slack tokens**: config/env (`channels.slack.*`)
|
||||
- **Pairing allowlists**: `~/.clawdbot/credentials/<channel>-allowFrom.json`
|
||||
- **Model auth profiles**: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **Legacy OAuth import**: `~/.clawdbot/credentials/oauth.json`
|
||||
|
||||
## Security Audit Checklist
|
||||
|
||||
When the audit prints findings, treat this as a priority order:
|
||||
@@ -199,6 +211,7 @@ Even with strong system prompts, **prompt injection is not solved**. What helps
|
||||
- Prefer mention gating in groups; avoid “always-on” bots in public rooms.
|
||||
- Treat links, attachments, and pasted instructions as hostile by default.
|
||||
- Run sensitive tool execution in a sandbox; keep secrets out of the agent’s reachable filesystem.
|
||||
- Note: sandboxing is opt-in; if sandbox mode is off, exec runs on the gateway host even though tools.exec.host defaults to sandbox.
|
||||
- Limit high-risk tools (`exec`, `browser`, `web_fetch`, `web_search`) to trusted agents or explicit allowlists.
|
||||
- **Model choice matters:** older/legacy models can be less robust against prompt injection and tool misuse. Prefer modern, instruction-hardened models for any bot with tools. We recommend Anthropic Opus 4.5 because it’s quite good at recognizing prompt injections (see [“A step forward on safety”](https://www.anthropic.com/news/claude-opus-4-5)).
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
291
docs/platforms/oracle.md
Normal file
291
docs/platforms/oracle.md
Normal file
@@ -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.<tailnet-name>.ts.net/
|
||||
```
|
||||
|
||||
Replace `<tailnet-name>` 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
|
||||
@@ -9,6 +9,10 @@ read_when:
|
||||
|
||||
Goal: go from **zero** → **first working chat** (with sane defaults) as quickly as possible.
|
||||
|
||||
Fastest chat: open the Control UI (no channel setup needed). Run `clawdbot dashboard`
|
||||
and chat in the browser, or open `http://127.0.0.1:18789/` on the gateway host.
|
||||
Docs: [Dashboard](/web/dashboard) and [Control UI](/web/control-ui).
|
||||
|
||||
Recommended path: use the **CLI onboarding wizard** (`clawdbot onboard`). It sets up:
|
||||
- model/auth (OAuth recommended)
|
||||
- gateway settings
|
||||
@@ -121,6 +125,7 @@ channels. If you use WhatsApp or Telegram, run the Gateway with **Node**.
|
||||
```bash
|
||||
clawdbot status
|
||||
clawdbot health
|
||||
clawdbot security audit --deep
|
||||
```
|
||||
|
||||
## 4) Pair + connect your first chat surface
|
||||
|
||||
@@ -104,6 +104,19 @@ clawdbot health
|
||||
- Sessions: `~/.clawdbot/agents/<agentId>/sessions/`
|
||||
- Logs: `/tmp/clawdbot/`
|
||||
|
||||
## Credential storage map
|
||||
|
||||
Use this when debugging auth or deciding what to back up:
|
||||
|
||||
- **WhatsApp**: `~/.clawdbot/credentials/whatsapp/<accountId>/creds.json`
|
||||
- **Telegram bot token**: config/env or `channels.telegram.tokenFile`
|
||||
- **Discord bot token**: config/env (token file not yet supported)
|
||||
- **Slack tokens**: config/env (`channels.slack.*`)
|
||||
- **Pairing allowlists**: `~/.clawdbot/credentials/<channel>-allowFrom.json`
|
||||
- **Model auth profiles**: `~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`
|
||||
- **Legacy OAuth import**: `~/.clawdbot/credentials/oauth.json`
|
||||
More detail: [Security](/gateway/security#credential-storage-map).
|
||||
|
||||
## Updating (without wrecking your setup)
|
||||
|
||||
- Keep `~/clawd` and `~/.clawdbot/` as “your stuff”; don’t put personal prompts/config into the `clawdbot` repo.
|
||||
|
||||
@@ -18,6 +18,9 @@ Primary entrypoint:
|
||||
clawdbot onboard
|
||||
```
|
||||
|
||||
Fastest first chat: open the Control UI (no channel setup needed). Run
|
||||
`clawdbot dashboard` and chat in the browser. Docs: [Dashboard](/web/dashboard).
|
||||
|
||||
Follow‑up reconfiguration:
|
||||
|
||||
```bash
|
||||
|
||||
@@ -64,6 +64,14 @@ By default, `clawdhub` installs into `./skills` under your current working
|
||||
directory (or falls back to the configured Clawdbot workspace). Clawdbot picks
|
||||
that up as `<workspace>/skills` on the next session.
|
||||
|
||||
## Security notes
|
||||
|
||||
- Treat third-party skills as **trusted code**. Read them before enabling.
|
||||
- Prefer sandboxed runs for untrusted inputs and risky tools. See [Sandboxing](/gateway/sandboxing).
|
||||
- `skills.entries.*.env` and `skills.entries.*.apiKey` inject secrets into the **host** process
|
||||
for that agent turn (not the sandbox). Keep secrets out of prompts and logs.
|
||||
- For a broader threat model and checklists, see [Security](/gateway/security).
|
||||
|
||||
## Format (AgentSkills + Pi-compatible)
|
||||
|
||||
`SKILL.md` must include at least:
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -19,6 +19,10 @@ Key references:
|
||||
Authentication is enforced at the WebSocket handshake via `connect.params.auth`
|
||||
(token or password). See `gateway.auth` in [Gateway configuration](/gateway/configuration).
|
||||
|
||||
Security note: the Control UI is an **admin surface** (chat, config, exec approvals).
|
||||
Do not expose it publicly. The UI stores the token in `localStorage` after first load.
|
||||
Prefer localhost, Tailscale Serve, or an SSH tunnel.
|
||||
|
||||
## Fast path (recommended)
|
||||
|
||||
- After onboarding, the CLI now auto-opens the dashboard with your token and prints the same tokenized link.
|
||||
|
||||
Reference in New Issue
Block a user