blog

    PVYai Agent: The Sovereign Coding Agent That Runs Anywhere

    Published Jul 13, 2026
    Updated Aug 14, 2026
    •

    A terminal-based AI coding assistant with 28+ model providers, multi-agent orchestration, and Swiss sovereignty — all in a single Go binary.

    Pvyai Agent 7a

    The Problem with Current Coding Agents

    Claude Desktop, Codex, Cursor, and similar tools share a common flaw: they're cloud-first, platform-locked, and resource-heavy. They require persistent internet connections, tie your code to a single provider, and run on Electron/Node.js stacks that consume hundreds of megabytes of RAM just to idle.

    For developers who care about sovereignty, PriVacY, and infrastructure freedom, these constraints are unacceptable.

    The PVYai Solution

    PVYai Agent is a terminal-based AI coding assistant built as a single Go binary. It runs in your shell, reads and writes your codebase, executes commands, and manages multi-agent workflows — all from a lightweight TUI (terminal user interface) built with Bubble Tea.

    It weighs in at ~256MB of RAM and runs on any machine that can run a terminal.

    Install Anywhere

    1# Via npm (recommended) 2npm install -g @pvyswiss/pvyai 3 4# Or direct download (macOS, Linux, Windows) 5curl -L https://github.com/pvyswiss/pvyai-coding-agent/releases/latest/download/pvyai-v0.x.x-macos-arm64.tar.gz | tar xz 6sudo mv pvyai /usr/local/bin/

    That's it. One binary. No Electron. No Node.js. No persistent cloud dependency.

    1cd your-project 2pvyai

    On first launch, the provider wizard walks you through choosing a model provider — or skip it entirely and set PVYAI_API_KEY to use the recommended PVY.ai Platform (Swiss sovereign AI on B300 GPUs). or just paste your API Key from your PVYai User Account into the TUI.


    What Makes PVYai Different

    1. 28+ Model Providers — Not Locked to One

    PVYai ships with 28+ built-in providers. Switch between them at runtime with /model or /provider — no configuration file edits required.

    ProviderUse Case
    PVY.ai Platform ★Swiss sovereign AI, B300 GPU, no data leaves Switzerland your dedicated environment or Switzerland at all, fine-tuned PVYai Models with up to 1M Context
    OpenAIFull model catalog
    AnthropicClaude models with reasoning, vision, prompt cache
    GoogleGemini with 1M context
    OpenRouterMulti-provider gateway with OAuth
    Ollama LocalRun models locally on your machine
    + 22 moreDeepSeek, Groq, xAI, Mistral, Bedrock, Vertex AI, and more

    Your code never belongs to a single vendor. Choose the right model for the right task:

    1# Quick edit — use a fast, cheap model 2pvyai --mode fast "Fix the typo in line 42" 3 4# Complex architecture — use deep reasoning 5pvyai --mode deep "Design the authentication system" 6 7# Long context — use 1M window 8pvyai --mode large "Review the entire codebase and propose refactoring"

    2. Multi-Agent Orchestration — Built In

    Claude Desktop and Codex are single-agent tools. PVYai Agent natively orchestrates teams of agents.

    Specialists — Delegate focused tasks to sub-agent processes:

    @explorer find the authentication retry logic
    @code-review review the last 3 commits
    @worker implement the feature in internal/auth/
    

    Each specialist runs as a real OS child process with its own model, tool allowlist, and reasoning effort. Read-only specialists (explorer, code-review) are auto-approved — no permission prompts.

    Swarms — Coordinate multiple agents in teams with mailbox communication, task handoffs, and scheduling:

    swarm_spawn(team="backend", agent_type="worker", task="Implement API")
    swarm_spawn(team="frontend", agent_type="worker", task="Build UI")
    swarm_send(to="frontend-worker", team="frontend", subject="API schema ready", body="...")
    backend_results = swarm_collect(team="backend")
    

    Teams of up to 8 concurrent members. Mailbox-based inter-agent communication. Scheduled recurring swarms. Pipeline workflows with handoffs between agent types.

    Loops — Schedule recurring agent jobs with standard cron expressions:

    1# Every 30 minutes: check CI status 2pvyai cron add "*/30 * * * *" --prompt "Check CI status for the current branch and report failures" 3 4# Daily 9 AM: progress summary 5pvyai cron add "0 9 * * *" --prompt "Write a short progress summary of what changed today"

    3. Plan-Driven Development

    PVYai enforces structure before action:

    Spec Mode (/spec) — Forces the agent to plan before acting:

    1. Draft phase: Agent inspects the codebase in read-only mode and writes a detailed spec
    2. Review phase: You review, edit, approve or reject the spec
    3. Implementation phase: A fresh agent run executes the approved spec

    Live Plans (update_plan tool) — The agent autonomously maintains a task list displayed as a live panel in your terminal:

    ┌──────────────────────────────────────────┐
    │ PLAN                                      │
    │ ◉ Add --version flag to main.go          │ ✓
    │ ◯ Update README                          │ ✓
    │ ◯ Add test                               │ ◌ in_progress
    └──────────────────────────────────────────┘
    

    4. Skills — Reusable Instruction Sets

    Skills are SKILL.md files that the agent loads on demand. Install from git, create locally, or share with your team:

    1pvyai skills add https://github.com/your-org/deploy-checks-skill.git

    The agent proactively matches your request to available skills and loads their instructions — no manual invocation needed.

    5. Evals — Validate Agent Behavior

    PVYai includes a full evaluation harness for testing agent behavior:

    1# Run a full benchmark across multiple models 2pvyai eval bench \ 3 --suite evals/regression.json \ 4 --agent-command "pvyai exec --cwd {workspace} --model {model} {prompt}" \ 5 --model claude-sonnet-4.5 \ 6 --model gemini-2.5-pro \ 7 --report-dir /tmp/eval-reports

    Score your agent's output against verification commands, expected file changes, forbidden files, and trace events. Compare models side-by-side. Track improvement over time.

    6. Swiss Sovereign AI by Default

    The recommended provider is PVY.ai Platform — a Swiss sovereign AI endpoint running Open WebUI + several backends on NVIDIA B300 GPUs (282GB VRAM). Your code, your prompts, your data — never leaving Swiss jurisdiction.

    • Qwen 3.6 35B MoE (3B active) at highspeed on our Infra tunneled to your environment
    • 128K context window
    • Zero external cloud dependency
    • PVYai Sentinel security layer intercepts destructive commands at the SSE-stream level

    7. Worktree Isolation

    Run multiple agents in parallel on the same repository without interference:

    1# Terminal 1: Refactor auth module 2pvyai exec -w refactor-auth "Refactor internal/auth/ to use interfaces" 3 4# Terminal 2: Add database tests (concurrent, zero interference) 5pvyai exec -w add-db-tests "Add integration tests for internal/db/" 6 7# Terminal 3: Continue your work (unaffected) 8pvyai

    Each agent gets its own git worktree — a detached HEAD copy of your repo. Merge results with git cherry-pick when done.

    8. Notifications — Stay Informed

    When a long-running agent completes or needs your input, PVYai Agent notifies you via:

    • Terminal bell — subtle audible cue
    • Desktop notification — OSC-9 escape sequence, visible in Dock or SysTray
    • Matrix / PVYmessenger webhook — HTML-formatted messages with avatar and display name and description
    1export PVYAI_NOTIFY_WEBHOOK_URL="https://whapi.pvy.im/api/v1/matrix/hook/..." 2export PVYAI_NOTIFY_WEBHOOK_DISPLAY_NAME="PVYai Agent"

    9. PVYai Sentinel & PVYai Memory Integration

    Instead of working with the classic Model Eval and Evict schema (number of tool calls, number of turns), you can, if:

    • A) You only use the LLM model provided by the PVYai platform (including all Anthropic, GLM, and DeepSeek models offered through it).
    • B) You don't want to configure the Team Agents and Specialists.

    Select the PVYai Sentinel Orchestrator, which automatically orchestrates the fine-tuned LLMs provided by PVYai for various tasks and roles, ensuring that the right model is used for each specific task in the plan.

    This allows you to benefit from real-time analysis by PVYai Sentinel of how the models are performing for their planned use in the team, maximizing coding or team capacity instead of retiring a model shortly before a goal is reached, only to re-initialize it with fresh, empty context.

    Furthermore, PVYai Memory is available for all (including manually orchestrated agents and specialists) for use in the PVYai Agent, as well as (which can be enabled or disabled) PVYai Sentinel Safeguarding, which monitors the planned interactions of the agents with the code or infrastructure in real time.


    Feature Comparison

    FeaturePVYai AgentClaude DesktopOpenAI CodexCursor
    Binary size~256MB RAM, single Go binaryElectron (~800MB+)Cloud-onlyElectron (~600MB+)
    Install anywhere✓ Any terminal, any OSmacOS/Windows onlyWeb browserVS Code extension
    Model providers28+ (PVY, OpenAI, Anthropic, Google, Ollama, +22 more)Anthropic onlyOpenAI onlyMultiple (paid tiers)
    Local models✓ Ollama, LM Studio, any OpenAI-compatible✗ Cloud only✗ Cloud onlyLimited
    Multi-agent orchestration✓ Specialists, Swarms, Loops✗✗Limited
    Plan-driven development✓ Spec mode + live plans✗✗Basic
    Skills system✓ Reusable SKILL.md sets✗✗Prompt libraries
    Eval harness✓ Full benchmark framework✗✗✗
    Worktree isolation✓ Parallel agents, zero interference✗✗✗
    Cron loops✓ Scheduled recurring agents✗✗✗
    Swiss sovereignty✓ Default provider✗✗✗
    Open source✓ GitHub releases✗✗Partial
    OAuth login✓ OpenRouter, xAI, ChatGPT, Hugging Face✗✗✗
    Permission modes✓ ask / auto / unsafe / spec-draft✗✗Basic
    Session lineage✓ Fork/rewind/trace✗✗✗

    Architecture

    ┌─────────────────────────────────────────────────────┐
    │                    Your Terminal                     │
    │                                                      │
    │  ┌──────────────────────────────────────────────┐   │
    │  │  PVYai TUI (Bubble Tea)                      │   │
    │  │  ┌────────────────────────────────────────┐  │   │
    │  │  │  you: Refactor the auth module          │  │   │
    │  │  │  PVYai: ◌ explorer · ✓ worker · ◌ plan │  │   │
    │  │  │  > _                                   │  │   │
    │  │  └────────────────────────────────────────┘  │   │
    │  └──────────────────────────────────────────────┘   │
    │           │          │          │                     │
    │     ┌─────┘    ┌────┘    ┌───┘                        │
    │     ▼          ▼        ▼                              │
    │  @explorer  @worker  @code-review                     │
    │  (read-only) (edit+exec) (read-only)                  │
    │     │          │        │                              │
    │     ▼          ▼        ▼                              │
    │  pvyai exec  pvyai exec  pvyai exec                   │
    │  (child proc) (child proc) (child proc)               │
    └─────────────────────────────────────────────────────┘
                │
                ▼
        ┌───────────────┐
        │  Model Router  │
        │               │
        │ PVY.ai ★      │  ← Swiss sovereign (default)
        │ OpenAI        │
        │ Anthropic     │
        │ Ollama Local  │
        │ + 24 more     │
        └───────────────┘
    

    Getting Started

    Quick Start (PVY.ai Platform — Recommended)

    1npm install -g @pvyswiss/pvyai 2export PVYAI_API_KEY="your-api-key" 3cd your-project 4pvyai

    The wizard detects your API key and skips credential entry. Your model defaults to qwen3.6:35b (Qwen 3.6 35B MoE, 110 tok/s on H200).

    Quick Start (OpenAI)

    1export OPENAI_API_KEY="sk-..." 2pvyai

    Quick Start (Anthropic)

    1export ANTHROPIC_API_KEY="sk-ant-..." 2pvyai

    Quick Start (OAuth — OpenRouter)

    1. Run pvyai — the wizard opens
    2. Choose "Sign in with OAuth"
    3. Select "OpenRouter"
    4. Authorize in your browser
    5. PVYai mints and stores your API key automatically (keyring on macOS, encrypted file on Linux)

    Headless / SSH Setup

    For servers without a browser, use the device-code flow:

    1. Choose "Sign in with OAuth"
    2. Press d for device-code flow
    3. Visit the displayed URL on any device
    4. Enter the code — authorization completes

    Configuration

    PVYai uses two config files:

    FileScopePath
    User configPersonal, all projects~/.config/pvyai/config.json
    Project configShared with team<project>/.pvyai/config.json

    Minimal config

    1{ 2 "activeProvider": "pvyai", 3 "providers": [ 4 { 5 "name": "pvyai", 6 "provider": "pvyai", 7 "baseURL": "https://yourpvyai-api-url/api", 8 "model": "PVY-Coder-Deep" 9 } 10 ], 11 "maxTurns": 50 12}

    Multi-provider config

    1{ 2 "activeProvider": "pvyai", 3 "providers": [ 4 { "name": "pvyai", "provider": "pvyai", "model": "qwen3.6:35b" }, 5 { "name": "anthropic", "provider": "anthropic", "model": "PVY-Coder-Deep" }, 6 { "name": "ollama-local", "provider": "ollama", "model": "qwen2.5-coder:32b" } 7 ] 8}

    API keys are never stored in config files — they go to the encrypted credential store or environment variables.


    Modes — Pre-Bundled Presets

    ModeModelReasoningMax TurnsUse Case
    smartclaude-sonnet-4.5medium50General-purpose coding
    deepclaude-opus-4.1high50Complex reasoning, architecture
    fastclaude-haiku-4.5low15Quick edits, autocomplete
    largegemini-2.5-promedium50Long-context tasks (1M ctx)
    preciseclaude-sonnet-4.5high50Careful, thorough work
    1pvyai --mode deep "Refactor the authentication module"

    Why PVYai Agent matters

    For Developers Who Care About Sovereignty

    Your code is your code. PVY.ai Platform ensures your prompts, your context, and your agent's decisions never leave Swiss jurisdiction. No US CLOUD Act, no EU data retention directives, no vendor lock-in.

    For Teams Who Need Structure

    Spec mode forces planning before action. Live plans track progress in real-time. Evals validate behavior across model upgrades. Worktree isolation lets agents experiment without touching your working tree.

    For Operators Who Hate Bloat

    A single Go binary. 256MB RAM. No Electron. No Node.js. No persistent cloud dependency. Run it on a Raspberry Pi, a Proxmox LXC container, or a production server — it works the same everywhere.

    For Researchers Who Compare Models

    Run the same eval suite across 28+ providers. Compare pass rates, token usage, and speed side-by-side. Find the best model for each task type. Track improvement over time with report diffing.


    CLI Quick Reference

    1pvyai # Interactive TUI shell 2pvyai exec "fix the bug in auth.go" # One-shot prompt 3pvyai exec --model claude-sonnet-4.5 "refactor auth" 4 5pvyai setup # Guided provider setup 6pvyai auth login openrouter # OAuth login 7pvyai auth status # Token status 8 9pvyai providers # Inspect configured providers 10pvyai models # List model registry entries 11pvyai doctor # Health checks 12 13pvyai skills list # List installed skills 14pvyai skills add <git-url> # Install a skill from git 15 16pvyai specialist list # List specialist definitions 17pvyai specialist create <name> # Create a specialist 18 19pvyai mcp list # List MCP server backends 20 21pvyai cron add "0 9 * * *" --prompt "..." # Schedule a job 22pvyai cron run # Start the cron loop 23 24pvyai eval --suite evals.json # Validate a suite 25pvyai eval bench --suite evals.json # Full benchmark 26 27pvyai search "authentication" # Search sessions 28pvyai sessions # Inspect session lineage 29pvyai version # Print version 30pvyai update # Check for updates

    PVYai Agent Teams

    It's not limited to coding only. You can run with PVYai Agent "human-less" autonomous companies or operations, such as a Sales & Marketing Team. In combination with PVYlime Desktop, we provide native VM Templates for it, where the latest PVYai Agent is always present.

    You can configure for each project your Agent Teams, Swarm and Loops manually, or you choose "PVYai Agentic Orchestrator" and he will team up based on whats need right now for this particular task, the right PVYai Model for you.

    License & Availability

    PVYai Agent is available as a Go binary via npm (@pvyswiss/pvyai) and GitHub releases at github.com/pvyswiss/pvyai-coding-agent.

    Supported platforms: macOS (Apple Silicon, Intel), Linux (x86_64, ARM64), Windows. MIT License. Please note, to benefit from the PVYai Models, a PVYai Subscription is required. But you can use it freely with any AI Provider of your choice.

    Documentation


    PVYai Agent is part of the PVY.ai Platform — a Swiss sovereign AI ecosystem built on Open WebUI as Frontend, 13+ MCP tool servers and 25+ own fine-tuned PVYai Models. Built for developers who refuse to choose between AI capability and infrastructure freedom.