Docs: Getting started

Getting started

From nothing installed to your agent's first faked query in under a minute. Sosie writes its sosie.yml as it starts.

What you need

  • Node 24 or 26. npx comes with it.
  • An upstream: a PostgreSQL 15 to 18, MySQL 8.4 or 9, MongoDB 6.0 to 8.0, or SQL Server 2019 to 2025 database, or your team’s own REST or GraphQL API.
  • A read-only login for it. Sosie’s own session is read-only either way, but a login that cannot write is safer. Postgres, MySQL and SQL Server show one.

1. Start Sosie, in your own terminal

Run it in your project’s folder, in a terminal of yours, not the agent’s: the connection string is for Sosie only.

npx @sosie/cli

The first time, there is no sosie.yml yet: Sosie asks for your first source at a hidden prompt, and writes one.

  No sosie.yml here yet: one, with the first database or API Sosie reads.

  Its connection string, or the API's URL (hidden):
  ✓ A Postgres database: db.internal:5432/app
  A name for it (app):
  The variable to keep it in (APP_URL):
  ✓ Wrote sosie.yml: app, its upstream read from ${APP_URL}, never written there. Commit it.
    Set APP_URL in your terminal, and Sosie starts without asking for it.

  ✓ app  db.internal:5432/app, read-only: 42 tables, 3 views
  ✓ Every value is faked

  app:                       postgres://localhost:7674/app
  Claude Code:               claude plugin marketplace add monkilabs/sosie
                             claude plugin install sosie@sosie
  Any MCP client:            npx @sosie/cli mcp

sosie.yml names the variable, never the string:

sources:
  app:
    upstream: ${APP_URL}

Commit it. Next time, set APP_URL in your terminal, or type the string at the prompt again. It is never an argument: arguments show in shell history and the process list, where an agent can read them.

Every source of the project

Two databases, a REST API, a GraphQL API: list each under sources:, and one Sosie serves them all, each at an address of its own, from 7674 up. An API’s credentials go in headers, read from a variable too:

sources:
  app:
    upstream: ${APP_URL}
  billing:
    upstream: ${BILLING_API_URL}
    headers:
      Authorization: Bearer ${BILLING_TOKEN}

A URL with a graphql segment in its path (/graphql, /graphql/v1) is the GraphQL source; any other http(s) URL the REST source; kind: graphql says a GraphQL API elsewhere is one. Configuration has every key.

2. Point your agent at it

Everything that speaks the upstream’s protocol uses the address Sosie printed for its source, unchanged: the agent, your app, its tests, psql, curl, any Postgres MCP server.

$ psql postgres://localhost:7674/app -c 'SELECT u.full_name, o.status, o.total FROM orders o JOIN users u ON u.id = o.user_id'
    full_name     |  status   |  total
------------------+-----------+---------
 Janick Dach      | cancelled |  512.87
 Janick Dach      | paid      |    7.06
 Cristian Kuhlman | shipped   | 3916.25

Agents that prefer MCP get Sosie’s own server, which talks to the running Sosie and never to your database. In Claude Code, the plugin brings it with a skill that tells the agent how to read through Sosie:

claude plugin marketplace add monkilabs/sosie
claude plugin install sosie@sosie

Copilot, Cursor and Codex add the same marketplace. Any other MCP client takes the server in its configuration:

{
  "mcpServers": {
    "sosie": { "command": "npx", "args": ["@sosie/cli", "mcp"] }
  }
}

MCP and scan lists its tools.

3. Query by what you saw

Every value is a fake of the real one, of the same type and format. The same real value is always the same fake, so a value the agent saw finds its row again:

SELECT * FROM users WHERE email = 'van29@example.com';

Sosie turns van29@example.com back into the real email before the query runs, and fakes the row that comes back. The same goes for ids in API paths (/users/87) and GraphQL arguments (user(id: "87")).

4. Let through what must be real

If a fake breaks your app’s logic, a status that must be a real one, list that field in sosie.yml:

pass:
  - orders.status
sources:
  app:
    upstream: ${APP_URL}

At the top, a rule holds for every source that has the table; under a source, for that one. Configuration has every rule.

5. Check the transcripts

When it matters, check that nothing real reached a transcript or a log:

npx @sosie/cli scan ~/.claude/projects
  ✓ No real values found in 412 files.

It exits 1 when it finds a real value, so CI can run it.

Install it once

npm i -g @sosie/cli

Then the command is just sosie: sosie, sosie init, sosie mcp and sosie scan.

Good to know

  • Order and ranges follow the real values. ORDER BY id sorts by the real ids, so the fakes come back out of order; WHERE total > 100 compares real totals.
  • Values a query computes are faked by type. length(email) or max(id) are not the length or maximum of the fakes. count(…) passes unchanged.
  • Partial matches do not find fakes. LIKE '%van%' filters the real values, so a piece of a fake finds nothing.
  • Binary results (asyncpg, pgx, JDBC) are the fakes written as Postgres would send them. A type Sosie cannot write that way (regclass, money, composites, ranges) is refused in binary, with an error that names it.

Edit this page on GitHub