vtai-agent

<!-- mcp-name: io.github.velsrocky/vtai-agent -->
# VT-AIAgent

[![CI](https://github.com/velsrocky/vtai-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/velsrocky/vtai-agent/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

System-automation agent for **your** machine, exposed as an MCP server for
opencode / Claude Code / pi — and drivable directly via the `vtai` CLI.

## Tools

| Tool | What it does |
|---|---|
| `system_info` | Read-only machine snapshot (CPU, RAM, disks, load, GPU) plus the config and guardrails in effect |
| `run_shell` | Allowlisted shell commands, sandboxed (see below) |
| `organize_files` | Content-aware directory cleanup inside writable roots |
| `backup_sync` | rsync incremental backup with verification; `--delete` is opt-in |
| `transcode_media` | VAAPI-accelerated batch video transcode; never touches originals |
| `disk_audit` | Read-only scan for reclaimable disk space |
| `delegate_coding` | Hand tasks to opencode/claude/pi; git snapshot + verify + rollback; require human approval by default |
| `auto_mode` | Autonomous loop: hand a goal to a coding CLI, review the reply, iterate until it matches |
| `inspect_application` | REA-powered static analysis of an app under guardrails: deny-glob check → quarantine copy → minimal-env run → evidence digest in the audit trail → optional judge pass (off until enabled in config) |

## Safety model

- **Dry-run by default** (`guardrails.dry_run_default`) — previews never touch disk.
- **Path containment**: writes only inside `paths.writable_roots`, resolved
  paths defeat `..`/symlink escapes; `guardrails.deny_globs` protect secrets.
- **Fail-closed shell sandbox**: the binary must be a bare allowlisted name
  with an explicit read/write policy, resolve inside `trusted_bin_dirs`, carry
  no exec-enabling flags, and every path argument passes the same checks.
- **Kill switch**: drop a `KILL` file in `data_dir` to abort executing tools.
- **Echo-loop breaker**: N identical denials in a window escalate the refusal
  into a `CIRCUIT BREAKER` instruction the looping model can't miss.
- **Budget cap**: `budget_usd_per_run` aborts an orchestrated run when accrued
  token cost exceeds it; spend is recorded per run.
- **Audit**: every allow and deny is logged to SQLite in `data_dir`, each
  invocation (orchestrated, MCP, or CLI) attributed to a run row.

## Quick start

### Prerequisites

| | Requirement | Notes |
|---|---|---|
| **OS** | Linux, macOS, or Windows | all three run in CI (blocking since 0.6.0) |
| **Python** | 3.14+ | pinned by `.python-version`; `uv` fetches it for you |
| **uv** | >= 0.13.1 | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| **Planner LLM** | one of: Ollama, any OpenAI-compatible endpoint, or a cloud key | see [Choosing a model](#choosing-a-model) |
| *rsync* | optional | required by `backup_sync`; without it the tool fails closed |
| *ffmpeg* | optional | required by `transcode_media` and the voice helpers |
| *Lemonade Server* | optional | speech in/out for `agent-listen` / `agent-speak` |

### 1. Install

```bash
git clone https://github.com/velsrocky/vtai-agent.git
cd vtai-agent
uv sync --dev
```

`uv sync` needs uv >= 0.13.1 (the lockfile is `revision = 5`; the floor is
declared as `[tool.uv] required-version`, so an older uv says so plainly
instead of failing on a lockfile parse).

### 2. Configure

The agent reads one TOML file. **Which** one is resolved in this order:

1. `$VT_CONFIG` — explicit override
2. `config/settings.toml` next to the package (i.e. the clone you just made)
3. `~/.vtaiagent/settings.toml` — the per-user file

A fresh clone contains the **maintainer's** config (their provider, their
writable roots), so point the agent at your own file instead of editing the
tracked one:

```bash
export VT_CONFIG="$HOME/.vtaiagent/settings.toml"
uv run vtai init          # writes a starter config there + creates the dirs
```

Put that `export` in your shell profile so every later command (and the MCP
server) picks it up.

`vtai init` creates `~/.vtaiagent` (audit DB + data dir), `~/Downloads`, and
`~/Documents/vt-data`, and writes a starter config with safe defaults:
`dry_run_default = true`, `deny_globs` for `~/.ssh`, `~/.gnupg`, `~/.aws` and
`**/.env`, and writable roots limited to `~/Downloads`, `~/Documents/vt-data`
and `~/.vtaiagent/tmp`. It is safe to re-run.

Check which config you ended up with — `vtai info` names the file and its
origin:

```bash
uv run vtai info
#   config file     : /Users/you/.vtaiagent/settings.toml (user-level)
```

<details>
<summary>Alternative: keep the checkout's config and override with env vars</summary>

A `.env` file (gitignored; copy `.env.example`) in the working directory
overrides any setting, using the `VT_` prefix with `__` for nesting:

```bash
VT_LOCAL__BASE_URL=http://localhost:13305/api/v1
VT_LOCAL__MODEL=<a pulled chat model>
VT_ACTIVE_PROVIDER=local
```

This is how a machine with no Ollama points the agent at a Lemonade server
instead. The `.env` is read from the **current working directory**, so run
the CLI from the checkout, or export the variables in your shell.
</details>

### Choosing a model

The planner/judge model comes from `active_provider`:

- `local` — any OpenAI-compatible endpoint: Ollama (`http://localhost:11434/v1`),
  llama.cpp, vLLM, LM Studio, Lemonade. No API key.
- `anthropic` / `openai` — cloud models; put `ANTHROPIC_API_KEY` or
  `OPENAI_API_KEY` in `.env`.

Set `cost_per_1k_input` / `cost_per_1k_output` in the provider block to make
`budget_usd_per_run` meaningful; without them the agent falls back to the
model's native price table.

### 3. Verify

Start with the preflight — it checks uv, your config, the writable roots,
what is protected, the optional tools, the model endpoint, the MCP
registration and any delegate waiting for review:

```bash
uv run vtai doctor
```

```
VT-AIAgent doctor — v0.6.2
  ✓  agent version      0.6.2
  ✓  uv                 0.13.1
  ✓  config file        /Users/you/.vtaiagent/settings.toml (user-level)
  ✓  config valid       no issues
  ✓  writable roots     3 present
  ✓  protected paths    4 deny globs
  ✓  shell allowlist    22 binaries
  ✓  model endpoint     http://localhost:11434/v1
  !  optional tools     not installed: ffmpeg (for transcode_media, voice helpers)
  ✓  mcp registration   opencode (global)
  ✓  pending approvals  none
```

It exits non-zero if something needs fixing. Then, to try the pieces:

```bash
uv run vtai info                         # config, provider, guardrails
uv run vtai tools                        # the registered tools
uv run vtai run system_info              # a read-only call, no LLM involved
uv run vtai goal --dry-run "list my Downloads"   # full loop with the model
```

### 4. Use it from your agent CLI

```bash
scripts/register-mcp.sh                  # opencode (global), claude (user), pi (CLI)
```

opencode's registration lands in `~/.config/opencode/opencode.jsonc` and
merges with your existing providers. The script registers an **absolute**
`uv` path on purpose: a bare `uv` fails with
`NotFound: ChildProcess.spawn (uv ...)` when the client spawns the server
from a daemon with a minimal PATH.

### Use

```bash
uv sync                                  # install
uv run vtai init                         # create/validate config, dirs, writable roots
uv run vtai info                         # show config
uv run vtai tools                        # list tools
uv run vtai run system_info              # invoke a tool
uv run vtai run run_shell --params '{"command":"ls ~/Downloads","dry_run":true}'
scripts/register-mcp.sh                  # register with opencode / claude
```

To get the `vtai` CLI outside the checkout, install it as an editable tool so
it tracks your working copy:

```bash
uv tool install --editable /path/to/vtai-agent   # -> ~/.local/bin/vtai
```

Install into another project as a dependency with
`uv add git+https://github.com/velsrocky/vtai-agent@v0.6.8`, or pull the
image with `docker build -t vtai-agent .`.

## Registry & distribution

PyPI: `uv tool install vtai-agent` (or `pipx install vtai-agent`) — publishes
on `v*` tags via Trusted Publishing with build attestations (see
`.github/workflows/publish.yml`). The `<!-- mcp-name: ... -->` comment above
is the PyPI-package proof the official MCP registry expects; `server.json`
carries the registry manifest (`io.github.velsrocky/vtai-agent`, stdio)
alongside a metadata-consistency gate in the publish workflow. Only install
from these sources; a similar repository name does not establish provenance.

Register with the official MCP registry after a PyPI release:
```bash
mcp-publisher auth --oauth2-github
mcp-publisher publish server.json
```

## Certification (vtai-cert)

Safety claims are probes, not prose: `vtai certify` runs the executable
guardrail-compliance suite (deny-glob containment, dotdot/symlink escapes,
fail-closed shell, injected-argv resistance, dry-run-first, kill switch,
audit exactness, echo-loop breaker, and the delegate's verify-then-trust
loop with scripted-fake rollback + approval-gate probes) and emits a
digest-stamped certificate;
exit 0 gates the release in CI. See [docs/certification.md](docs/certification.md).

## HTTP transport

`vtai serve --transport http --port 8765 --token $VT_HTTP_TOKEN` exposes the
same guarded tools over MCP StreamableHTTP at `/mcp`. The bearer token is
required when binding anything other than localhost; the server refuses to
bind externally without one.

## Development

```bash
uv sync --dev
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run python scripts/generate_tool_catalog.py --check   # tool-catalog doc drift
```

The config file is resolved as described in [Configure](#2-configure): `$VT_CONFIG`
→ the checkout's `config/settings.toml` → `~/.vtaiagent/settings.toml`. Env
overrides use the `VT_` prefix with `__` nesting (e.g.
`VT_GUARDRAILS__DRY_RUN_DEFAULT=fal