Skip to content

README.md

Latest commit

 

History

History
178 lines (142 loc) · 6.11 KB

README.md

File metadata and controls

178 lines (142 loc) · 6.11 KB

clawlab

local multi-agent setup

works on: macOS | Linux | WSL
docs: home | config | infra

powered by: openclaw | picoclaw | zeroclaw | nanobot | nullclaw | hermes | moltis | mercury

intro

  • manage multiple agents as plain directories in a single repo
  • bootstrap and command multiple unrelated agents in a unified way
  • forward native agent commands directly (help, onboard, status, --tui, etc.)
  • customize the templates freely; bundled agents and services are examples

recommended host setup

  • run managed agents and shared services under a dedicated agent user
  • clone into the shared host path and make it writable by your user
  • create infra/host.env file and run ./cmd infra bootstrap

structure

  • agents/ holds agent instances: one working directory per agent
  • config/ shared definitions: agent kinds, host aliases, shared-service manifests, ports
  • infra/ machine bootstrap and service supervision for Linux/macOS
  • shared/ shared space across agents (e.g. content, knowledge, skills, etc.)
  • cmd unified CLI for agents and infra commands

example agents/ tree with two instances per supported kind:

agents/
├── 001-openclaw/
├── 002-openclaw/
├── 003-picoclaw/
├── 004-picoclaw/
├── 005-zeroclaw/
├── 006-zeroclaw/
├── 007-nanobot/
├── 008-nanobot/
├── 009-nullclaw/
├── 010-nullclaw/
├── 011-hermes/
├── 012-hermes/
├── 013-moltis/
├── 014-moltis/
├── 015-mercury/
└── 016-mercury/

cmd tree

<target> = <agents|services|agent-id|service-id>

cmd
├── list                                      # list agent directories
├── make <agent-id|agent-id-agent-kind> ...   # create an agent and run native setup
├── remove <agent-id> [-y|--yes]              # uninstall service artifact and remove agent dir
├── <agent-id>
│   ├── bootstrap                             # install runtime/dependencies for this agent
│   ├── edit                                  # open agent dir in $EDITOR
│   ├── start ...                             # run agent gateway/daemon in foreground
│   └── <native agent command> ...            # forward to the native agent CLI
└── infra
    ├── bootstrap                             # install host deps/runtimes and service-manager artifacts
    ├── install [<target>...]                 # install service-manager artifacts
    ├── uninstall [<target>...]               # remove service-manager artifacts
    ├── start [<target>...]                   # start managed agents/services
    ├── stop [<target>...]                    # stop managed agents/services
    ├── restart [<target>...]                 # restart managed agents/services
    ├── status [<target>...]                  # show managed status
    ├── doctor [<target>...]                  # show diagnostics and short logs
    ├── log [<target>...]                     # tail logs
    └── render [<all|brew|caddy>]             # render generated infra files

lifecycle

  • ./cmd make <agent-name> creates the agent directory and runs the agent's native setup command
  • ./cmd remove <agent-id> removes the agent directory
  • ./cmd <agent-id> bootstrap installs runtime and any kind-specific dependencies / steps for that one agent
  • ./cmd <agent-id> onboard native agent command for the initial setup, onboarding, auth, channels, etc .
  • ./cmd <agent-id> start runs an agent in the foreground (stop a foreground run with Ctrl-C)
  • ./cmd infra bootstrap installs runtime dependencies and service-manager artifacts based on host agents or services
  • ./cmd infra start/stop <agent-id> manage configured agent as a supervised background service
  • ./cmd infra start agents is the host-scoped shortcut for the ids listed in CLAWLAB_AGENTS
  • ./cmd infra start services is the host-scoped shortcut for the service ids listed in CLAWLAB_SERVICES

common flows

inspect the local agent list:

./cmd list

create and use an agent interactively:

./cmd make 001-openclaw
./cmd 001 bootstrap
./cmd 001 onboard --skip-daemon
./cmd 001 start

./cmd make 004-picoclaw
./cmd 004 bootstrap
./cmd 004 auth login --provider anthropic
./cmd 004 start

./cmd make 007-zeroclaw
./cmd 007 bootstrap
./cmd 007 auth paste-redirect --provider openai-codex --profile default
./cmd 007 start

./cmd make 011-hermes
./cmd 011 bootstrap
./cmd 011 setup
./cmd 011 --tui
./cmd 011 start

open agent directory in $EDITOR:

./cmd 001 edit

remove agent directory and its service-manager artifact:

./cmd remove 011

manage host-assigned infra targets:

./cmd infra bootstrap
./cmd infra install
./cmd infra start
./cmd infra status agents
./cmd infra log services
./cmd infra stop services

operate on explicit agents and services:

./cmd infra install caddy vibetunnel 000 004 011
./cmd infra start services 003 005
./cmd infra restart caddy 001 002 006
./cmd infra status 000 004 caddy
./cmd infra doctor services 007
./cmd infra log 003 005 caddy
./cmd infra stop 008 vibetunnel
./cmd infra uninstall 011 caddy

manually generate infra templates:

./cmd infra render all
./cmd infra render brew
./cmd infra render caddy

notes

done for fun