| title | VisionClaw Documentation |
|---|---|
| description | Documentation hub for VisionClaw — a governed agentic mesh for real-time 3D knowledge-graph exploration with GPU-accelerated physics, OWL 2 EL ontology reasoning, and a multi-agent control surface. |
VisionClaw · Documentation Hub
VisionClaw is a governed agentic mesh for real-time 3D knowledge-graph exploration: a Rust backend, CUDA GPU physics, OWL 2 EL ontology reasoning over an embedded Oxigraph triple store, and a multi-agent AI control surface.
git clone https://github.com/DreamLab-AI/VisionClaw.git
cd VisionClaw && cp env.example .env
./scripts/launch.sh up dev./scripts/launch.sh up dev is the canonical launcher. The explicit fallback is docker compose -f docker-compose.unified.yml --profile dev up -d — docker-compose.unified.yml is the application compose file; docker-compose.cloudflared.yml is an optional standalone tunnel overlay that launch.sh does not use.
| Service | URL | Notes |
|---|---|---|
| 3D graph frontend | http://localhost:3001 | nginx |
| REST API | http://localhost:4000/api | HTTP + WebSocket |
| Solid pod | http://localhost:8484 | per-user pod storage |
| Codescape (dev nginx) | http://localhost:3001/codescape/ | opt-in, CODESCAPE=1 ./scripts/launch.sh up dev; code-graph section, separate workspace (ADR-2143) |
| Codescape (direct) | http://localhost:4100 | loopback by default; hook ingest :4101 stays on visionclaw_network, never published |
| MCP TCP (agentbox) | multi-agent-container:9500 (MCP_TCP_PORT) |
outbound poll by bots_client.rs for agent-state snapshots; WebSocket cutover planned — see ADR-2084 |
The graph store is the embedded Oxigraph triple store backed by SQLite (ADR-2004). Neo4j is fully removed (ADR-132) and there is no separate database browser UI.
| Layer | Facts |
|---|---|
| Backend | 428 Rust files (~178K LOC); 35 Actix actors (19 service + 16 GPU; +10 WebSocket session); 44 hexser handlers (19 directive + 25 query), no CQRS bus (ADR-089); 9 ports, 12 adapters; 8 workspace crates |
| GPU physics | 82 CUDA __global__ kernels across 9 .cu files (5,854 LOC); 17,147 nodes laid out live |
| Client | 465 TypeScript/TSX files (422 non-test, ~103K LOC); 16 feature modules |
| Ontology | Whelk-rs OWL 2 EL + SHACL-lite + JSON-LD validation + PROV-O provenance (PRD-022); 7 MCP ontology tools |
| Wire protocol | Full-snapshot V3 (52 B/node) / V5 (V3 body + 8-byte broadcast seq) — delta encoding prohibited by design (BROADCAST-001); clients tween to server targets |
| Decision record | 99 living ADR-2xxx records in adr/; the frozen legacy corpus under archive/ holds 120 ADRs, 26 PRDs and 15 DDD context maps |
Documentation follows the Diátaxis framework — each quadrant serves a distinct need. Outside the four quadrants, docs/ also carries the security audit, screenshots and media assets, diagram sources, gap-close evidence, estate-closeout receipts and the dream-cycle ledger.
| Category | Purpose | Start here |
|---|---|---|
| Tutorials | Learning-oriented lessons that teach VisionClaw by doing | tutorials/ |
| How-to | Task recipes for deployment, development, operations, and features | how-to/ |
| Explanation | Concepts and rationale — architecture, physics, ontology, security | explanation/ |
| Reference | Exhaustive specifications — REST, WebSocket, binary protocol, schema, config | reference/ |
| Decisions | Architecture Decision Records governing every major design choice | adr/ |
| Formal record (frozen) | Legacy Product Requirements and Domain-Driven Design context maps — rationale only, never authority | archive/prd/ · archive/ddd/ |
- New user — Start with What is VisionClaw?, then Installation, Your first graph, and the navigation guide.
- Developer — Building against the API: REST API, WebSocket protocol, Binary protocol. Understanding the internals: System overview, Backend architecture, Client architecture, and Physics & GPU engine. Contributing: CONTRIBUTING and the development guide.
- Debugging and architecture audits — Tracing one agent write across seven layers (the command at each hop to find which layer dropped a request) and the actor bypass inventory (per-site recommendations for X-2; recommendations only, nothing deleted).
- Operator — Running it in production: Deployment, the operations runbooks, Configuration reference, Known issues, and the pre-demo security audit (2026-08-21).
Codescape is a separate section (live code-graph view with voice), not part of the knowledge-work system.
Before debugging unexpected behaviour, check KNOWN_ISSUES.md — it tracks active P1/P2 bugs and their workarounds.
VisionClaw runs on top of agentbox, the sovereign agent-runtime subsystem (skills, identity mesh, pod adapters, ACSP control surfaces). agentbox is a subsystem with its own documentation set — VisionClaw links into it rather than duplicating it.
- Contributing — workflow, branching conventions, code standards
- Changelog — version history and release notes
Maintained by DreamLab AI — Issues · Discussions