> **BETA. USE AT YOUR OWN RISK. SOV is provided "as is", with no warranty of any kind. It runs AI agents that execute commands, edit files and make network calls on your machine. Install it only on a machine, and with accounts, you can afford to lose. You are responsible for your AI vendor accounts, their terms of service, and every charge they bill you. Versions may change, break or lose data without notice. Do not use it for production, regulated or sensitive data. By installing, you accept these terms.**

# SOV-AGENT beta (stage 2): what it is, what it needs, where we expect it to break

Private beta. Please do not share this address. Linux and macOS, Python 3.12 or newer.

## Install

    curl -fsSL https://sov.works/beta/8b467bd3c431e9436c582f688720225a/install-agent.sh | sh

Installs sov-agent, sov-log and sov-src into ~/.sov-agent (or --prefix DIR): no sudo, nothing started, no provider login needed.
Third-party dependencies are hash-locked (`requirements-third-party.txt`). The three SOV wheels are checked against SHA256SUMS
(which sits on the same host, so it only detects corruption; compare its own hash with the one the project owner sent you).

Bundle: see VERSION. The docs in docs/ are copies of README.md, INSTALL-FLEET.md and the v1 caller guide at that exact commit.

## What SOV-AGENT is

A dispatcher that lets one AI agent offload thinking and coding to other model CLIs and APIs, with pacing, budgets and audit.
Read docs/README.md first, then docs/v1-CALLER-GUIDE.md (the v1 broker and the MCP server `sov-agent mcp`).

## What it needs before it does anything (this is the stage-2 test)

- An Agent-owned PostgreSQL database (`SOV_AGENT_DATABASE_URL`, driver `postgresql+psycopg://`, NOT `postgresql://`).
- A running SOV-JOBS service (stage 1) and its credentials (`SOV_JOBS_TOKEN`), plus `SOV_AGENT_TOKEN`, `SOV_AGENT_PROFILE_ID`,
  `SOV_AGENT_PROFILE_REVISION` (see docs/README.md, "Installation and configuration").
- An immutable profile provisioned separately (`sov_agent/profile_install.py` in the wheel is the place to look).
- The v1 broker (`sov-agent serve-v1`) with a model catalog (`sov-agent v1-catalog-install --catalog-json ...`) and a caller token.
- At least one lane. On this box you have NO subscription CLIs (Claude, Codex, Cursor, Grok are never installed on a test box).
  The only lane you can use is the metered OpenRouter one (opt-in: `v1-caller-put ... --overflow`; a call with a workspace also
  needs `--allow-uncapped-metered-cli` and the `opencode` CLI). Use only the funded test key you were given, and report SPEND.

## Stage 2b files (added after the first outsider run)

- `catalog-openrouter-min.json`: the smallest catalog that passes `validate_catalog`, ONE OpenRouter lane. Every `REPLACE-WITH-...`
  value is host-specific (binary paths and their sha256, the Jobs URL and service id, the sha256 of your key, never the key).
- `QUICKSTART-LINUX-OPENROUTER.md`: the ordered steps, each fact cited to a source file. Its last section lists what still needs a human.
- `make_jobs_bundle.py`: reads your catalog and writes the SOV-JOBS bundle (the `agent.call` definition, a submit credential and one
  worker credential per client). Run it inside the sov-agent venv, then `python -m sov_jobs.v2 install-bundle --bundle-json jobs-bundle.json`
  in your stage-1 SOV-JOBS environment. Both files are candidate a531a8e (docs, unmerged) plus a steward helper.
- Known gaps the quickstart states: no public Linux worker start, no public credential-free broker script, no shipped opencode binary,
  a spend ledger (`SOV_AGENT_SPEND_LEDGER`) with a real prepaid cap is required for metered calls. Stop where you cannot go further and report where.

## Where the steward expects it to break (please confirm or disprove each)

1. There may be no documented way for a newcomer to create the Agent database and the first profile (no `init`-style command).
2. The v1 catalog format may be undocumented outside the fleet's own deploy script; a newcomer may not be able to write one.
3. Secrets: the docs assume a native OS secret store (Windows Credential Manager); on Linux the tokens must come from the environment.
4. Overflow to a metered lane is described as "only when subscription lanes are full or long-busy": with no subscription lanes it
   may never trigger, or may refuse for a reason that is hard to read.
5. The wheel's metadata declares sov-src as a private git link, so a plain pip install cannot resolve it: the installer uses --no-deps.
6. The documented install is a Windows-qualified, hash-bound offline procedure (docs/INSTALL-FLEET.md); Linux is unqualified.

## Your task

Follow ONLY what this page and the docs say, in this order, and report the FIRST honest failure at each step: exact command,
exit code, what you expected, what happened, every place you had to guess.
1. Install (one-liner above). Does it exit 0? Is the CLI named as documented?
2. `sov-agent --help` and each subcommand's `--help`: can a newcomer tell what to run first?
3. Bring up a Postgres for SOV-AGENT (your own throwaway container, invented values, removed afterwards).
4. Try to reach a working `agent_ask` (a read-only question, no workspace) through the v1 broker using ONE OpenRouter model,
   with the smallest cost cap the docs allow. Stop at $10 of spend and ask.
5. Try the MCP server (`sov-agent mcp`) from your own MCP-capable app if it supports a local stdio server.
Write the report as a mailbox message (out/). Never put a key in it.