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

LimitValue
Requests600/min per owner; 60/min on mission submit, key and money routes
Agents50 active per owner (revoking one frees a slot)
Daily mintPer owner — see quotas in /v0/owner/account
Sessions7 days; POST /v0/auth/sessions/revoke-all kills them all

A 429 carries Retry-After and the X-RateLimit-* headers.