clawrium 0.1.0__tar.gz

clawrium-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests with coverage
+        run: make test-cov
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: .coverage

clawrium-0.1.0/.gitignore

@@ -0,0 +1,211 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+## AI Stuff
+
+.claude/

clawrium-0.1.0/.mcp.json

@@ -0,0 +1,17 @@
+{
+  "mcpServers": {
+    "atx": {
+      "command": "/home/devashish/bin/atx",
+      "args": [
+        "mcp",
+        "serve"
+      ],
+      "env": {
+        "ATX_DAEMON_PORT": "30000",
+        "ATX_DB_PATH": "/home/devashish/.config/atx/data/atx.db",
+        "ATX_PROJECT_ID": "2f7d41ac-f5fb-4466-8e2e-9e69bbef6701",
+        "ATX_WORKING_DIR": "/home/devashish/workspace/ric03uec/clawrium"
+      }
+    }
+  }
+}

clawrium-0.1.0/.planning/PROJECT.md

@@ -0,0 +1,93 @@
+# Clawrium
+
+## What This Is
+
+Clawrium is a CLI/TUI tool for managing AI assistant fleets on local networks. It provides a centralized command center for installing, configuring, and maintaining multiple "claws" (AI assistants like OpenClaw, ZeroClaw, NemoClaw) across hosts, solving the chaos of configuration drift, scattered secrets, and inconsistent management.
+
+## Core Value
+
+Users can manage all their AI assistants from one place with consistent configuration and security practices, regardless of which claw types they run.
+
+## Requirements
+
+### Validated
+
+- [x] Initialize Clawrium config directory (`clm init`) — *Phase 1*
+- [x] Dependency check with install instructions — *Phase 1*
+
+### Active
+
+- [ ] Add/remove hosts in the fleet
+- [ ] Install OpenClaw on Ubuntu hosts via Ansible
+- [ ] Manage claw configs (SOUL.md, IDENTITY.md, AGENTS.md, etc.) from central store
+- [ ] Sync configs from central store to hosts
+- [ ] Check claw status on hosts
+- [ ] Rotate API keys across claws
+- [ ] Switch model providers for claws
+- [ ] Add/remove agents within a claw
+
+### Out of Scope
+
+- Cloud services — fully local, no external dependencies
+- Non-Debian-based distros — Ubuntu and Debian for v1, other distros later
+- Other claw types — OpenClaw only for v1, ZeroClaw/NemoClaw later
+- GUI — CLI/TUI only, no web interface
+- Multi-user/auth — single user for v1
+
+## Context
+
+**Problem space:**
+- AI assistants (claws) proliferate — users don't know which to install
+- Each claw has different config files, formats, and locations
+- Configuration drift when managing multiple instances
+- Secrets (API keys) scattered across config files
+- Upgrades risk breaking existing config
+- No unified way to manage fleet health
+
+**OpenClaw specifics:**
+- Config lives in `~/.openclaw/workspace/`
+- Key files: SOUL.md, IDENTITY.md, AGENTS.md, USER.md, MEMORY.md, HEARTBEAT.md
+- Global config: `~/.openclaw/openclaw.json`
+
+**Clawrium approach:**
+- Central store at `~/.config/clawrium/`
+- Registry of claw types with versions, dependencies, templates
+- Ansible playbooks for installation and config sync
+- Never takes sudo — prompts user for privileged operations
+
+## Constraints
+
+- **Tech stack**: Python + Typer CLI, ansible-runner for execution, uv/uvx for packaging
+- **Security**: No sudo permissions — Clawrium prompts user when privileged commands needed
+- **Platform**: Ubuntu and Debian for v1
+- **Claw support**: OpenClaw only for v1
+- **Deployment**: Fully local, no cloud dependencies
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Ansible for execution | Standard automation tool, no agent needed on hosts, SSH-based | — Pending |
+| No sudo policy | Security-first, user controls privileged operations | — Pending |
+| Central store in ~/.config/clawrium/ | Standard XDG location, single source of truth | — Pending |
+| Start with OpenClaw | Well-documented, clear file structure, good test case | — Pending |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `/gsd:transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `/gsd:complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-03-21 after Phase 1 completion*

clawrium-0.1.0/.planning/REQUIREMENTS.md

@@ -0,0 +1,118 @@
+# Requirements: Clawrium
+
+**Defined:** 2026-03-20
+**Core Value:** Users can manage all their AI assistants from one place with consistent configuration and security practices.
+
+## v1 Requirements
+
+Requirements for initial release: OpenClaw on single Ubuntu host.
+
+### Initialization
+
+- [x] **INIT-01**: User can initialize Clawrium config directory (`clm init`)
+- [x] **INIT-02**: User sees dependency check (Python, Ansible) with install instructions
+
+### Host Management
+
+- [x] **HOST-01**: User can add a host with SSH details (`clm host add`)
+- [x] **HOST-02**: User can list all hosts with hardware info (`clm host list`)
+- [x] **HOST-03**: User can remove a host (`clm host remove`)
+- [x] **HOST-04**: User can check host status (`clm host status`)
+- [x] **HOST-05**: System detects hardware capabilities (arch, GPU, memory, disk)
+
+### Claw Registry
+
+- [x] **REG-01**: System loads claw manifests from registry
+- [x] **REG-02**: User can list available claw types (`clm registry list`)
+- [x] **REG-03**: System validates claw compatibility against host capabilities
+
+### Claw Installation
+
+- [x] **INST-01**: User can install OpenClaw via interactive flow (`clm install`)
+- [x] **INST-02**: Installation validates compatibility before proceeding
+- [x] **INST-03**: Installation streams progress in real-time
+- [x] **INST-04**: Installation fails fast with clear error messages
+
+### Secrets Management
+
+- [x] **SEC-01**: User can set secrets (`clm secret set`)
+- [x] **SEC-02**: User can list secret keys (`clm secret list`)
+- [x] **SEC-03**: Secrets stored with mode 600, never displayed
+
+### Fleet Status
+
+- [x] **STAT-01**: User can view fleet status (`clm status`)
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Agent Normalization
+
+- **AGENT-01**: User can create portable agent definitions (`clm agent create`)
+- **AGENT-02**: User can list agents (`clm agent list`)
+- **AGENT-03**: User can edit agents (`clm agent edit`)
+- **AGENT-04**: System translates agents to claw-specific format
+
+### Claw Operations
+
+- **CLAW-01**: User can upgrade claw instances (`clm claw upgrade`)
+- **CLAW-02**: User can remove claw instances (`clm claw remove`)
+- **CLAW-03**: User can assign agents to claws (`clm claw agent add`)
+
+### Multi-Host Fleet
+
+- **FLEET-01**: User can manage multiple hosts
+- **FLEET-02**: User can sync configs across hosts
+
+### Additional Claw Types
+
+- **TYPE-01**: ZeroClaw support
+- **TYPE-02**: NemoClaw support
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| TUI interface | CLI first, TUI later |
+| Cloud services | Fully local, no external dependencies |
+| Non-Ubuntu distros | Ubuntu only for v1, other distros later |
+| Security hardening (airgap, sandboxing) | Table stakes first, hardening in v2+ |
+| GUI/web interface | CLI/TUI only |
+| Multi-user auth | Single user for v1 |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| INIT-01 | Phase 1 | Complete |
+| INIT-02 | Phase 1 | Complete |
+| HOST-01 | Phase 2 | Complete |
+| HOST-02 | Phase 2 | Complete |
+| HOST-03 | Phase 2 | Complete |
+| HOST-04 | Phase 2 | Complete |
+| HOST-05 | Phase 2 | Complete |
+| REG-01 | Phase 3 | Complete |
+| REG-02 | Phase 3 | Complete |
+| REG-03 | Phase 3 | Complete |
+| INST-01 | Phase 4 | Complete |
+| INST-02 | Phase 4 | Complete |
+| INST-03 | Phase 4 | Complete |
+| INST-04 | Phase 4 | Complete |
+| STAT-01 | Phase 4 | Complete |
+| SEC-01 | Phase 5 | Complete |
+| SEC-02 | Phase 5 | Complete |
+| SEC-03 | Phase 5 | Complete |
+
+**Coverage:**
+- v1 requirements: 17 total
+- Mapped to phases: 17
+- Unmapped: 0 ✓
+
+---
+*Requirements defined: 2026-03-20*
+*Last updated: 2026-03-21 after phase 4 planning*

clawrium-0.1.0/.planning/ROADMAP.md

@@ -0,0 +1,114 @@
+# Roadmap: Clawrium
+
+## Overview
+
+Clawrium v1 delivers a CLI tool for managing OpenClaw instances on single Ubuntu hosts. The journey progresses from foundation setup through host management, registry and compatibility checking, secrets handling, and culminates in the full installation flow with fleet status visibility. Each phase delivers complete, verifiable capabilities that build toward the core value: managing AI assistants from one place with consistent configuration and security practices.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [x] **Phase 1: Foundation Setup** - Initialize Clawrium configuration and verify dependencies (completed 2026-03-21)
+- [x] **Phase 2: Host Management** - Add, list, remove hosts with hardware capability detection (completed 2026-03-21)
+- [x] **Phase 3: Registry & Compatibility** - Load claw manifests and validate hardware compatibility (completed 2026-03-21)
+- [x] **Phase 4: Installation & Fleet Status** - Install OpenClaw instances and view fleet status (completed 2026-03-22)
+- [ ] **Phase 5: Secrets Management** - Secure storage and retrieval of API keys and credentials
+
+## Phase Details
+
+### Phase 1: Foundation Setup
+**Goal**: Users can initialize Clawrium and verify all dependencies are met
+**Depends on**: Nothing (first phase)
+**Requirements**: INIT-01, INIT-02
+**Success Criteria** (what must be TRUE):
+  1. User runs `clm init` and configuration directory is created at ~/.config/clawrium/
+  2. User sees clear status of all dependencies (Python, Ansible, ansible-runner)
+  3. User receives actionable install instructions for any missing dependencies
+**Plans**: 2 plans
+
+Plans:
+- [x] 01-01-PLAN.md — Project scaffolding and clm init command (creates config directory)
+- [x] 01-02-PLAN.md — Dependency detection with install instructions
+
+### Phase 2: Host Management
+**Goal**: Users can manage hosts with automatic hardware capability detection
+**Depends on**: Phase 1
+**Requirements**: HOST-01, HOST-02, HOST-03, HOST-04, HOST-05
+**Success Criteria** (what must be TRUE):
+  1. User can add a host and SSH connection is tested before saving
+  2. User sees detected hardware capabilities (architecture, GPU, memory, disk) when adding host
+  3. User can list all hosts with hardware information displayed
+  4. User can check status of any host (SSH connectivity, service health)
+  5. User can remove a host and all associated resources are cleaned up
+**Plans**: 4 plans
+
+Plans:
+- [x] 02-01-PLAN.md — Test scaffolding with SSH and Ansible mock fixtures
+- [x] 02-02-PLAN.md — Host storage and SSH connection testing modules
+- [x] 02-03-PLAN.md — Hardware capability detection via ansible-runner
+- [x] 02-04-PLAN.md — CLI host commands (add, list, remove, status)
+
+### Phase 3: Registry & Compatibility
+**Goal**: Users can browse available claw types and validate compatibility before installation
+**Depends on**: Phase 2
+**Requirements**: REG-01, REG-02, REG-03
+**Success Criteria** (what must be TRUE):
+  1. User runs `clm registry list` and sees OpenClaw with version and requirements
+  2. System loads OpenClaw manifest from platform/registry/openclaw/ directory
+  3. System validates host capabilities against claw requirements and reports compatibility (supported/unsupported with specific reasons)
+**Plans**: 4 plans
+
+Plans:
+- [x] 03-01-PLAN.md — Create OpenClaw manifest and registry loading module (REG-01)
+- [x] 03-02-PLAN.md — Extend HardwareInfo with OS detection (REG-03 foundation)
+- [x] 03-03-PLAN.md — Implement compatibility checking function (REG-03)
+- [x] 03-04-PLAN.md — Registry CLI commands (list, show) (REG-02)
+
+### Phase 4: Installation & Fleet Status
+**Goal**: Users can install OpenClaw on Ubuntu hosts and view fleet status
+**Depends on**: Phase 2, Phase 3
+**Requirements**: INST-01, INST-02, INST-03, INST-04, STAT-01
+**Success Criteria** (what must be TRUE):
+  1. User runs `clm install` and flows through: pick claw → pick host → validate compatibility → install
+  2. Installation validates compatibility before proceeding and fails fast if host is incompatible
+  3. User sees real-time progress during installation (base setup, dependencies, claw installation)
+  4. Installation fails fast with clear error messages if any step fails
+  5. User runs `clm status` and sees all hosts with their claw instances, agents, and status
+**Plans**: 4 plans
+
+Plans:
+- [x] 04-01-PLAN.md — Core install module and Ansible playbooks (INST-02, INST-04)
+- [x] 04-02-PLAN.md — Install CLI with interactive flow and progress (INST-01, INST-03)
+- [x] 04-03-PLAN.md — Install state tracking and health check module (INST-04, STAT-01)
+- [x] 04-04-PLAN.md — Fleet status CLI command (STAT-01)
+
+### Phase 5: Secrets Management
+**Goal**: Users can securely store and manage secrets for claw instances
+**Depends on**: Phase 1
+**Requirements**: SEC-01, SEC-02, SEC-03
+**Success Criteria** (what must be TRUE):
+  1. User can set a secret with `clm secret set` and it's stored with mode 600
+  2. User can list secret keys with `clm secret list` and values are never displayed
+  3. Secrets file is created with correct permissions (600) on first write
+**Plans**: 2 plans
+
+Plans:
+- [x] 05-01-PLAN.md — Core secrets storage module and manifest schema extension (SEC-01, SEC-03)
+- [x] 05-02-PLAN.md — CLI secret commands (set, list, remove) (SEC-01, SEC-02, SEC-03)
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4 → 5
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Foundation Setup | 2/2 | Complete   | 2026-03-21 |
+| 2. Host Management | 4/4 | Complete | 2026-03-21 |
+| 3. Registry & Compatibility | 4/4 | Complete | 2026-03-21 |
+| 4. Installation & Fleet Status | 4/4 | Complete | 2026-03-22 |
+| 5. Secrets Management | 0/2 | Planning complete | - |