Metadata-Version: 2.4
Name: clawdaemons
Version: 0.1.0
Summary: The agent OS. Host AI agents 24/7 across Hermes and Deer Flow.
Project-URL: Homepage, https://clawdos.space/clawdaemons
Project-URL: Documentation, https://clawdos.space/clawdaemons
Project-URL: Source, https://github.com/clawdosdev/clawdaemons
Project-URL: Issues, https://github.com/clawdosdev/clawdaemons/issues
Project-URL: ClawdOS, https://clawdos.space
Author-email: ClawdOS Dev <clawnflip@proton.me>
License: MIT
License-File: LICENSE
Keywords: agent-hosting,agents,ai-os,autonomous-agents,base,clawdos,deer-flow,farcaster,hermes-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: rich>=13.7
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: websockets>=12.0
Provides-Extra: all
Provides-Extra: deerflow
Provides-Extra: dev
Requires-Dist: hatchling>=1.20; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: hermes
Description-Content-Type: text/markdown

# Clawdaemons

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

[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)](https://github.com/clawdosdev/clawdaemons/releases)
[![Status](https://img.shields.io/badge/status-preview-orange.svg)](https://github.com/clawdosdev/clawdaemons)
[![Frameworks](https://img.shields.io/badge/frameworks-hermes%20%2B%20deer--flow-amber.svg)](https://clawdos.space/clawdaemons)

**Clawdaemons** is a hosting framework and runtime for autonomous AI agents. Each agent runs as a
*daemon* inside [ClawdOS](https://clawdos.space) — 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](#why-clawdaemons)
- [Roadmap: Phase 1 / Phase 2](#roadmap-phase-1--phase-2)
- [Install](#install)
- [Quick start](#quick-start)
- [Tool surface](#tool-surface)
- [Wallet modes](#wallet-modes)
- [Daemon manifest](#daemon-manifest)
- [CLI reference](#cli-reference)
- [Architecture](#architecture)
- [Comparison](#comparison)
- [Status](#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

```bash
pip install clawdaemons
```

Or, from source:

```bash
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:

```bash
# 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

```bash
# 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:

```python
# 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

```python
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)

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

### Wallet namespace

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

### Farcaster namespace

```python
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.

```toml
[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](https://github.com/NousResearch)
- Deer Flow bug reports belong upstream at [ByteDance/deer-flow](https://github.com/bytedance/deer-flow)

## License

MIT. See [LICENSE](./LICENSE).

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