Initial implementation of vault-os
Complete implementation across all 13 phases: - vault-core: types, YAML frontmatter parsing, entity classification, filesystem ops, config, prompt composition, validation, search - vault-watch: filesystem watcher with daemon write filtering, event classification - vault-scheduler: cron engine, process executor, task runner with retry logic and concurrency limiting - vault-api: Axum REST API (15 route modules), WebSocket with broadcast, AI assistant proxy, validation, templates - Dashboard: React + TypeScript + Tailwind v4 with kanban, CodeMirror editor, dynamic view system, AI chat sidebar - Nix flake with dev shell and NixOS module - Graceful shutdown, inotify overflow recovery, tracing instrumentation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
commit
f820a72b04
123 changed files with 18288 additions and 0 deletions
260
README.md
Normal file
260
README.md
Normal file
|
|
@ -0,0 +1,260 @@
|
|||
# vault-os
|
||||
|
||||
A personal AI operations platform — a single Rust daemon that turns a directory of markdown files with YAML frontmatter into a reactive system: knowledge base, task manager, agent orchestrator, cron scheduler, and web dashboard.
|
||||
|
||||
**Everything is markdown.** Status is directory-based. The filesystem is the database.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
vault-os (binary)
|
||||
├── vault-core # Types, frontmatter parsing, filesystem ops, validation, search
|
||||
├── vault-watch # Filesystem watcher (notify/inotify) with daemon write filtering
|
||||
├── vault-scheduler # Cron engine, process executor, task runner with retry logic
|
||||
└── vault-api # Axum REST API, WebSocket, embedded dashboard
|
||||
```
|
||||
|
||||
The daemon runs three concurrent event sources via `tokio::select!`:
|
||||
- **Filesystem events** — file changes trigger cache updates, task execution, cron rescheduling
|
||||
- **Cron timer** — fires scheduled agent tasks at the right time
|
||||
- **Shutdown signal** — graceful shutdown waiting for running tasks
|
||||
|
||||
## Vault Directory Structure
|
||||
|
||||
```
|
||||
vault/
|
||||
├── agents/ # Agent definitions
|
||||
├── skills/ # Reusable skill modules
|
||||
├── crons/
|
||||
│ ├── active/ # Enabled cron jobs
|
||||
│ ├── paused/ # Disabled cron jobs
|
||||
│ └── templates/ # Cron templates
|
||||
├── todos/
|
||||
│ ├── harald/ # Human tasks
|
||||
│ │ ├── urgent/
|
||||
│ │ ├── open/
|
||||
│ │ ├── in-progress/
|
||||
│ │ └── done/
|
||||
│ └── agent/ # Agent task queue
|
||||
│ ├── queued/
|
||||
│ ├── running/
|
||||
│ ├── done/
|
||||
│ └── failed/
|
||||
├── knowledge/ # Free-form knowledge base
|
||||
├── views/ # Dashboard view definitions
|
||||
│ ├── pages/
|
||||
│ ├── widgets/
|
||||
│ ├── layouts/
|
||||
│ └── notifications/
|
||||
└── .vault/ # Daemon state (git-ignored)
|
||||
├── config.yaml
|
||||
└── state.json
|
||||
```
|
||||
|
||||
## Building
|
||||
|
||||
### Prerequisites
|
||||
|
||||
**With Nix (recommended):**
|
||||
|
||||
```sh
|
||||
nix develop
|
||||
```
|
||||
|
||||
This gives you Rust (stable, latest), rust-analyzer, clippy, Node.js 22, npm, and cargo-watch.
|
||||
|
||||
**Without Nix:**
|
||||
|
||||
- Rust stable (1.75+)
|
||||
- Node.js 22+
|
||||
- npm
|
||||
- pkg-config, openssl (on Linux)
|
||||
|
||||
### Build the daemon
|
||||
|
||||
```sh
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
### Build the dashboard
|
||||
|
||||
```sh
|
||||
cd dashboard
|
||||
npm install
|
||||
npm run build
|
||||
```
|
||||
|
||||
### Run tests
|
||||
|
||||
```sh
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
### Run clippy
|
||||
|
||||
```sh
|
||||
cargo clippy --workspace
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
### Start the daemon
|
||||
|
||||
```sh
|
||||
vault-os --vault /path/to/your/vault
|
||||
```
|
||||
|
||||
The daemon creates the directory structure automatically on first run.
|
||||
|
||||
### CLI Options
|
||||
|
||||
| Flag | Env Var | Default | Description |
|
||||
|------|---------|---------|-------------|
|
||||
| `--vault <PATH>` | `VAULT_PATH` | (required) | Path to vault directory |
|
||||
| `--port <PORT>` | `VAULT_PORT` | `8080` | HTTP/WebSocket port |
|
||||
| `--bind <ADDR>` | `VAULT_BIND` | `127.0.0.1` | Bind address |
|
||||
| `--max-parallel <N>` | `VAULT_MAX_PARALLEL` | `4` | Max concurrent agent executions |
|
||||
| `--log-level <LEVEL>` | `VAULT_LOG_LEVEL` | `info` | Log level (trace/debug/info/warn/error) |
|
||||
|
||||
### Access the dashboard
|
||||
|
||||
Open `http://localhost:8080` in your browser.
|
||||
|
||||
For development with hot-reload:
|
||||
|
||||
```sh
|
||||
cd dashboard
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The Vite dev server proxies `/api` and `/ws` to the Rust daemon on port 8080.
|
||||
|
||||
## File Format
|
||||
|
||||
Every entity is a markdown file with YAML frontmatter. Example agent:
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: reviewer
|
||||
executable: claude-code
|
||||
model: claude-sonnet-4-20250514
|
||||
skills:
|
||||
- read-vault
|
||||
- github-pr-review
|
||||
timeout: 600
|
||||
max_retries: 1
|
||||
env:
|
||||
GITHUB_TOKEN: ${GITHUB_TOKEN}
|
||||
---
|
||||
|
||||
You are a code reviewer. Review pull requests thoroughly,
|
||||
focusing on correctness, security, and maintainability.
|
||||
```
|
||||
|
||||
Example cron job:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Daily Inbox Review
|
||||
schedule: "0 9 * * *"
|
||||
agent: reviewer
|
||||
enabled: true
|
||||
---
|
||||
|
||||
Review all open PRs and summarize findings.
|
||||
```
|
||||
|
||||
Example human task (in `todos/harald/open/`):
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Fix login bug
|
||||
priority: high
|
||||
labels: [bug, auth]
|
||||
created: 2026-03-01T10:00:00Z
|
||||
---
|
||||
|
||||
The login form throws a 500 when the email contains a plus sign.
|
||||
```
|
||||
|
||||
## API
|
||||
|
||||
The REST API is available at `/api`. Key endpoints:
|
||||
|
||||
| Endpoint | Description |
|
||||
|----------|-------------|
|
||||
| `GET /api/agents` | List all agents |
|
||||
| `POST /api/agents/:name/trigger` | Trigger an agent |
|
||||
| `GET /api/crons` | List cron jobs |
|
||||
| `POST /api/crons/:name/trigger` | Fire a cron manually |
|
||||
| `GET /api/todos/harald` | List human tasks |
|
||||
| `PATCH /api/todos/harald/:status/:id/move` | Move task between statuses |
|
||||
| `GET /api/todos/agent` | List agent tasks |
|
||||
| `GET /api/knowledge` | Search knowledge base |
|
||||
| `GET/PUT/DELETE /api/files/*path` | Generic file CRUD |
|
||||
| `GET /api/tree` | Vault directory tree |
|
||||
| `GET /api/stats` | Vault statistics |
|
||||
| `GET /api/health` | Health check |
|
||||
| `POST /api/assistant/chat` | AI assistant chat |
|
||||
| `POST /api/validate` | Validate a vault file |
|
||||
| `GET /api/templates` | List entity templates |
|
||||
| `WS /ws` | Real-time events |
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `.vault/config.yaml` in your vault root:
|
||||
|
||||
```yaml
|
||||
# Agent executors
|
||||
executors:
|
||||
ollama:
|
||||
base_url: http://localhost:11434
|
||||
|
||||
# Task queue settings
|
||||
queue:
|
||||
max_parallel: 4
|
||||
default_timeout: 600
|
||||
retry_delay: 60
|
||||
|
||||
# Inline AI assistant
|
||||
assistant:
|
||||
default_model: local/qwen3
|
||||
models:
|
||||
- local/qwen3
|
||||
- claude-sonnet-4-20250514
|
||||
```
|
||||
|
||||
Set `ANTHROPIC_API_KEY` in your environment to use Claude models with the assistant.
|
||||
|
||||
## NixOS Deployment
|
||||
|
||||
Add to your NixOS configuration:
|
||||
|
||||
```nix
|
||||
{
|
||||
inputs.vault-os.url = "github:you/vault-os";
|
||||
|
||||
# In your configuration.nix:
|
||||
imports = [ vault-os.nixosModules.default ];
|
||||
|
||||
services.vault-os = {
|
||||
enable = true;
|
||||
vaultPath = "/var/lib/vault-os";
|
||||
port = 8080;
|
||||
bind = "127.0.0.1";
|
||||
maxParallel = 4;
|
||||
environmentFile = "/run/secrets/vault-os.env"; # for API keys
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
The systemd service runs with hardened settings (NoNewPrivileges, ProtectSystem=strict, PrivateTmp, etc.).
|
||||
|
||||
## License
|
||||
|
||||
Licensed under either of
|
||||
|
||||
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
|
||||
- MIT License ([LICENSE-MIT](LICENSE-MIT))
|
||||
|
||||
at your option.
|
||||
Loading…
Add table
Add a link
Reference in a new issue