Configuration
One file, sosie.yml, says everything Sosie reads and how it fakes it. sosie init writes it with your first source.
sosie.yml
The only configuration there is: no flags, and no variable of Sosie’s own but SOSIE_HOME, where its store is. It
lives in the folder you start Sosie in, is committed with the code and reviewed like code. It names every source of
the project, a database or an API, each by a name of your own.
# For every source; a source may set its own.
max-rows: 1000
timeout: 30
pass:
- orders.status
- countries.*
format:
users.handle: username
sources:
shop:
upstream: ${SHOP_DATABASE_URL}
crm:
upstream: ${CRM_DATABASE_URL}
port: 7700
pass: [contacts.region]
billing:
upstream: ${BILLING_API_URL}
headers:
Authorization: Bearer ${BILLING_TOKEN}
schema: ./openapi/billing.yaml
storefront:
upstream: ${STOREFRONT_URL}
kind: graphql
schema: ./storefront.graphql
npx @sosie/cli starts one Sosie for all of them, each at an address of its own. Without a sosie.yml, it asks for
your first source and writes one, as npx @sosie/cli init does.
Every key
| Key | Where | Default | |
|---|---|---|---|
sources |
the top | none: at least one | Each source by its name: lowercase letters, digits, - and _, a letter first |
upstream |
a source | none: required | ${NAME}: the variable that holds its connection string or base URL |
kind |
a source | from the URL | postgres, mysql, mongodb, sqlserver, rest or graphql, for a URL that does not say: GraphQL at /query |
schema |
a REST or GraphQL source | the API’s own: its OpenAPI document if it serves one, or introspection | A file, by its path from sosie.yml, or a URL: an OpenAPI document, or GraphQL SDL or an introspection result as JSON |
headers |
a REST or GraphQL source | none | Headers Sosie sends the API: Authorization: Bearer ${TOKEN} |
refuse |
a REST source | none | Paths Sosie never sends a request to, each with every path under it: [/oauth/*, /billing/portal] |
port |
a source | the next free from 7674, in the order listed | 0 lets the system pick |
host |
the top, or a source | 127.0.0.1 |
Another address is allowed, with a warning: the endpoints have no password |
max-rows |
the top, or a source | 1000 |
Rows a query returns, and items of each list in an API’s answer |
timeout |
the top, or a source | 30 |
Seconds a statement, a command or a request may run upstream, from 1 to 3600. The MCP tools request and graphql wait 50 s at most either way; query, find and aggregate wait this long |
pass |
the top, or a source | none | Fields whose values come back unchanged |
format |
the top, or a source | none | Formats for fields Sosie cannot tell from their names |
A key a source cannot use is an error that says why: a Postgres source takes no headers.
Credentials
A connection string, a password or a token is never written in sosie.yml, nor given as an argument: arguments show in
shell history and in the process list, where an agent can read them. sosie.yml names the variable that holds it,
${NAME}, and Sosie reads it from the terminal it starts in, or asks for it at a hidden prompt. The names are yours:
reuse what your app already has.
export SHOP_DATABASE_URL='postgres://readonly:…@db.internal:5432/shop'
export BILLING_TOKEN='…'
npx @sosie/cli
Only upstream and the values of headers read variables. upstream is always one whole variable, never a URL
written out, not even in part: Sosie refuses one, so a file an agent can edit never names a host. A header may hold
text around its variable (Bearer ${TOKEN}): headers go only to their own source’s upstream. Write $$ for a $.
The first time a source is to send a variable, Sosie shows what it sends and where, and asks, before anything is sent:
! sosie.yml has a source send a variable it has not sent to its upstream before:
billing sends BILLING_TOKEN, in Authorization, to billing.internal/v1 (BILLING_API_URL).
Send it? (y/N)
Your yes is kept on your machine, in ~/.sosie/allowed.json, never in sosie.yml: an agent that edits the file to
have a header carry another variable, or send one to another upstream, is asked about the same way. Without a
terminal to ask in, Sosie stops and says so; start it in a terminal once.
A short-lived token need not mean a restart. When a REST or GraphQL API answers 401, as it does once a token has
expired, Sosie asks in its terminal for the variables that source’s headers read, at a hidden prompt:
! billing: the API answered 401: a value its headers send may have expired.
BILLING_TOKEN, a new value (hidden), or Enter to keep it:
Every source that reads a variable you type sends the new value from then on, and Sosie keeps running, with all it has learned. Enter keeps the old one, and Sosie asks again only after the API has answered with it. Without a terminal it asks nothing, and a new value needs a restart.
Field ids
| Source | A field’s id |
|---|---|
| Postgres | table.column, or schema.table.column outside public |
| MySQL | table.column, or database.table.column outside the database the connection string names |
| MongoDB | collection.path, a nested field’s path dotted (users.address.city), or database.collection.path outside the database the connection string names |
| SQL Server | table.column, or schema.table.column outside the login’s default schema (dbo) |
| REST, with a document | Schema.property, nested properties dotted: User.address.city |
| REST, without one | The entity its path names, singular, and the key: user.email |
| GraphQL | Type.field: User.email |
entity.* names every field of an entity. The MCP tool describe lists the fields each source has, and which pass.
A field’s id carries no source’s name: two sources with a users table share its fakes, so a person is one fake in
both, and adding a source never changes another’s.
pass
Values of a listed field come back unchanged. Use it for what your app’s logic needs to be real: statuses, prices, reference tables such as countries. A field that passes still never shows a value the request turned back from a fake.
At the top, a rule holds for every source that has the table; under a source, for that one. A field that shares another’s values cannot pass alone, or joins between them would break:
sosie.yml: orders.user_id passes but users.id, whose values it shares, does not. List both or neither.
format
Gives a field a format its name does not say. The formats:
email, phone, first_name, last_name, full_name, street, city, postal_code, country, company,
username, url, iban, text, shape
Personal formats (email, phone, the names, street, city, postal code) share fakes across fields and sources: one person’s email is the same fake wherever it appears. A source’s own format for a field wins over the top’s.
Checked at start-up
An unknown key, source, entity, field or format stops Sosie with an error that names it, so a typo never lets data through silently. Every problem is listed at once:
sosie.yml: sources.crm: contacts.regoin is not a field. Did you mean contacts.region?
sosie.yml: users.nick is not a field of shop's users. A rule for one source goes under it.
A rule at the top that no source has the table for is an error too. A source that learns its fields as answers come,
REST without a document and MongoDB, keeps a rule for a field it has not met, and applies it once it does, with a
warning: one of its own, or one at the top that no source knows yet. Read the warnings Sosie starts with, as one may be
a typo. entity.* holds for the fields such a source meets later too.
The commands
| Command | What it does |
|---|---|
sosie |
Start every source sosie.yml names. Without a sosie.yml, in a terminal, sosie init first |
sosie init |
Write sosie.yml with your first source, its connection string asked for at a hidden prompt |
sosie mcp |
An MCP server over stdio, for every running Sosie |
sosie scan <path>… |
Search files and folders for real values; exit 1 if one is found |
--help and --version are the only flags. Exit codes: 0; 1 for a failure (a problem in sosie.yml, a source
that cannot connect, a port in use, a real value found by scan); 2 for a usage error.
sosie init asks for the first source’s connection string, says what it found there, and asks for a name for the
source and the variable to keep the string in. It writes sosie.yml with those, never with the string; a
sosie.yml that has rules only gets the source added, its rules kept. Add any other source under sources: by hand.
SOSIE_HOME, where Sosie keeps its store (~/.sosie by default), is the one variable of its own: it is the machine’s,
not the project’s.
Upgrading from 0.3 and earlier
SOSIE_UPSTREAM, SOSIE_UPSTREAM_HEADERS, SOSIE_OPENAPI, SOSIE_GRAPHQL_SCHEMA and the flags --port, --host,
--rules and --max-rows are gone: each is a key of sosie.yml. With SOSIE_UPSTREAM still set, this
reads it:
sources:
app:
upstream: ${SOSIE_UPSTREAM}
Sosie says so when one of them is still set and sosie.yml does not name it, and a flag given says where it went.
Several projects
One Sosie serves every source of a project. Another project’s Sosie, started in its own folder, takes the next free
ports. All of them share one store, so a person is the same fake everywhere, and sosie mcp serves them all: its tools
take a source, by its name, when several of a kind run.
Each running Sosie writes ~/.sosie/running/<pid>.json for sosie mcp: each source’s name, kind, address, schema and
the fields that pass. Nothing real: no upstream, no credentials, no values. It is removed when Sosie stops.
Defaults
| Setting | Default |
|---|---|
| Address | 127.0.0.1, the first source at 7674 and each next at the next free port, and ::1 |
| Rows per query; items per list of an API’s answer | 1,000 |
| Rows per MCP query | 200 |
| Statement timeout upstream | 30 s |
| Store | $SOSIE_HOME/store/, or ~/.sosie/store/ |