vault-os/README.md

# 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.