Install

This page covers the standard install. If you want to track main or contribute, see Install from source. If you want the fastest path to a working AI-assistant query, jump to Quickstart — it includes install plus the full setup flow.

Prerequisites

• Python 3.10 or newer. Check with python --version. faz uses async/await features and type-hint syntax that older Pythons don't have.
• A database to point faz at. faz supports 14 — see Databases overview. For a first install, any local Postgres / MySQL / Mongo is fine.
• (Optional) an MCP-compatible AI client like Claude Desktop, Cursor, or Claude Code, if you plan to use faz as an MCP server. The REST API works without any client.

Install

Pick the method you use. The selection persists across the docs — every other page that shows a faz <cmd> example will follow it.

pip install faz-core

pipx install faz-core

uv pip install faz-core

faz pulls in 30+ database driver packages — all 14 connectors plus FastAPI, MCP, and DuckDB. Expect 30–90 seconds for a fresh install.

Configure

Generate a starter config in your current directory:

faz init

uv run faz init

python -m faz init

This creates two things:

• faz.yaml — your config. Heavily commented; edit it to match your environment.
• .faz/ — a runtime directory where the audit log lives (.faz/audit.jsonl).

The generated faz.yaml looks like this:

databases:
  - name: postgres
    type: postgresql
    host: localhost
    port: 5432
    database: myapp
    username: ${POSTGRES_USER}        # ← env-var interpolation NOT yet implemented
    password: ${POSTGRES_PASSWORD}    #   set the literal value or use docker secrets

permissions:
  - database: postgres
    access: R                         # baseline applies to every table
    tables:
      <audit-table>:    W
      <writable-table>: RW

safety:
  max_rows_per_query: 5000
  queries_per_minute: 60
  query_timeout_seconds: 30
  auto_block_sensitive: true

Edit faz.yaml:

1. Replace the sample databases: entry with your real connection details. Per-connector specifics — what host, port, database, and extra: mean for each — are documented on the individual connector pages.
2. Set the permissions: block to match your trust model. Start with access: R and tighten or loosen per-table from there.

The full schema for every key, with every default value, is on faz.yaml.

If you'd rather not edit YAML by hand, an interactive wizard walks you through one connection at a time:

faz add-database

uv run faz add-database

python -m faz add-database

It prompts for connection type, host, port, credentials, and writes the entry to faz.yaml.

Verify

Print the loaded permission policy. This confirms faz.yaml parses cleanly:

faz policy

uv run faz policy

python -m faz policy

Expected output (for the default starter config):

<database>
    baseline: R
    overrides:
        <audit-table>     →  W
        <writable-table>  →  RW

safety:
    auto_block_sensitive   =  True
    max_rows_per_query     =  5000
    queries_per_minute     =  60
    query_timeout_seconds  =  30

If you see (no permissions loaded — check faz.yaml), your permissions: block didn't parse. Run faz init again or check Connection failed for parse-error messages.

To confirm faz can actually reach your database, start the REST server in one terminal:

faz serve

uv run faz serve

python -m faz serve

…and in another terminal, hit the health endpoint:

curl http://localhost:8787/v1/health

A reachable database returns:

{ "status": "ok", "version": "0.1.0", "databases_connected": 1 }

If databases_connected is 0, faz couldn't open the connection. The server logs the underlying error at startup; GET /v1/databases will show reachable: false with the error message for each failed connection.

Next steps