Installation

Valved is a Python CLI plus a Postgres-backed state store. It is Postgres-from-day-one — there is no SQLite fallback.

Requirements

• Python 3.11+
• Postgres 14+ — either the bundled docker-compose.yml (recommended for local dev) or your own (managed RDS, Cloud SQL, Supabase, etc.)
• Docker — only if you use the bundled Postgres path
• An Anthropic API key (or Claude OAuth token) for the AI harness — see Configuration

Install

Pick your favorite Python tool:

pipx install valved
# or
uv tool install valved
# or
pip install --user valved

After install, valved version should work.

First run with bundled Postgres

Dev-only credentials

The bundled docker-compose.yml uses default credentials (valved / valved) suitable for local development only. Do not expose this Postgres to the network. For any production-shaped install, use --external-postgres with credentials you control, or override via the DATABASE_URL env variable / state_store.url in runtime.toml.

mkdir my-valved-project && cd my-valved-project
valved init                  # writes valved.toml, valved/, .env.example, docker-compose.yml
docker compose up -d         # starts Postgres on 127.0.0.1:5432
valved serve                 # API + scheduler + worker; runs migrations on first boot

Behind the scenes:

• valved init writes valved.toml, the valved/ config dir, .env.example, and docker-compose.yml (the bundled-Postgres template).
• docker compose up -d brings up Postgres at the URL the .env template expects: postgresql+psycopg://valved:valved@127.0.0.1:5432/valved.
• valved serve runs alembic upgrade head on the empty Postgres, then starts accepting CLI / REST / MCP requests.

First run with external Postgres

If you already operate Postgres (managed RDS / Cloud SQL / Supabase / a local install):

valved init --external-postgres "postgresql+psycopg://user:pass@host:5432/db"
valved serve

The --external-postgres flag tells valved init to skip the docker-compose.yml scaffolding and record your connection string in .env instead.

Set your model credentials

The harness needs a model provider. Set one before you plan or build:

cp .env.example .env
# then edit .env to add ANTHROPIC_API_KEY (or a Claude OAuth token)
valved auth status           # verify the harness can see a credential

See Configuration → valved/models.toml for API-key vs OAuth and model tiers.

Verify the install

curl -s http://127.0.0.1:8765/healthz   # liveness
curl -s http://127.0.0.1:8765/readyz    # readiness (200 once migrations are at head)
valved runs list

If readyz returns 503, check valved serve logs — the most common cause is DATABASE_URL pointing somewhere unreachable.

Where to go next

• Quickstart — build your first pipeline end-to-end
• The core loop — how plan → build → run → deploy fit together
• MCP server — drive Valved from Claude Desktop / Cursor / Claude Code