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):

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

cargo build --release

Build the dashboard

cd dashboard
npm install
npm run build

Run tests

cargo test --workspace

Run clippy

cargo clippy --workspace

Usage

Start the daemon

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:

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:

---
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:

---
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/):

---
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:

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

{
  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)
• MIT License (LICENSE-MIT)

at your option.