Quickstart#
This walkthrough creates an agent key and completes a full loop: read the register, create an obligation, file proof, then connect something that can act on it.
Before you start#
- A workspace. Sign up at remindify-xi.vercel.app/signup, or run Remindify locally.
- Node.js 22 or newer only if you run Remindify locally.
- About ten minutes.
1. Pick a base URL#
| Where | Base URL | Setup |
|---|---|---|
| Hosted preview | https://remindify-xi.vercel.app |
Sign up in the browser; nothing to install |
| Local | http://localhost:4178 |
npm install && npm run dev |
The hosted preview is a real deployment, not a mock: accounts, machine keys and the REST API work over HTTPS. Two conveniences are switched off there because it has no OAuth client or email webhook — Google sign-in and password reset. Use email and password, keep the password safe, and treat the workspace as demo data. Environment variables lists what a full deployment configures.
export REMINDIFY_URL=https://remindify-xi.vercel.app
# or: export REMINDIFY_URL=http://localhost:4178Run locally instead#
npm install
npm run devVite serves the app on http://localhost:5173 and proxies /api to the server on 4178. To serve the built app from one port:
npm run build
npm start2. Create an agent#
Open Agents and choose Create agent. Give it a focus, a role and an autonomy ceiling:
| Ceiling | What the agent may do |
|---|---|
notify |
Suggest work; never act |
prepare |
Draft a plan and checklist |
approve |
Act only after a human approval |
autopilot |
Act automatically, within its scopes and connector |
The ceiling caps the obligation's own autonomy. An agent with a prepare ceiling cannot execute an autopilot obligation.
3. Issue a machine key#
Open Agent access, choose Create key, and copy the secret immediately. It is shown once.
The four scopes are:
| Scope | What it allows |
|---|---|
obligations:read |
List and read obligations |
obligations:write |
Create obligations, complete them, file receipts |
risk:read |
Portfolio risk and trust snapshots |
agents:read |
Read the agent roster |
New keys default to all four if you omit scopes:
curl -X POST "$REMINDIFY_URL/api/keys" \
-H "content-type: application/json" \
-H "cookie: remindify_session=..." \
-d '{"name":"registrar","scopes":["obligations:read","obligations:write"],"expires_in_days":90}'The response contains key.secret exactly once.
4. Read the register#
export REMINDIFY_KEY=rfy_live_...
curl "$REMINDIFY_URL/api/v1/obligations" \
-H "Authorization: Bearer $REMINDIFY_KEY"Response:
{
"count": 12,
"clock": "2026-10-28T09:00:00.000Z",
"obligations": [
{
"id": "ob_rent",
"title": "Pay rent",
"category": "finance",
"provider": "Selam Properties",
"amount": 750,
"currency": "USD",
"due_at": "2026-11-01T09:00:00.000Z",
"autonomy": "autopilot",
"proof_required": "Landlord receipt + transfer reference",
"status": "active",
"risk": { "score": 62, "band": "high", "days": 4, "urgency": 1.18 }
}
]
}5. Create an obligation#
title is required. due_at defaults to 14 days from now if omitted.
curl -X POST "$REMINDIFY_URL/api/v1/obligations" \
-H "Authorization: Bearer $REMINDIFY_KEY" \
-H "content-type: application/json" \
-H "Idempotency-Key: create-domain-renewal-2026-10" \
-d '{
"title": "Renew the studio domain",
"category": "work",
"provider": "Cloudflare",
"amount": 24,
"currency": "USD",
"due_at": "2026-11-15T10:00:00.000Z",
"autonomy": "approve",
"severity": 4,
"proof_required": "Registrar confirmation email",
"recurrence": { "unit": "year", "interval": 1 }
}'The response is 201 with { "obligation": { ... } }.
If the request times out, retry with the same Idempotency-Key and body. The original response is replayed for 24 hours; reusing the key with a different body returns 409 idempotency_conflict.
6. Complete it with proof#
curl -X POST "$REMINDIFY_URL/api/v1/obligations/ob_.../complete" \
-H "Authorization: Bearer $REMINDIFY_KEY" \
-H "content-type: application/json" \
-H "Idempotency-Key: complete-domain-2026-10" \
-d '{
"proof": "Cloudflare order CF-88213 · renewed to 2027-11-15",
"note": "Auto-renew was off; paid by card ending 4412."
}'A successful completion:
- advances a recurring obligation to its next due date, or archives a one-off;
- files a proof receipt in the trust layer, signed server-side with HMAC-SHA256;
- records an attributed
proofevent.
The response includes next_due for recurring obligations, or archived: true for one-off ones.
To check the evidence, run the auditor on the receipt with POST /api/trust/receipts/:id/audit. It returns verified, confidence, a verdict and any discrepancies. GET /api/trust/receipts/:id/verify returns the receipt status, whether its signature is valid, the proof_hash and any settlement. A rejected receipt leaves any PayPal escrow hold untouched; see Proof and escrow.
7. Let the agent act#
The REST API records what an agent did. To let it do the work, connect an execution connector in the agent's passport:
- Run an HTTPS endpoint you control.
- Paste the URL in the passport and copy the signing secret once.
- On approve or autopilot, Remindify sends a signed
POSTwith the obligation, action and run id. - Return
2xxwith{"proof": "..."}to file evidence.
Read the full contract in Execution connectors. Without a connector, the agent is draft-only: it can plan and request approval, but nothing executes.
8. Or use MCP#
If your client is Claude Desktop, Cursor or another MCP host, skip the HTTP client:
{
"mcpServers": {
"remindify": {
"command": "node",
"args": ["/absolute/path/to/remindify/mcp/server.mjs"],
"env": {
"REMINDIFY_URL": "http://localhost:4178",
"REMINDIFY_KEY": "rfy_live_..."
}
}
}
}The MCP server is a local stdio process in this repository, so the args path is always local. Set REMINDIFY_URL to the hosted base URL to drive the hosted workspace, or to http://localhost:4178 for a local one.
Tools: list_obligations, get_obligation, create_obligation, complete_obligation, portfolio_risk, list_agents, list_trust.
Next steps#
- Obligations for the full field and risk model.
- Agent tools and models for framework recipes.
- Errors before you ship a retry loop.
- Keep keys server-side. Never ship a machine key in a browser bundle or a public repository.