diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..62b7367 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,182 @@ +# Changelog + +All notable changes to [clawport-ui](https://www.npmjs.com/package/clawport-ui) will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [0.5.3] - 2026-03-05 + +### Changed + +- Added clawport.dev link to README header. + +## [0.5.2] - 2026-03-04 + +### Fixed + +- Agent discovery now uses SOUL.md-driven scanning for subdirectory agents, replacing fragile directory-name matching. + +## [0.5.1] - 2026-03-03 + +### Changed + +- Rewrote CLI discovery to use real `openclaw agents list` output format. + +## [0.5.0] - 2026-03-02 + +### Added + +- CLI-based agent discovery via `openclaw agents list`. +- Dagre-powered org map with team-column layout. + +### Fixed + +- Deduplicated root agent when `agents/` directory name matches root ID. + +## [0.4.6] - 2026-02-28 + +### Added + +- Setup detection module with comprehensive setup scenario tests. + +## [0.4.5] - 2026-02-27 + +### Fixed + +- Handle `{ crons, pipelines }` response format in all consumers. + +## [0.4.4] - 2026-02-26 + +### Fixed + +- Split cron-pipelines module to avoid `fs` import in client bundle. + +## [0.4.3] - 2026-02-25 + +### Added + +- Rebuilt Memory page as 3-tab dashboard with live config viewer. + +### Changed + +- Documentation: added 405 troubleshooting, auto-discovery info, fixed clone URL. + +### Fixed + +- Detect and auto-enable gateway HTTP endpoint during setup. +- Rewrote agent auto-discovery to handle all OpenClaw heading formats. + +## [0.4.2] - 2026-02-24 + +### Added + +- Auto-discover agents from OpenClaw workspace. +- Kanban board hardening. + +### Changed + +- Default accent color to red; clarified package vs CLI naming. + +## [0.4.1] - 2026-02-23 + +### Fixed + +- Set `turbopack.root` to package directory for global installs. +- Moved Next.js build dependencies to `dependencies` for global installs. +- Converted `next.config.ts` to `next.config.mjs` for global installs. +- Use package-local `next` binary instead of `npx` in CLI. + +## [0.2.0] - 2026-02-20 + +### Added + +- CLI entry point (`bin/clawport.mjs`) with `clawport dev`, `clawport setup`, `clawport start`, `clawport status`, and `clawport help` commands. +- Published `clawport-ui` to npm with default lobster emoji. +- MIT LICENSE file and repository URLs for open-source readiness. +- Lucide icons on all action buttons with dynamic accent contrast. +- Onboarding wizard (5-step first-run setup: name, theme, accent, mic, overview). + +### Changed + +- Rebranded from Agent Claw / Manor UI to ClawPort throughout the codebase. +- Renamed ManorMap component and stripped voice IDs. + +## [0.1.3] - 2026-02-17 + +### Added + +- Kanban board with agent automation (V2). + +### Changed + +- Comprehensive README, CLAUDE.md, and `.env.example` update. + +### Removed + +- Voice recording and audio playback from chat. + +### Fixed + +- `sendViaOpenClaw` uses send-then-poll pattern for `chat.send`. +- Image pipeline: resize client-side, use CLI `execFile`, check only latest message. + +## [0.1.2] - 2026-02-14 + +### Added + +- Route image messages through OpenClaw `chat.send` pipeline. +- TDD coverage for multimodal, validation, and audio-recorder modules. +- Multimodal chat with vision and file support, plus TTS listen button. +- Voice messages, file attachments, and enhanced media input. + +### Fixed + +- Use WebSocket for image messages instead of CLI (fixes E2BIG). +- Return plain string for audio-only messages in `buildApiContent`. + +## [0.1.1] - 2026-02-11 + +### Added + +- Complete Apple-quality UI/UX remake. +- Security hardening and test infrastructure. +- Messenger-style chat with avatars, name labels, and markdown formatting. +- Full Messenger rebuild with persistent threads, all agents, and media support. +- 5-theme system (Dark, Glass, Color, Light, System) with visible map connectors. + +### Fixed + +- Removed hardcoded OpenClaw gateway token. +- Chat via OpenClaw gateway using `claude-sonnet-4-6` (no separate API key required). + +### Changed + +- Apple dark mode full pass: glass chat, line numbers, gold gradients, animated states. + +## [0.1.0] - 2026-02-07 + +### Added + +- Initial release. +- Agent org map with React Flow. +- Call box for direct agent chat. +- Cron monitor dashboard. +- Memory browser. +- Next.js 16 App Router with Turbopack. + +[0.5.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.2...v0.5.3 +[0.5.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.1...v0.5.2 +[0.5.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.5.0...v0.5.1 +[0.5.0]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.6...v0.5.0 +[0.4.6]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.5...v0.4.6 +[0.4.5]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.4...v0.4.5 +[0.4.4]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.3...v0.4.4 +[0.4.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.2...v0.4.3 +[0.4.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.4.1...v0.4.2 +[0.4.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.2.0...v0.4.1 +[0.2.0]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.3...v0.2.0 +[0.1.3]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.2...v0.1.3 +[0.1.2]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.1...v0.1.2 +[0.1.1]: https://github.com/JohnRiceML/clawport-ui/compare/v0.1.0...v0.1.1 +[0.1.0]: https://github.com/JohnRiceML/clawport-ui/releases/tag/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b598183 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,116 @@ +# Contributing to ClawPort + +Thank you for your interest in contributing to ClawPort. Whether you are fixing a bug, improving documentation, or adding a feature, your help is welcome and appreciated. + +This guide covers the conventions and process we follow so that contributions stay consistent and easy to review. + +## Development Setup + +1. Fork and clone the repository: + ```bash + git clone https://github.com//clawport-ui.git + cd clawport-ui + ``` + +2. Install dependencies (Node 22+): + ```bash + npm install + ``` + +3. Run the setup script to auto-detect your local OpenClaw installation and generate `.env.local`: + ```bash + npm run setup + ``` + +4. Start the dev server (Turbopack, port 3000): + ```bash + npm run dev + ``` + +## Code Style + +ClawPort follows a small set of conventions that keep the codebase consistent. Please follow these when writing new code: + +- **TypeScript strict mode.** No `any` escapes without a comment explaining why. +- **Tailwind CSS custom properties for theming.** Use `var(--text-primary)`, `var(--bg)`, etc. instead of Tailwind color utility classes like `text-gray-500`. Theme tokens are defined in `app/globals.css`. +- **No external charting or media libraries.** Use native Web APIs (Canvas, SVG, MediaRecorder, AudioContext) and custom components. +- **Base64 data URLs for persisted media.** Blob URLs do not survive page reloads. Always convert to base64 before storing. +- **Call `requireEnv()` inside functions, not at module top level.** Top-level calls crash imports during `next build` and test runs when env vars are absent. See `lib/env.ts` for the helper. + +## Testing + +All tests live alongside their source files: `lib/foo.ts` has `lib/foo.test.ts`. + +Before opening a PR, make sure both of these pass: + +```bash +npm test # Vitest -- all tests must pass +npx tsc --noEmit # Type-check -- zero errors expected +``` + +### Writing Tests + +- Write tests for every new feature or bug fix. +- Use the patterns already established in the codebase: + - `vi.mock('child_process')` for CLI-dependent code + - `vi.stubEnv('VAR_NAME', 'value')` for environment variables + - `vi.useFakeTimers({ shouldAdvanceTime: true })` for polling or time-dependent logic +- Keep tests focused. One behavior per test case. + +## Pull Request Process + +1. **Fork** the repo and create a feature branch from `main`: + ```bash + git checkout -b fix/agent-discovery-crash + ``` + +2. **Make your changes.** Commit with clear messages (see below). + +3. **Push** your branch and open a pull request against `main`. + +4. In the PR description, explain **what** the change does and **why** it is needed. Link to a related issue if one exists. + +5. A maintainer will review your PR. Be open to feedback -- we may suggest changes before merging. + +## Commit Messages + +Use imperative mood with a short subject line. A longer body is optional but welcome for non-trivial changes. + +Examples from the project history: + +``` +Fix agent discovery: SOUL.md-driven scanning +Add CLI-based agent discovery +feat: auto-discover agents from OpenClaw workspace +``` + +Keep the subject under 72 characters. If you need to elaborate, leave a blank line after the subject and write a body paragraph. + +## What Makes a Good PR + +- **One concern per PR.** A bug fix, a feature, or a refactor -- not all three at once. +- **Tests included.** New behavior should have corresponding tests. Bug fixes should include a test that would have caught the bug. +- **No unrelated changes.** Resist the urge to fix formatting or rename variables in files you are not otherwise touching. Those are welcome as separate PRs. + +## Reporting Bugs + +Open a [GitHub Issue](https://github.com/JohnRiceML/clawport-ui/issues) with: + +- A clear title describing the problem. +- Steps to reproduce (commands, configuration, browser/OS if relevant). +- Expected behavior vs. actual behavior. +- Relevant error messages, logs, or screenshots. + +## Feature Requests + +Open a [GitHub Issue](https://github.com/JohnRiceML/clawport-ui/issues) and describe: + +- The problem you are trying to solve (not just the solution you have in mind). +- Why this matters for your workflow. +- Any alternatives you have considered. + +Good feature requests focus on the "why" and leave room for the maintainers and community to collaborate on the "how." + +## License + +By contributing to ClawPort, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/README.md b/README.md index 64591be..c94fbf7 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,114 @@ +
+ # ClawPort -**[clawport.dev](https://clawport.dev)** | A visual command centre for your AI agent team. +**A visual command centre for your AI agent team.** -ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. Built with Next.js 16, React 19, and a dark command-centre aesthetic with five themes. +[![npm version](https://img.shields.io/npm/v/clawport-ui.svg)](https://www.npmjs.com/package/clawport-ui) +[![license](https://img.shields.io/npm/l/clawport-ui.svg)](LICENSE) +[![tests](https://img.shields.io/badge/tests-442%20passed-brightgreen)](#testing) + +[Website](https://clawport.dev) | [Setup Guide](SETUP.md) | [API Docs](docs/API.md) | [npm](https://www.npmjs.com/package/clawport-ui) + +
--- -## Getting Started +ClawPort is an open-source dashboard for managing, monitoring, and talking directly to your [OpenClaw](https://openclaw.ai) AI agents. It connects to your local OpenClaw gateway and gives you an org chart, direct agent chat with vision and voice, a kanban board, cron monitoring, and a memory browser -- all in one place. -### Prerequisites +No separate AI API keys needed. Everything routes through your OpenClaw gateway. -- [Node.js 22+](https://nodejs.org) (LTS recommended) -- [OpenClaw](https://openclaw.ai) installed and running -- OpenClaw gateway started (`openclaw gateway run`) +--- -### Quick Start (npm) +## Quick Start + +### 1. Install OpenClaw + +ClawPort requires a running [OpenClaw](https://openclaw.ai) instance. If you don't have one yet: + +```bash +# Install OpenClaw +curl -fsSL https://openclaw.ai/install.sh | bash + +# Run the onboarding wizard (sets up workspace, gateway, and daemon) +openclaw onboard --install-daemon +``` + +After onboarding, verify the gateway is running: + +```bash +openclaw gateway status +``` + +You should see your gateway URL (`localhost:18789`) and auth token. See the [OpenClaw docs](https://docs.openclaw.ai/getting-started) for more detail. + +### 2. Install ClawPort > **Note:** The npm package is `clawport-ui`. The CLI command is `clawport`. > Do not install the unrelated `clawport` package. ```bash -# Install globally (package: clawport-ui, command: clawport) npm install -g clawport-ui +``` -# Auto-detect your OpenClaw config +### 3. Connect and Launch + +```bash +# Auto-detect your OpenClaw config and write .env.local clawport setup -# Start the dev server +# Start the dashboard clawport dev ``` -### Quick Start (from source) +Open [http://localhost:3000](http://localhost:3000). The onboarding wizard walks you through naming your portal, picking a theme, and setting up your operator identity. + +
+Install from source instead ```bash git clone https://github.com/JohnRiceML/clawport-ui.git cd clawport-ui npm install - -# Auto-detect your OpenClaw config and write .env.local npm run setup - -# Start the dev server npm run dev ``` -Open [http://localhost:3000](http://localhost:3000). On first launch you'll see the **onboarding wizard**, which walks you through naming your portal, choosing a theme, and personalizing agent avatars. - -See [SETUP.md](SETUP.md) for detailed environment configuration and troubleshooting. +
--- ## Features -### Org Map -Interactive org chart of your entire agent team. Nodes show hierarchy, cron status, voice capabilities, and relationships at a glance. Powered by React Flow with BFS-based auto-layout. +- **Org Map** -- Interactive org chart of your entire agent team. Hierarchy, cron status, and relationships at a glance. Powered by React Flow with auto-layout. +- **Chat** -- Streaming text chat, image attachments with vision, voice messages with waveform playback, file attachments, clipboard paste and drag-and-drop. Conversations persist locally. +- **Kanban** -- Task board for managing work across agents. Drag-and-drop cards with agent assignment and chat context. +- **Cron Monitor** -- Live status of all scheduled jobs. Filter by status, sort errors to top, expand for details. Auto-refreshes every 60 seconds. +- **Memory Browser** -- Read team memory, long-term memory, and daily logs. Markdown rendering, JSON syntax highlighting, search, and download. +- **Agent Detail** -- Full profile per agent: SOUL.md viewer, tools, hierarchy, crons, voice ID, and direct chat link. +- **Five Themes** -- Dark, Glass, Color, Light, and System. All CSS custom properties -- switch instantly. +- **Auto-Discovery** -- Automatically finds agents from your OpenClaw workspace. No config file needed. -### Chat (Call Box) -Full-featured messenger for direct agent conversations: -- **Streaming text chat** via Claude (through the OpenClaw gateway) -- **Image attachments** with vision -- agents can see and describe images -- **Voice messages** -- hold-to-record with waveform playback -- **File attachments** -- PDFs, docs, text files with type-aware rendering -- **Clipboard paste and drag-and-drop** for images -- **Clear chat** per agent -- Conversations persist to localStorage +--- -### Agent Detail -Full profile: SOUL.md viewer, tool list, hierarchy, associated crons, voice ID, and direct chat link. +## How It Works -### Kanban -Task board for managing work across your agent team. Drag-and-drop cards with agent assignment and chat context. +ClawPort reads your OpenClaw workspace to discover agents, then connects to the gateway for all AI operations: -### Cron Monitor -Live status of all scheduled jobs. Filter by status (all/ok/error/idle), sort errors to top, expand for error details. Auto-refreshes every 60 seconds. +``` +Browser --> ClawPort (Next.js) --> OpenClaw Gateway (localhost:18789) --> Claude + | | + | Text: /v1/chat/completions (streaming SSE) + | Vision: openclaw gateway call chat.send (CLI) + | Audio: /v1/audio/transcriptions (Whisper) + | + Reads from: + $WORKSPACE_PATH/agents/ (agent SOUL.md files) + $WORKSPACE_PATH/memory/ (team memory) + openclaw cron list (scheduled jobs) +``` -### Memory Browser -Read team memory, long-term memory, and daily logs. Markdown rendering and JSON syntax highlighting built-in. Search, copy, and download support. - -### Settings -Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent avatar overrides, and theme selection. All settings persist in your browser. +All AI calls -- chat, vision, TTS, transcription -- route through the gateway. One token, no separate API keys. --- @@ -86,211 +116,99 @@ Personalize your portal: custom name, subtitle, logo/emoji, accent color, agent ### Required Environment Variables -| Variable | Description | -|----------|-------------| -| `WORKSPACE_PATH` | Path to your OpenClaw workspace directory (default: `~/.openclaw/workspace`) | -| `OPENCLAW_BIN` | Path to the `openclaw` CLI binary | -| `OPENCLAW_GATEWAY_TOKEN` | Token that authenticates all API calls to the gateway | +| Variable | Description | How to find it | +|----------|-------------|----------------| +| `WORKSPACE_PATH` | Path to your OpenClaw workspace | Default: `~/.openclaw/workspace` | +| `OPENCLAW_BIN` | Path to the `openclaw` binary | Run `which openclaw` | +| `OPENCLAW_GATEWAY_TOKEN` | Gateway auth token | Run `openclaw gateway status` | -### Optional Environment Variables +### Optional | Variable | Description | |----------|-------------| -| `ELEVENLABS_API_KEY` | ElevenLabs API key for voice/TTS indicators on agent profiles | +| `ELEVENLABS_API_KEY` | ElevenLabs API key for voice indicators on agent profiles | -No separate AI API keys are needed. All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. - -See [SETUP.md](SETUP.md) for how to find each value. +Running `clawport setup` auto-detects all required values and writes `.env.local`. See [SETUP.md](SETUP.md) for manual configuration, agent customization, and troubleshooting. --- -## Agent Customization +## Agent Discovery -ClawPort ships with a bundled agent registry (`lib/agents.json`) as a working example. To use your own agents, create a file at: +ClawPort automatically discovers agents from your OpenClaw workspace. No configuration file needed. -``` -$WORKSPACE_PATH/clawport/agents.json -``` +**What it scans:** +- `$WORKSPACE_PATH/SOUL.md` -- root orchestrator +- `$WORKSPACE_PATH/IDENTITY.md` -- root agent name and emoji +- `agents//SOUL.md` -- top-level agents +- `agents//sub-agents/*.md` -- flat sub-agent files +- `agents//members/*.md` -- team member files +- `agents///SOUL.md` -- nested subdirectory agents -ClawPort checks for this file on every request. If it exists, it takes priority over the bundled registry. If it's missing or malformed, the bundled default is used as a fallback. +**What it ignores:** +- Directories without `SOUL.md` (e.g., `briefs/`, data files) +- Non-`.md` files in `sub-agents/` and `members/` -Each agent entry looks like this: - -```json -{ - "id": "my-agent", - "name": "My Agent", - "title": "What they do", - "reportsTo": "parent-agent-id", - "directReports": [], - "soulPath": "agents/my-agent/SOUL.md", - "voiceId": null, - "color": "#06b6d4", - "emoji": "🤖", - "tools": ["read", "write"], - "memoryPath": null, - "description": "One-liner description of this agent." -} -``` - -See [SETUP.md](SETUP.md) for the full field reference and examples. +For full control over names, colors, hierarchy, and tools, create `$WORKSPACE_PATH/clawport/agents.json`. See [SETUP.md](SETUP.md) for the schema and examples. --- -## Architecture - -### How Chat Works - -Text messages go through the OpenClaw gateway's OpenAI-compatible endpoint (`/v1/chat/completions`) for streaming responses. - -Image messages use a different pipeline because the gateway's HTTP endpoint strips image data. Instead, ClawPort uses the same path as Discord/Telegram channels: +## CLI +```bash +clawport dev # Start the development server +clawport start # Build and start production server +clawport setup # Auto-detect OpenClaw config, write .env.local +clawport status # Check gateway reachability and config +clawport help # Show usage ``` -User attaches image - → Client resizes to 1200px max (fits within OS arg limits) - → Client converts to base64 data URL - → POST /api/chat/[id] detects image in latest message - → Server calls `openclaw gateway call chat.send` via CLI - → Server polls `openclaw gateway call chat.history` every 2s - → Agent processes image + text through Anthropic vision API - → Response returned to client as SSE -``` - -Voice messages are recorded in-browser using the MediaRecorder API, transcribed server-side via Whisper (through the gateway's `/v1/audio/transcriptions` endpoint), and sent as text with the audio waveform preserved for playback. - -### Directory Structure - -``` -app/ - page.tsx — Org Map (React Flow org chart) - chat/page.tsx — Multi-agent messenger - agents/[id]/page.tsx — Agent detail profile - kanban/page.tsx — Task board - crons/page.tsx — Cron job monitor - memory/page.tsx — Memory file browser - settings/page.tsx — ClawPort personalization - api/ - agents/route.ts — GET agents from registry - chat/[id]/route.ts — POST chat (text + vision) - crons/route.ts — GET crons via CLI - memory/route.ts — GET memory files - tts/route.ts — POST text-to-speech - transcribe/route.ts — POST audio transcription - -components/ - OrgMap.tsx — React Flow graph with auto-layout - AgentNode.tsx — Custom node for the org chart - Sidebar.tsx — Desktop navigation sidebar - MobileSidebar.tsx — Mobile hamburger menu - ThemeToggle.tsx — Theme switcher (5 themes) - GlobalSearch.tsx — Cmd+K agent search - chat/ - ConversationView.tsx — Message history + input with media - AgentList.tsx — Agent sidebar for chat - VoiceMessage.tsx — Waveform playback component - FileAttachment.tsx — File bubble with icon + download - MediaPreview.tsx — Pre-send attachment strip - -lib/ - agents.ts — Agent registry + SOUL.md reader - agents-registry.ts — Registry loader (workspace override or bundled) - agents.json — Bundled default agent registry - anthropic.ts — OpenClaw vision pipeline (chat.send + poll) - audio-recorder.ts — MediaRecorder + waveform extraction - conversations.ts — Client-side conversation store (localStorage) - crons.ts — Cron data via openclaw CLI - env.ts — Environment variable helper - memory.ts — Memory file reader - multimodal.ts — Message → API content format converter - sanitize.ts — HTML/markdown sanitization - settings.ts — ClawPort settings (localStorage) - transcribe.ts — Whisper transcription with fallback - validation.ts — Chat message validation - types.ts — Shared TypeScript types - themes.ts — Theme definitions - styles.ts — Semantic style constants - utils.ts — Tailwind merge utility -``` - -### Key Design Decisions - -- **No separate API keys** -- All AI calls (chat, vision, TTS, transcription) route through the OpenClaw gateway. One subscription, one token. -- **No external charting/media libraries** -- Voice waveforms use plain div bars (not canvas), images resize via native Canvas API, all CSS uses Tailwind custom properties. -- **Client-side persistence** -- Conversations stored in localStorage with base64 data URLs. Blob URLs don't survive page reload; data URLs do. -- **Image resize before send** -- Images are resized client-side to max 1200px longest side before base64 encoding. This keeps the CLI argument payload under macOS's 1MB `ARG_MAX` limit. -- **Send-then-poll for vision** -- The gateway's `chat.send` is async (returns immediately). We poll `chat.history` every 2 seconds until the assistant response appears, matched by timestamp. --- -## Themes +## Testing -Five built-in themes, toggled via the sidebar button: - -| Theme | Description | -|-------|-------------| -| **Dark** | Apple Dark Mode with warm blacks, red accent | -| **Glass** | Frosted translucent panels on deep blue-black | -| **Color** | Vibrant purple-indigo gradients | -| **Light** | Apple Light Mode, clean whites | -| **System** | Follows OS preference | - -All themes use CSS custom properties. Components reference semantic tokens (`--bg`, `--text-primary`, `--accent`, etc.) so every theme is automatic. +```bash +npm test # 442 tests across 21 suites (Vitest) +npx tsc --noEmit # Type-check (zero errors) +npx next build # Production build +``` --- ## Stack - [Next.js 16](https://nextjs.org) (App Router, Turbopack) -- [React 19](https://react.dev) -- [TypeScript 5](https://typescriptlang.org) +- [React 19](https://react.dev) / [TypeScript 5](https://typescriptlang.org) - [Tailwind CSS 4](https://tailwindcss.com) -- [React Flow (@xyflow/react)](https://reactflow.dev) -- Org chart -- [OpenAI SDK](https://github.com/openai/openai-node) -- Gateway client (routed to Claude via OpenClaw) -- [Vitest 4](https://vitest.dev) -- Test runner -- [OpenClaw](https://openclaw.ai) -- AI gateway, agent runtime, vision pipeline +- [React Flow](https://reactflow.dev) -- org chart +- [Vitest 4](https://vitest.dev) -- testing +- [OpenClaw](https://openclaw.ai) -- AI gateway and agent runtime --- -## Development +## Documentation -See [CLAUDE.md](CLAUDE.md) for the full developer guide: architecture deep-dives, test patterns, common tasks, and contribution conventions. - -```bash -npm run dev # Start dev server (Turbopack, port 3000) -npm test # Run all tests via Vitest -npx tsc --noEmit # Type-check (expect 0 errors) -npx next build # Production build -``` +| Document | Description | +|----------|-------------| +| [SETUP.md](SETUP.md) | Full setup guide, agent customization, troubleshooting | +| [docs/API.md](docs/API.md) | REST API reference for all endpoints | +| [docs/COMPONENTS.md](docs/COMPONENTS.md) | UI component catalog (50+ components) | +| [docs/THEMING.md](docs/THEMING.md) | Theme system, CSS tokens, settings API | +| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute | +| [CHANGELOG.md](CHANGELOG.md) | Version history | +| [CLAUDE.md](CLAUDE.md) | Developer architecture guide | --- -## Built by +## Contributing -[John Rice](https://github.com/johnrice) with [Jarvis](https://openclaw.ai) (OpenClaw AI) - ---- - -## npm - -```bash -npm install -g clawport-ui -clawport help -``` - -Published as [`clawport-ui`](https://www.npmjs.com/package/clawport-ui) on npm. The CLI command is `clawport` (not `clawport-ui`). The separate `clawport` npm package is unrelated and not affiliated with this project. - -### CLI Commands - -| Command | Description | -|---------|-------------| -| `clawport dev` | Start the development server | -| `clawport start` | Build and start the production server | -| `clawport setup` | Auto-detect OpenClaw config and write `.env.local` | -| `clawport status` | Check gateway reachability and current config | -| `clawport help` | Show usage | +Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code style, and PR guidelines. --- ## License -MIT +[MIT](LICENSE) + +--- + +Built by [John Rice](https://github.com/JohnRiceML) with [Jarvis](https://openclaw.ai) (OpenClaw AI). diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..743e167 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,64 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | --------- | +| 0.5.x | Yes | +| < 0.5 | No | + +## Reporting a Vulnerability + +If you discover a security vulnerability in ClawPort, please report it responsibly. + +- **Email:** security@clawport.dev +- **GitHub:** Use [GitHub Security Advisories](https://github.com/JohnRiceML/clawport-ui/security/advisories/new) to report vulnerabilities privately. + +Please include steps to reproduce, affected versions, and potential impact. You should receive an acknowledgment within 72 hours. We will not pursue legal action against good-faith reporters. + +## Security Model + +ClawPort is a **local-first, single-operator tool**. It is designed to run on a developer's own machine or a trusted server. There is no user authentication system, no multi-tenant isolation, and no public-facing deployment expected. + +The trust boundary is the local machine. If an attacker has access to the machine running ClawPort, the application is not the appropriate layer of defense. + +## Token Handling + +ClawPort authenticates with the OpenClaw gateway using `OPENCLAW_GATEWAY_TOKEN`, stored in `.env.local` (gitignored). This token is: + +- Read server-side only via Next.js server actions and API routes. +- Never exposed to the browser or included in client-side bundles. +- Never logged or written to disk at runtime. + +No direct API keys for AI providers (OpenAI, Anthropic, etc.) are used. All AI calls route through the local OpenClaw gateway. + +## Data Storage + +- **Conversations** are stored in the browser's `localStorage` as base64 data URLs. They are not encrypted and are cleared when the user clears browser data. +- **Settings** are also stored in `localStorage`. +- No data is sent to external servers. There is no database. + +Users should be aware that anyone with access to their browser profile can read stored conversations and settings. + +## Filesystem Access + +ClawPort reads files from the path specified by `WORKSPACE_PATH` and executes the OpenClaw CLI binary specified by `OPENCLAW_BIN` via `child_process.execFile`. + +- `execFile` is used instead of `exec` to avoid shell injection. +- Both `WORKSPACE_PATH` and `OPENCLAW_BIN` are configured via server-side environment variables, not user input. +- Access is bounded by the OS-level permissions of the process running ClawPort. + +## Out of Scope + +The following are not considered vulnerabilities in ClawPort: + +- Denial of service against localhost services. +- Social engineering attacks. +- Physical access to the host machine. +- Vulnerabilities in OpenClaw, the gateway, or upstream AI providers (report those to their respective maintainers). +- Missing authentication or authorization (by design -- this is a single-operator tool). +- Data readable in `localStorage` by same-origin scripts (expected browser behavior). + +## Dependencies + +Dependencies are kept minimal. We run `npm audit` regularly and update vulnerable packages promptly. If you identify a dependency-level vulnerability that affects ClawPort specifically, please report it through the channels above. diff --git a/SETUP.md b/SETUP.md index 2d37b2a..d9926fa 100644 --- a/SETUP.md +++ b/SETUP.md @@ -6,9 +6,73 @@ This guide walks you through getting ClawPort running against your own OpenClaw ## Prerequisites -1. **Node.js 22+** -- [Download](https://nodejs.org). Verify with `node -v`. -2. **OpenClaw** -- [Install OpenClaw](https://openclaw.ai) and make sure the CLI works: `openclaw --version`. -3. **OpenClaw gateway running** -- ClawPort talks to the gateway at `localhost:18789`. Start it before launching the UI. +- **Node.js 22+** -- [Download](https://nodejs.org). Verify with `node -v`. +- **OpenClaw** -- installed and running (see below) + +--- + +## 0. Setting Up OpenClaw + +ClawPort connects to [OpenClaw](https://openclaw.ai), an open-source, self-hosted AI assistant that runs locally on your machine. If you already have OpenClaw running, skip to [step 1](#1-install-clawport). + +### Install OpenClaw + +```bash +# macOS / Linux +curl -fsSL https://openclaw.ai/install.sh | bash + +# Or via npm (requires Node 22+) +npm install -g openclaw +``` + +Windows: `iwr -useb https://openclaw.ai/install.ps1 | iex` + +Verify the install: + +```bash +openclaw --version +``` + +### Run the Onboarding Wizard + +The onboarding wizard sets up your workspace, configures the gateway, and installs it as a background daemon: + +```bash +openclaw onboard --install-daemon +``` + +This creates: + +| What | Where | +|------|-------| +| Config file | `~/.openclaw/openclaw.json` | +| Workspace | `~/.openclaw/workspace/` | +| Agent SOUL files | `~/.openclaw/workspace/agents/` | +| Memory | `~/.openclaw/workspace/memory/` | +| Credentials | `~/.openclaw/credentials/` | + +### Verify the Gateway + +The gateway is the local server that handles all AI operations. ClawPort talks to it at `localhost:18789`. + +```bash +openclaw gateway status +``` + +You should see the gateway URL, port, and auth token. If the gateway isn't running: + +```bash +openclaw gateway run +``` + +### Key Concepts + +- **Workspace** -- the directory where OpenClaw stores agent files, memory, and configuration. Default: `~/.openclaw/workspace`. +- **Gateway** -- local server at `localhost:18789` that routes AI calls to Claude, GPT, or local models. Exposes an OpenAI-compatible HTTP endpoint and a WebSocket control plane. +- **Agents** -- each agent has a `SOUL.md` defining its persona and a directory under `agents/` in your workspace. +- **SOUL.md** -- the identity file for an agent. Contains its name, role, personality, and operating rules. ClawPort reads these to build the dashboard. + +For more detail, see the [OpenClaw documentation](https://docs.openclaw.ai/getting-started). --- diff --git a/package.json b/package.json index a9bfd60..e02ed2e 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "clawport-ui", - "version": "0.5.3", + "version": "0.5.4", "description": "Open-source dashboard for managing, monitoring, and chatting with your OpenClaw AI agents.", "homepage": "https://clawport.dev", "repository": {