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.
npxcomes 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 idsorts by the real ids, so the fakes come back out of order;WHERE total > 100compares real totals. - Values a query computes are faked by type.
length(email)ormax(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.