clodbot is an open source personal AI assistant that you run on your own hardware. It connects big language models from providers like Anthropic and OpenAI to real tools like messaging apps, files, shells, browsers, and smart home devices, while keeping the orchestration layer under your control.
Interesting thing isn’t it clodbot chat. That is, the project ships a concrete architecture for local first agents and a typed workflow engine called Lobster that turns model calls into deterministic pipelines.
Architecture: Gateways, Nodes and Skills
At the heart of Cloudbot is the gateway process. Gateway exposes a WebSocket control plane ws://127.0.0.1:18789 and a local HTTP interface for the control UI and web chat.
Your messages from WhatsApp, Telegram, Signal, Slack, Discord, iMessage, and other channels are delivered to the gateway. The gateway decides which agent should handle the message, which tools should be called, and which model provider should be used. After this it sends a reply on the same channel.
The runtime is divided into a few main concepts:
- door: Routing, Model Call, Tool Invocation, Session, Presence and Scheduling.
- nodes: Processes that provide Cloudbot access to local resources such as the file system, browser automation, microphone, camera, or platform specific APIs on macOS, Windows, Linux, iOS, and Android.
- channel: Integrations for chat systems like WhatsApp, Telegram, Discord, Slack, Signal, Microsoft Teams, Matrix, Zalo and more. These are configured as channel backends that connect to the gateway.
- Skills and Plugins: tools that the agent can call, described in a standard
SKILL.mdFormatted and distributed via ClawdHub.
This separation lets you run the gateway on a five-dollar virtual server or a spare machine at home, while keeping heavy model computations on a remote API or local model backend when needed.
skills and SKILL.md Standard
ClodBot uses an open skill format as described in SKILL.md. A skill is defined in Markdown with a small header and a serialized process. For example, a deployment skill can specify steps such as checking git status, running tests, and deploying only after success.
---
name: deploy-production
description: Deploy the current branch to production. Use only after tests pass.
disable-model-invocation: true
---
1. Check git status ensuring clean working directory.
2. Run `npm test`
3. If tests pass, run `npm run deploy`
The gateway reads these definitions and exposes them to agents as devices with clear capabilities and security constraints. Skills are published on CloudHub and can be installed or compiled into larger workflows.
This means that operational runbooks can move from ad-hoc wiki pages to machine executable skills while still being auditable as text.
Lobster: Typed Workflow Runtime for Agents
Lobster is the workflow runtime that powers native Lobster and many advanced Clodbot automations. It is described as a typed workflow shell that lets Clodbot run multi step tool sequences as a single deterministic operation with explicit approval gates.
Instead of making the model call multiple tools in a loop, Lobster moves the orchestration into a small domain specific runtime:
- Pipelines are defined as compact shells such as JSON or YAML, or pipeline strings.
- Exchange typed JSON data, not unstructured text.
- The runtime enforces timeouts, output limits, and sandbox policies.
- Workflow can pause on side effects and resume later
resumeToken.
A simple inbox triage workflow looks like this:
name: inbox-triage
steps:
- id: collect
command: inbox list --json
- id: categorize
command: inbox categorize --json
stdin: $collect.stdout
- id: approve
command: inbox apply --approve
stdin: $categorize.stdout
approval: required
- id: execute
command: inbox apply --execute
stdin: $categorize.stdout
condition: $approve.approved
Clodbot treats this file as a skill. When you ask it to clean up your inbox, it calls a Lobster pipeline instead of improvising multiple tool calls. model dictates When? How to run the pipeline and with what parameters, but the pipeline itself remains deterministic and auditable.
Local Lobster is a reference agent that uses Lobster to run local workflows and is described in coverage as an open source agent that redefines personal AI by combining local first workflows with proactive behavior.
active local first behavior
One of the major reasons why Cloudbot is trending and visible in the X and developer communities is that it behaves like an operator and not just a chat window.
Because the gateway can run scheduled tasks and track state throughout the session, common patterns include:
- Daily briefing that summarizes calendars, tasks, and important mail.
- Periodic recaps such as task summaries sent weekly.
- Monitors that keep an eye on conditions then send you messages on your preferred channel to be the first to do so.
- File and repository automation that runs locally but is triggered by natural language.
This all runs on your machine or server with routing and tool policies. Model calls still go to providers like Anthropic, OpenAI, Google, XAI, or the local backend, but the supporting brain, memory, and integration are under your control.
Installation and developer workflow
The project provides a one line installer that receives a script clawd.bot And bootstrap nodes, gateways and core components. For more control, you can install via npm or clone the TypeScript repository and build with pnpm.
Typical Steps:
curl -fsSL https://clawd.bot/install.sh | bash
# or
npm i -g clawdbot
clawdbot onboard
After onboarding you join a channel like Telegram or WhatsApp, choose a model provider and enable the skill. From there you can write your own SKILL.md Create files, Lobster workflows, and display them through chat, web chat, or the macOS companion app.
some examples
Michael Sutter is a data science professional and holds a Master of Science in Data Science from the University of Padova. With a solid foundation in statistical analysis, machine learning, and data engineering, Michael excels in transforming complex datasets into actionable insights.
