clawd_platform

KO | EN

gitlite — search

#python #hacktoberfest #typescript #go #golang #android #machine-learning #macos #windows #kubernetes #awesome-list #pytorch #mcp #open-source

(★ 9)

One-click platform to deploy your own autonomous OpenClaw AI agent to Telegram — it rents and configures the server for you.

clawd_platform Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# OpenClaw SaaS

> **Deploy your own autonomous AI agent to Telegram in one click — the platform buys the server for you.**

OpenClaw SaaS is an open-source platform that turns a multi-step DevOps chore into a single form submission. A user describes the bot they want, and the platform automatically **provisions a cloud VPS, configures it over SSH, deploys a Dockerized [OpenClaw](#what-is-openclaw) agent, and hands back a live, working AI assistant** — no terminal, no SSH keys, no Docker knowledge required.

---

## Table of Contents

- [The Problem](#the-problem)
- [What is OpenClaw?](#what-is-openclaw)
- [How It Works](#how-it-works)
- [The Provisioning Pipeline](#the-provisioning-pipeline)
- [Features](#features)
- [Tech Stack](#tech-stack)
- [Architecture](#architecture)
- [Engineering Highlights](#engineering-highlights)
- [Getting Started](#getting-started)
- [Environment Variables](#environment-variables)
- [Project Structure](#project-structure)
- [API Overview](#api-overview)
- [License](#license)

---

## The Problem

Self-hosting an autonomous AI agent is genuinely useful — it runs 24/7, connects to your messengers, and *acts* on your behalf. But getting one online today means:

1. Renting a VPS and configuring networking (IPv4/IPv6, firewall).
2. SSH-ing in, installing Docker, writing `docker-compose.yml` and config files.
3. Wrangling tokens, environment variables, and file permissions.
4. Keeping the container alive and debugging when it doesn't boot.

That's a half-day of DevOps for something that should take 60 seconds. **OpenClaw SaaS removes every step between "I want a bot" and "my bot is live."** You fill out one form; the platform does the rest — including renting the server.

## What is OpenClaw?

[OpenClaw](https://github.com/openclaw/openclaw) is an open-source **autonomous AI agent** that runs continuously on a server and connects to messengers (Telegram, WhatsApp, Slack, Discord, and more). Unlike a chatbot that only answers questions, OpenClaw *takes real actions* — sending messages, running scheduled tasks, browsing the web, managing files, and proactively reaching out via a built-in heartbeat loop. It supports many LLM backends (Claude, GPT, Gemini, local models via Ollama).

This project is **not** OpenClaw itself — it's the **one-click hosting layer** on top of it.

## How It Works

From the user's perspective, it's three steps:

```
┌──────────────┐      ┌──────────────┐      ┌──────────────────────┐
│ 1. Configure │ ───▶ │  2. Checkout │ ───▶ │  3. Auto-Deployment  │
│              │      │              │      │                      │
│ Bot name,    │      │ Pick a plan  │      │ Server is rented &   │
│ Telegram     │      │ & pay        │      │ configured for you;  │
│ token, model │      │              │      │ bot goes live in     │
│              │      │              │      │ ~minutes             │
└──────────────┘      └──────────────┘      └──────────────────────┘
```

Behind that simple flow, the backend runs a full infrastructure-as-code pipeline.

## The Provisioning Pipeline

When a user creates a bot, the API returns immediately and a background worker takes over. Everything below happens automatically and asynchronously:

```
POST /api/v1/bots
      │
      ▼
┌───────────────────────────────────────────────────────────────────────┐
│  Bot (status: deploying)  +  DeployTask (status: queued)  → Postgres   │
└───────────────────────────────────────────────────────────────────────┘
      │
      ▼   Async worker polls the queue (SELECT ... FOR UPDATE SKIP LOCKED)
      │   up to N tasks processed concurrently
      ▼
  ┌─────────────────────────────────────────────────────────────────┐
  │ 1. Create VPS on Timeweb Cloud (SSH key injected at boot)        │
  │ 2. Attach a public IPv4 (NL region ships IPv6-only by default)   │
  │ 3. Poll until the server reports status = "on"                   │
  │ 4. SSH in (with retry/backoff): install Docker, upload           │
  │    openclaw.json + .env + docker-compose.yml, fix permissions    │
  │ 5. docker compose pull && docker compose up -d                   │
  └─────────────────────────────────────────────────────────────────┘
      │
      ├── success ──▶  Bot → "active"   (user has a live agent)
      │
      └── failure ──▶  Bot → "error", VPS destroyed (no orphaned billing),
                       a sanitized, human-readable reason saved to the task log
```

Key design choices in this pipeline:

- **Crash-safe queue** — tasks are claimed with `FOR UPDATE SKIP LOCKED`, so multiple worker loops never grab the same job, and an unfinished job can be retried.
- **Self-healing cleanup** — if anything fails, the half-built server is deleted automatically so the user is never billed for a broken deploy.
- **Bounded concurrency** — the worker runs up to `WORKER_MAX_CONCURRENT` deploys in parallel via `asyncio`, with available-slot accounting.
- **Resilient SSH** — connecting to a freshly booted VM is flaky, so SSH setup uses retry-with-delay until the box accepts the key.

## Features

**For users**
- 🚀 **One-click deployment** — go from a form to a running Telegram agent in minutes.
- 🖥️ **Zero infrastructure knowledge needed** — the platform rents and configures the server for you.
- 🤖 **AI onboarding guide** — a 4-step quiz generates a *personalized strategy* (with copy-paste prompts) for what to automate first, powered by an LLM with structured outputs.
- 📊 **Dashboard** — create, monitor (live status: deploying / active / error), reconfigure, and delete bots.
- 👤 **Profile & history** — every onboarding session is saved and revisitable.
- 🔐 **Email/password auth** via Supabase.

**For engineers (under the hood)**
- ⚙️ Fully **async** backend (FastAPI + asyncpg + asyncssh + httpx) — no blocking I/O.
- 🧱 **SOLID / DI** — cloud provider, SSH configurator, and LLM provider all sit behind interfaces and are injected via FastAPI `Depends`.
- 🔒 **Secrets encrypted at rest** — Telegram tokens and SSH passwords are Fernet-encrypted before touching the database.
- 🛡️ **Defense in depth** — strict input validation (regex-constrained tokens/models), JWT verification (ES256 / JWKS with TTL cache), per-IP rate limiting, shell-injection guards on remote paths, and log sanitization that strips secrets from stack traces.
- 🔁 **Observability** — request-ID middleware (`X-Request-ID` propagation) and `/health` + `/health/worker` endpoints exposing live worker metrics.

## Tech Stack

| Layer | Technologies |
|---|---|
| **Frontend** | Next.js 16 (App Router), React 19, TypeScript (strict), Tailwind CSS v4, Redux Toolkit |
| **Backend** | FastAPI, Python 3.13, SQLModel / SQLAlchemy (async), Pydantic v2 |
| **Database** | PostgreSQL (async via `asyncpg`), JSONB bot configs |
| **Auth** | Supabase (email/password on the client; JWT verification on the server) |
| **Infrastructure** | Timeweb Cloud API (VPS provisioning), `asyncssh` (remote config), Docker (bot runtime) |
| **AI** | OpenAI SDK with Structured Outputs (onboarding strategy generation) |
| **Tooling** | Ruff (lint/format), ESLint, `uv` / `pip`, Turbopack |

## Architecture

A monorepo with two independently deployable apps:

```
openclaw-saas/
├── frontend/          # Next.js 16 web app (landing, dashboard, AI guide, profile)
│   ├── app/
│   │   ├── (pages)/   # Routes: /, /auth, /bots, /bots/[id], /ai-guide, /profile, /checkout
│   │   ├── components/ # Feature-organized UI (auth, dashboard, ai-guide, main, ...)
│   │   └── shared/    # Reusable hooks, UI primitives, SVG assets
│   ├── store/         # Redux Toolkit slices (userSlice, botsSlice)
│   └── lib/           # API client, Supabase client, helpers
│
├── backend/           # FastAPI API + background provisioning worker
│   └── app/
│       ├── api/v1/    # Versioned REST endpoints + auth/rate-limit dependencies
│       ├── core/      # Config, security (JWKS), encryption, logging, retry
│       ├── db/        # Async engine + SQLModel models (Bot, Server, DeployTask, ...)
│       ├── provisioner/  # The deploy pipeline: Timeweb client, SSH configurator, worker
│       ├── services/  # Business logic + LLM provider (interfaces + implementations)
│       ├── schemas/   # Pydantic request/response models with strict validation
│       └── prompts/   # LLM system prompt + knowledge base
│
└── docs/              # Internal specs & the Timeweb API reference
```

The frontend never talks to cloud or SSH — it only calls the backend's REST API. All infrastructure orchestration is isolated in `backend/app/provisioner/`, behind interfaces (`ICloudProvider`, `IServerConfigurator`) so the cloud provider could be swapped without touching the rest of the system.

## Engineering Highlights

A few things in this codebase that go beyond a typical CRUD app:

- **Background job system without a broker** — a Postgres-backed queue using `SELECT ... FOR UPDATE SKIP LOCKED` gives reliable, concurrent, crash-safe task processing using only the database already in the stack.
- **Real infrastructure automation** — the platform programmatically rents servers, manages IP allocation, and configures Linux boxes over SSH/SFTP, then deploys containers — a complete infra-as-code flow triggered by an HTTP request.
- **Security-conscious by default** — encryption at rest, JWKS-based JWT verification with caching, regex-validated inputs, injection-safe remote paths, and stack-trace sanitization so secrets never leak into logs.
- **Clean async architecture** — every layer (HTTP, DB, SSH, cloud API, LLM) is async; dependency-inverted interfaces keep the provisioning logic testable and provider-agnostic.
- **Thoughtful UX details** — token kept in a ref to avoid refetch storms on Supabase token refresh, per-operation Redux status/error fields, and an AI guide that meaningfully personalizes onboarding instead of showing static docs.

## Getting Started

### Prerequisites

- **Node.js** 20+ and **Python** 3.13+
- A **PostgreSQL** database
- A **Supabase** project (for auth)
- An **OpenAI** API key (for the AI onboarding guide)
- A **Timeweb Cloud** API token + SSH key *(only needed to actually provision servers)*

### 1. Backend

```bash
cd backend
cp .env.example .env          # then fill in the values (see below)
pip install -e .              # or: uv sync
python -m uvicorn app.main:app --reload   # → http://localhost:8000
```

Generate the encryption key required in `.env`:

```bash
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
```

### 2. Frontend

```bash
cd frontend
cp .env.example .env          # then fill in the values
npm install
npm run dev                   # → http://localhost:5001
```

Open **http://localhost:5001** and you're up. The AI onboarding guide works without provisioning; deploying a live bot additionally requires valid Timeweb credentials.

### Linting

```bash
# backend
ruff check app/ && ruff format app/
# frontend
npm run lint
```

## Environment Variables

### Backend (`backend/.env`)

| Variable | Description |
|---|---|
| `SUPABASE_URL`, `SUPABASE_JWT_SECRET` | Supabase auth / JWT verification |
| `DATABASE_URL` | PostgreSQL DSN (`postgresql+asyncpg://...`) |
| `ENCRYPTION_KEY` | Fernet key for encrypting secrets at rest |
| `OPEN_AI_API_KEY` | OpenAI key for onboarding strategy generation |
| `TIMEWEB_API_TOKEN`, `SSH_PRIVATE_KEY_PATH` | VPS provisioning + SSH access |
| `WORKER_POLL_INTERVAL`, `WORKER_MAX_CONCURRENT` | Worker tuning (defaults: 5s, 5 concurrent) |
| `SSH_MAX_RETRIES`, `SSH_RETRY_DELAY` | SSH connection resilience (defaults: 10, 5s) |
| `ONBOARDING_LLM_MODEL`, `ONBOARDING_RATE_LIMIT` | LLM model + per-IP rate limit |

### Frontend (`frontend/.env`)

| Variable | Description |
|---|---|
| `NEXT_PUBLIC_SUPABASE_URL`, `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase client credentials |
| `NEXT_PUBLIC_API_URL` | Backend base URL (default `http://localhost:8000`) |

> The UI text and validation messages are in **Russian** (the product's target audience), while the codebase and APIs are in English.

## API Overview

All endpoints are versioned under `/api/v1`.

| Method | Endpoint | Description |
|---|---|---|
| `POST` | `/bots` | Create a bot → queues an async deploy |
| `GET` | `/bots` | List the current user's bots (with status counts) |
| `GET` | `/bots/{id}` | Bot detail: config, server info, latest deploy log |
| `PATCH` | `/bots/{id}` | Update bot config |
| `DELETE` | `/bots/{id}` | Delete bot + best-effort destroy the VPS |
| `POST` | `/onboarding/strategy` | Generate a personalized strategy (optional auth, rate-limited) |
| `GET` | `/onboarding/sessions` | Paginated history of a user's onboarding sessions |
| `GET` | `/health`, `/health/worker` | Liveness + live worker metrics |

Interactive API docs are auto-generated by FastAPI at **`/docs`** when the backend is running.

## License

This project is open source. *(Add a `LICENSE` file — e.g. MIT — to make the terms explicit.)*

---

Built with FastAPI, Next.js, and a lot of async. ⚡ 
 OpenClaw is a separate open-source project; this repository is the self-hosting platform around it.

clawd_platform

clawd_platform Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

clawd_platform

clawd_platform Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README