How carlosazaustre/tenacitos works
1. Overall shape
TenacitOS is a single Next.js 15 application that acts as a mission-control dashboard for an existing OpenClaw installation. There is no separate backend service: the app’s server routes read local files, OpenClaw workspace data, system state, and a local SQLite store directly on the host.
2. Primary trust boundary and auth
src/middleware.ts is the main gatekeeper. Almost everything is protected; the notable public entry points are login and health. Authentication is cookie-based, with a password login flow in /api/auth/login and logout in /api/auth/logout. The README also calls out rate limiting on failed login attempts and secure cookie settings in production.
3. Core external dependency: OpenClaw workspace
The central data source is the OpenClaw directory (OPENCLAW_DIR, defaulting to /root/.openclaw). TenacitOS discovers agents from openclaw.json and reads per-agent workspace content, sessions, memory, logs, and related metadata from the host filesystem. This means the dashboard is a read/write control surface over an existing local agent runtime, not an isolated app database.
4. Local app state files
The data/ directory holds JSON-backed app state such as cron jobs, activities, notifications, configured skills, and tasks. These files are the persistence layer for dashboard-managed content that is not sourced directly from OpenClaw. The .example.json files show that the repo expects these files to be created on deployment and kept out of version control.
5. Cost tracking pipeline
Cost analytics are handled separately from the main OpenClaw data flow. Usage is collected by scripts/collect-usage.ts from OpenClaw’s SQLite databases and aggregated into local cost data used by the /costs and /analytics views and their API routes. This is an offline ingestion step, with scripts/setup-cron.sh intended to automate hourly collection.
6. API layer as the backend façade
The src/app/api/* route handlers are the main server-side API surface. They expose subsystem-specific endpoints for agents, activities, analytics, auth, browse, costs, cron, files, git, logs, memory search, notifications, office, reports, search, sessions, skills, system, terminal, weather, and health. Several routes are specialized for streaming or stats (activities/stream, logs/stream, system/stats, system/monitor), indicating a mix of polling and event-style updates.
7. Dashboard UI structure
The protected dashboard lives under src/app/(dashboard). Each top-level page corresponds to a subsystem panel: agents, activity, analytics, calendar, costs, cron, files, git, logs, memory, reports, search, sessions, settings, skills, system, terminal, and workflows. Shared chrome and presentation live in src/components/TenacitOS, which provides the OS-like shell elements such as top bar, dock, status bar, and section/metric rows.
8. Main functional subsystems
The app is organized around a few major domains: agent management and status, activity and session observability, memory and file browsing/editing, cron scheduling and run history, system monitoring, and search. These domains are surfaced both as dashboard pages and as matching API endpoints, which keeps the architecture consistent: page → API route → local/OpenClaw data source.
9. Streaming and real-time views
Activity and log feeds have dedicated stream endpoints, and system monitoring has live stats/monitor routes. On the client side, this is reflected in charts, heatmaps, dashboards, and status widgets that likely refresh periodically or subscribe to streamed updates. The architecture favors near-real-time observability without introducing a message broker.
10. 3D office as a separate presentation surface
The /office route is an alternate, unprotected visualizer built with React Three Fiber. It uses src/components/Office3D plus public/models/ for per-agent GLB avatars, with fallback procedural or voxel avatars when models are absent. This surface is mostly presentational, but it still reflects the same underlying agent inventory and branding config.
11. File, terminal, and workspace control boundaries
File operations are exposed through dedicated API routes for list, preview, upload, write, mkdir, delete, and download. The terminal feature is explicitly read-only and guarded by a command allowlist to avoid arbitrary execution. That makes the file and terminal subsystems the two most sensitive control planes in the app.
12. Supporting libraries and runtime assumptions
Shared logic in src/lib handles path resolution, pricing, cron parsing, skill parsing, activity logging, usage collection, and database/query access. src/config/branding.ts centralizes env-driven branding. The stack is Node.js 22, Next.js App Router, React 19, Tailwind CSS v4, Recharts for charts, Lucide for icons, and SQLite via better-sqlite3 for usage/cost analytics.
13. Operational scripts and deployment model
The repo includes helper scripts for usage collection, pre-commit checks, and cron setup, which indicates the app is intended to be operated alongside the OpenClaw host rather than deployed as a generic SaaS. The production model is a single long-lived Node process behind PM2/systemd and optionally a reverse proxy like Caddy.
Main entry points: cron-jobs.example.json App state · middleware.ts Middleware · route.ts API façade · collect-usage.ts Usage pipeline
Components 21
App surface
Protected dashboard, login, office, and route entrypoints
- Middleware · Main request gate that protects dashboard routes and leaves login/health public
src/middleware.ts - Login · Cookie-based sign-in entry point and logout flow
src/app/login/page.tsx - Dashboard shell · Next.js dashboard layout and home entry for the main mission-control surface
src/app/(dashboard)/layout.tsx - Subsystem panels · Pages for agents, activity, analytics, costs, cron, files, logs, memory, search, sessions, settings, skills, system, terminal, workflows, and more
src/app/(dashboard)/page.tsx - Office view · Alternate office-style visualization built with React Three Fiber
src/app/office/page.tsx
API façade
Route handlers that expose host and workspace data
- Auth API · Login and logout handlers that establish and clear the dashboard session
src/app/api/auth/login/route.ts - API façade · Main subsystem endpoints for agents, activities, analytics, browse, costs, cron, files, git, logs, memory, notifications, reports, search, sessions, skills, system, terminal, weather, and health
src/app/api/agents/route.ts - Live feeds · Streaming and monitoring routes for activity, logs, and system live status
src/app/api/activities/stream/route.ts - File control · List, preview, write, upload, mkdir, delete, download, and workspace file access routes
src/app/api/files/route.ts - System API · System status, services, stats, and monitor endpoints for host health and runtime visibility
src/app/api/system/route.ts - Terminal API · Read-only terminal surface guarded by an allowlist
src/app/api/terminal/route.ts - Office API · Data endpoint backing the office visualization and agent avatars
src/app/api/office/route.ts
UI system
Shared components and presentation shells
- TenacitOS UI · OS-like shell components such as top bar, dock, status bar, rows, and metrics
src/components/TenacitOS/index.ts - Feature components · Domain widgets for activity feeds, agents, files, search, cron, skills, system info, notifications, markdown, calendar, and charts
src/components/ActivityFeed.tsx - Office3D · 3D office scene, avatars, furniture, controls, and model fallbacks
src/components/Office3D/Office3D.tsx
Core logic
Shared server-side helpers and runtime glue
Data and ops
Local persistence, workspace sources, and operational scripts
- App state · Local JSON-backed state for cron jobs, activities, notifications, skills, and tasks
data/cron-jobs.example.json - OpenClaw workspace · External OpenClaw directory and agent runtime data discovered from host files and workspace metadata
- Usage pipeline · Offline collection and aggregation of OpenClaw usage into local cost data for analytics
scripts/collect-usage.ts - Ops scripts · Cron setup, usage collection wrapper, and pre-commit checks for host operation
scripts/setup-cron.sh
Connections 22
- Middleware → Login: allows · Public entry path for authentication
- Middleware → Dashboard shell: protects · Gates dashboard routes behind the session cookie
- Middleware → API façade: protects · Secures the server API surface
- Login → Auth API: uses · Submits credentials and clears sessions
- Dashboard shell → TenacitOS UI: renders with · Uses shared shell chrome and status elements
- Subsystem panels → Feature components: renders with · Uses shared widgets and charts across panels
- Office view → Office3D: renders with · Uses the dedicated 3D office scene components
- API façade → OpenClaw workspace: reads · Most routes project host workspace data into the UI
- API façade → App state: reads/writes · Subsystem routes persist dashboard-managed app state
- File control → OpenClaw workspace: accesses · File browser and editor operate on workspace files
- System API → OpenClaw workspace: observes · System views draw host and runtime status from the workspace host
- Terminal API → OpenClaw workspace: controls · Restricted command execution against the host runtime
- Office API → OpenClaw workspace: reflects · Office avatars and inventory mirror the same agent set
- Core libs → OpenClaw workspace: interprets · Resolves workspace paths, parses skills and cron data, and queries usage sources
- Core libs → App state: persists · Helpers load and store dashboard-owned JSON state
- Usage pipeline → OpenClaw workspace: collects from · Reads SQLite usage data from the host installation
- Usage pipeline → App state: aggregates into · Produces local cost data consumed by analytics views
- Ops scripts → Usage pipeline: automates · Wraps hourly or scheduled usage collection
- Ops scripts → App state: prepares · Bootstraps and maintains expected local state files
- Branding → TenacitOS UI: styles · Centralized branding influences shell presentation
- Branding → Office view: brands · Office view uses the same identity configuration
- Live feeds → Subsystem panels: feeds · Supplies near-real-time activity, log, and system updates