clawdaemons 0.1.0

The agent OS. Host AI agents 24/7 across Hermes and Deer Flow.

Clawdaemons

The agent OS. Host AI agents 24/7 across Hermes and Deer Flow.

Clawdaemons is a hosting framework and runtime for autonomous AI agents. Each agent runs as a daemon inside ClawdOS — long-lived, sandboxed, with its own window, files, wallet, and Farcaster identity. Phase 1 hosts your agents on Hermes. Phase 2 stitches them across Hermes and Deer Flow so one daemon can route work to whichever framework fits best.

⚠️ Preview / pre-alpha. APIs may change before v1.0. Treat all daemons as untrusted code.

Not affiliated with Nous Research or ByteDance. Hermes Agent and Deer Flow are MIT-licensed open-source projects. We build against their public plugin interfaces.

---

Table of Contents

• Why Clawdaemons
• Roadmap: Phase 1 / Phase 2
• Install
• Quick start
• Tool surface
• Wallet modes
• Daemon manifest
• CLI reference
• Architecture
• Comparison
• Status

---

Why Clawdaemons

Most agent frameworks borrow their interface from messaging apps: one chat, one user, one bot replying. That model breaks the moment an agent needs to do three things at once, persist context across days, or coordinate with other agents.

ClawdOS is a multi-window environment with a filesystem, taskbar, and onchain identity. Treating each agent as a daemon — a background process with its own window, address space, and wallet — makes more sense than nailing another chat box to the side of the screen.

Clawdaemons gives you the framework to define those daemons, the host bridge to make them talk to ClawdOS, and (Phase 2) the orchestration layer to run them across multiple agent frameworks simultaneously.

---

Roadmap: Phase 1 / Phase 2

Phase 1 · Agent Hosting (shipping)

Long-lived AI agents, hosted as daemons inside ClawdOS.

• 24/7 uptime with auto-restart and daily state snapshots
• Bring-your-own-LLM — Anthropic, OpenAI, OpenRouter, local llama.cpp
• Sandboxed execution — local, Docker, SSH, Singularity, or Modal backends
• Per-daemon onchain wallet on Base, with session-key envelopes
• Optional Farcaster identity for casting and reading
• Live dashboard inside ClawdOS — inspect thoughts, last action, pending plan
• Multi-channel messaging — Telegram, Discord, Slack via Hermes' built-in IM layer
• $COS discount on managed hosting fees (when cloud hosting ships)

Phase 2 · Multi-framework Orchestration (in progress)

A single daemon, two frameworks, organized like a company.

• Department routing — research → Deer Flow, ops → Hermes, treasury → Hermes
• Cross-framework messaging via JSON-RPC 2.0
• Shared filesystem and wallet scoped by capability
• Manifest-driven framework selection — one config flip, no rewrite
• Unified dashboard for the whole team

---

Install

pip install clawdaemons

Or, from source:

pip install git+https://github.com/clawdosdev/clawdaemons.git

Requires Python ≥ 3.11.

Adding the agent frameworks. Hermes Agent and Deer Flow are not yet on PyPI, so the [hermes] and [deerflow] extras are currently no-ops. Install the frameworks from source alongside Clawdaemons:

# Hermes Agent (Phase 1)
pip install git+https://github.com/NousResearch/hermes-agent.git

# Deer Flow (Phase 2)
pip install git+https://github.com/bytedance/deer-flow.git

When upstream publishes to PyPI, we'll pin real versions in the extras.

---

Quick start

# scaffold a new daemon project
clawdaemons new hello-daemon

cd hello-daemon
pip install -e .

# run locally with the mock host (logs intended calls to stderr)
clawdaemons start hello-daemon

# tail logs
clawdaemons logs hello-daemon --follow

# deploy to live ClawdOS hosting (Phase 1)
clawdaemons deploy hello-daemon --host clawdos.space

Minimal daemon:

# hello_daemon/daemon.py
from clawdaemons import Daemon, host

daemon = Daemon(
    name="hello-daemon",
    system_prompt="Greet the user once per hour, briefly.",
    framework="hermes",   # or "deer-flow" in Phase 2
    tick_seconds=3600,
)

@daemon.tool
def write_greeting(text: str) -> str:
    """Open a ClawdOS window with a greeting. Max 200 chars."""
    return host.window.open(
        title="Hello",
        body_html=f"<h1 style='font-family:sans-serif'>{text}</h1>",
        w=400, h=200,
    )

def main() -> None:
    daemon.run()

if __name__ == "__main__":
    main()

---

Tool surface

Twelve tools across four namespaces. Each tool is a plain Python function with a type-annotated signature; the docstring becomes the LLM-facing description.

Window namespace

host.window.open(title, body_html, w=480, h=320) -> window_id
host.window.update(window_id, body_html)
host.window.close(window_id)

Filesystem namespace (sandboxed to the daemon's folder)

host.fs.write(path, content)
host.fs.read(path) -> str
host.fs.list(prefix="") -> list[str]

Wallet namespace

host.wallet.address() -> "0x..."
host.wallet.balance(token="ETH") -> str
host.wallet.request_signature(typed_data) -> hex | UserRejected

Farcaster namespace

host.farcaster.post(text, embeds=None) -> cast_hash
host.farcaster.as_self().post(text)            # daemon's own FID
host.farcaster.recent_casts(fid, limit=25) -> list[dict]

All tools route through the ClawdOS host over JSON-RPC 2.0. When the host is unreachable, calls fall back to a MockHost that prints structured logs to stderr — so you can iterate offline.

---

Wallet modes

Three custody options, scoped per daemon.

Mode	Default?	Behavior
proxy	✅	Daemon proposes, user signs from main wallet. Every action prompts.
session-key	recommended	Scoped allowance (e.g. swap ≤ 0.1 ETH/day, this token only, 7-day expiry). Sign once, daemon runs inside the envelope.
standalone	advanced	Daemon owns a separate EOA. User funds manually. Useful for receiving funds or building onchain history.

Capability declarations in the manifest don't grant access — the host enforces caps independently. Lying in your manifest just means the user gets prompted for permissions you don't end up using.

---

Daemon manifest

Every daemon ships a clawdaemon.toml at its package root.

[daemon]
name         = "hello-daemon"
display_name = "Hello Daemon"
version      = "0.1.0"
description  = "Greets the user once per hour."

[runtime]
framework = "hermes"           # "hermes", "deer-flow", or "multi" (Phase 2)
python    = ">=3.11"
entry     = "hello_daemon.daemon:main"

[capabilities]
windows    = ["open", "close", "update"]
filesystem = ["read:self", "write:self"]
wallet     = ["read"]
farcaster  = ["cast"]
network    = ["https://api.coingecko.com/*"]

[schedule]
cron     = "0 * * * *"
on_event = ["onchain:transfer:in"]

[hosting]
sandbox  = "docker"            # local | docker | ssh | singularity | modal
restart  = "on-failure"
backups  = "daily"

[ui]
default_window = { w = 400, h = 200 }

---

CLI reference

clawdaemons new <name>            Scaffold a new daemon project
clawdaemons install <path>        Register a local daemon
clawdaemons list                  List installed daemons
clawdaemons start <name>          Start a daemon locally
clawdaemons stop <name>           Stop a running daemon
clawdaemons status <name>         Show health and current activity
clawdaemons logs <name> [-f]      Tail logs
clawdaemons deploy <name>         Deploy to managed ClawdOS hosting (Phase 1)
clawdaemons undeploy <name>       Remove from managed hosting

---

Architecture

┌────────────────────────────────────────────────────────────┐
│  ClawdOS Host  (browser / Farcaster mini app)              │
│  Window Manager · Filesystem · Wallet · Farcaster          │
└────────────────────┬───────────────────────────────────────┘
                     │  JSON-RPC 2.0 over WebSocket
┌────────────────────▼───────────────────────────────────────┐
│  Clawdaemons Bridge  (this package)                        │
│  - Tool registry, schema generation                        │
│  - JSON-RPC client + reconnection                          │
│  - Capability enforcement                                  │
│  - MockHost fallback for offline dev                       │
└────────────────────┬───────────────────────────────────────┘
                     │  Framework plugin interface
┌────────────────────▼───────────────────────────────────────┐
│  Phase 1: Hermes Agent (Nous Research, MIT)                │
│  Phase 2: + Deer Flow (ByteDance, MIT) — multi-framework   │
└────────────────────────────────────────────────────────────┘

Each daemon runs in one of Hermes' five sandbox backends (local, Docker, SSH, Singularity, Modal). Production deployments default to Docker.

---

Comparison

	Clawmes	HermesOS	Clawdaemons
Surface	chat (Telegram/Discord)	managed cloud	OS-native daemons
Framework	Hermes only	Hermes only	Hermes + Deer Flow
Onchain identity	optional	none	first-class
Per-agent window	no	no	yes
Persistent filesystem	partial	yes	per-daemon, sandboxed
Farcaster integration	no	no	first-class
Phase 2 orchestration	no	no	yes
Self-hostable	yes	partial	yes
License	MIT	proprietary	MIT

---

Status

Item	Status
Manifest spec (Phase 1)	shipping
Framework + mock host	shipping
CLI scaffolding	shipping
Live JSON-RPC bridge	in progress (v0.2)
Managed cloud hosting	planned (v0.3)
Deer Flow integration (Phase 2)	planned (v0.4)
Multi-framework routing	planned (v0.4)
Frozen v1.0 spec	planned

---

Get involved

• Issues / PRs: https://github.com/clawdosdev/clawdaemons
• Discussion: ClawdOS community
• Hermes-side bug reports belong upstream at Nous Research
• Deer Flow bug reports belong upstream at ByteDance/deer-flow

License

MIT. See LICENSE.

Hermes Agent and Deer Flow are MIT-licensed open-source projects maintained separately. We are not affiliated with Nous Research or ByteDance.