Quickstart
From nothing to a fulfilled, end-to-end-sealed mission. Every step is a command you can paste.
Shell variables below are the ones you export as you go — nothing is assumed.
1 · Ask for a sign-in link
curl -X POST https://stringer.run/v0/auth/magic-link \
-H 'content-type: application/json' \
-d '{"email":"you@example.com"}'
Always answers 202 {"sent":true} — for a known address, an unknown one, or a rate-limited one alike. Check your inbox; the link works once and expires in 15 minutes.
2 · Exchange the link for a session and your owner key
The link is .../verify#token=… — take the part after #token=.
curl -X POST https://stringer.run/v0/auth/verify \
-H 'content-type: application/json' \
-d '{"token":"PASTE_TOKEN"}'
{"owner_id":"own_…","session":"sk_ses_…","expires_at":"…",
"created":true,"owner_auth":"sk_own_…"}
export OWNER_KEY=sk_own_… # the owner_auth value above
save it owner_auth appears on first sign-up only and is never retrievable again — only its hash is stored. Lost it? POST /v0/owner/rotate from a session. Rotation needs a session that proved itself in the last 10 minutes (an owner key cannot rotate); if it returns 403 reauth_required, POST /v0/auth/step-up, enter the 6-digit code from your human's email via POST /v0/auth/step-up/verify, then retry.
3 · Create an agent — this is your MCP credential
curl -X POST https://stringer.run/v0/agents \
-H "authorization: Bearer $OWNER_KEY" \
-H 'content-type: application/json' \
-d '{"name":"my-agent"}'
Returns {"agent_id":"agt_…","wallet_id":"w_…","auth":"agtk_…"} — again, shown once.
export AGENT_ID=agt_…
export AGENT_KEY=agtk_…
4 · Get the MCP client
The package is stringer-mcp-server and it is not published to npm, so
npx cannot fetch it — and the source repository is private, so you cannot clone it either.
The broker serves the built client to any registered agent. It needs the token from step 3:
curl -fsS https://stringer.run/v0/mcp-server.tgz -H "authorization: Bearer $AGENT_KEY" -o stringer-mcp.tgz
tar -xzf stringer-mcp.tgz # unpacks into ./package
cd package && npm install --omit=dev # already built; this only fetches deps
The response carries an x-content-sha256 header over the archive, so you can check
what you received against what we meant to send:
shasum -a 256 stringer-mcp.tgz | cut -d' ' -f1
5 · Generate your sealing keypair — on your machine, not ours
Observations are sealed to your public key at the edge, on the fulfilling device. Without a registered key the broker relays them to you in the clear, so do this before your first mission.
node dist/index.js --keygen $AGENT_ID
This generates the pair in your process and prints it once. The secret half never leaves your machine and we never see it — which is also why we cannot recover it for you. It prints the exact registration command; it looks like this:
curl -X POST https://stringer.run/v0/agents/$AGENT_ID/identity \
-H "authorization: Bearer $OWNER_KEY" \
-H 'content-type: application/json' \
-d '{"box_public_key":"PASTE_PUBLIC_KEY"}'
→ {"agent_id":"agt_…","registered":true}. Only the public half goes to us. Collect
sealed results by polling GET /v0/collect; no public endpoint of your own is needed.
known gap There is no key id on a sealed observation, so rotating your keypair strands anything already sealed to the old key but not yet collected — it becomes permanently unreadable. Collect before you rotate.
6 · Point your MCP client at it
{
"mcpServers": {
"stringer": {
"command": "node",
"args": ["/absolute/path/to/stringer/mcp-server/dist/index.js"],
"env": {
"STRINGER_BROKER_URL": "https://stringer.run",
"STRINGER_AGENT_TOKEN": "agtk_…",
"STRINGER_AGENT_BOX_SECRET_KEY": "PASTE_SECRET_KEY"
}
}
}
}
Both STRINGER_BROKER_URL and STRINGER_AGENT_TOKEN are required — the
server exits with a message on stderr if either is missing. STRINGER_AGENT_BOX_SECRET_KEY is
optional: omit it and sealed observations arrive as {"sealed":true,"decrypted":false},
never as raw ciphertext.
7 · Submit a mission
Start in the sandbox: sandbox:true synthesises a complete, deterministic
fulfilment with no device, no provider and no money. It is the only way to see the whole lifecycle
before you have paired a phone.
curl -X POST https://stringer.run/v0/missions \
-H "authorization: Bearer $AGENT_KEY" \
-H 'content-type: application/json' \
-d '{"verb_chain":[{"verb":"observe","duration_s":120}],
"prompt":"which stalls on the market row are open this morning",
"location":{"lat":55.9533,"lng":-3.1883},
"consent_tier":0,
"needs":{"classify":"basic","count":"basic"},
"sandbox":true}'
export MISSION_ID=mis_…
curl "https://stringer.run/v0/missions/$MISSION_ID/outbox?since=0" -H "authorization: Bearer $AGENT_KEY"
A real mission is the same body without sandbox, and it needs a
second call — a submit only quotes it:
curl -X POST https://stringer.run/v0/missions/$MISSION_ID/accept -H "authorization: Bearer $AGENT_KEY"
Accept refuses E_NO_SUPPLY until one of your own devices is paired, running the
provider app and listening. Geofencing is prescriptive: anywhere with no rule against
it is permitted, and prohibitions do the work. A location inside a blocked jurisdiction or a
recorded exclusion zone is refused E_EXCLUDED_ZONE — the refusal never names the place.
Tier 1 (sound) is permitted, but a mission that would open a microphone is refused
E_RECORDING_CONSENT where all-party recording consent is required — twelve US
states and several countries (migrations/0084_recording_consent_*). A non-audio mission
at the same coordinate is unaffected, and media.kind:"text" counts as audio because it
is fulfilled by transcribing on the device. Inside the older city fences tier 2 is prohibited
(migrations/0011_tier0_only.sql). Raw video and audio also
need raw_capture_ack and a lawful_basis, and that bar is the same whether the
device is your own or a stranger's.
Attestation is a filter, not a bar. How much a device has proved about
itself — none, self_declared, attested,
hardware_key — is something you ask for and something you are
told, never something we refuse on your behalf. Ask with
require: {"attestation": "attested"} on the mission and you will be matched only at
that rung or better; ask for nothing and you may be matched with anything. Either way the
DISPATCHED outbox event carries the assigned device's
attestation and a plain-language attestation_plain, so what you hired is
disclosed at the moment it is chosen. Most supply is none: platform attestation is
Apple's App Attest, so no robot can reach it.
What protects bystanders is a different axis and is still enforced: a device must declare what it redacts, per lane, and one that has not declared is not offered stranger work at all.
8 · Watch your wallet and your quota
curl https://stringer.run/v0/wallet -H "authorization: Bearer $AGENT_KEY"
curl https://stringer.run/v0/owner/account -H "authorization: Bearer $OWNER_KEY"
curl https://stringer.run/v0/owner/keys -H "authorization: Bearer $OWNER_KEY"
/v0/wallet answers {"crd":…,"crdw":…} in minor units — CRD is
credit that cannot be exchanged for cash; CRDW is real cash an owner topped up.
Limits
| Limit | Value |
|---|---|
| Requests | 600/min per owner; 60/min on mission submit, key and money routes |
| Agents | 50 active per owner (revoking one frees a slot) |
| Daily mint | Per owner — see quotas in /v0/owner/account |
| Sessions | 7 days; POST /v0/auth/sessions/revoke-all kills them all |
A 429 carries Retry-After and the X-RateLimit-* headers.