Vtai Agent

VT-AIAgent

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

Tools

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

1. Install

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 machine with no config file anywhere fails loudly on first use — the built-in defaults leave nothing protected (shell_allowlist empty) so nothing runs, and vtai info says so plainly ("no config file there"). vtai init writes a starter config; vtai init --doctor runs the full preflight right after it.

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:

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. Use vtai init --doctor to run the preflight immediately after writing. It is safe to re-run.

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

uv run vtai info

config file : /Users/you/.vtaiagent/settings.toml (user-level)

Alternative: keep the checkout's config and override with env vars

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

VT_LOCAL__BASE_URL=http://localhost:13305/api/v1

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

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:

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:

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

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

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:

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.7.0, 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 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:

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.

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

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: $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=false). Config is validated at startup (validate_settings) — a bad deny_globs pattern or a missing writable root fails fast, not mid-run.

Windows: the shell sandbox needs the allowlisted binaries to resolve, and a fresh Windows runner does not put Git for Windows' coreutils on PATH. Install Git for Windows and prepend its usr\bin (this is what CI does):

Add-Content $env:GITHUB_PATH "C:\Program Files\Git\usr\bin"   # CI

locally: add "C:\Program Files\Git\usr\bin" to your PATH

Everything else (install, config, MCP registration) is the same on all three platforms.

Orchestrator

vtai goal runs a bounded ReAct-style agent loop. Each step the model either emits one fenced-JSON tool call (parsed, guarded, executed, result fed back) or a final natural-language answer. Bounds enforced every step: max_steps, kill switch, and budget_usd_per_run. A lonely dry_run: true text blob that fails to parse or misses its tool key is retried with a corrective note instead of ending the run as "success"; the run mode is authoritative — the model cannot override it — and every tool call is persisted as a Step row and audit entry. If a paid provider's spend can't be determined (no cost_per_1k_* config and no native cost), the run fails closed rather than reporting free. The system prompt describes the machine's actual OS.

We use a text protocol rather than native function-calling on purpose: the local Ollama models on this box emit tool calls as raw JSON text even when native tool schemas are provided (verified 2026-10-03 with qwen2.5-coder:7b), so the text p