Tell your agent what the journey should do. It can inspect templates and workflows, create the graph, and simulate each path before you publish.
Quick Start
Prerequisites
- Node.js 22 or newer
- pnpm 11+ and Docker Compose (local server only)
1. Install the CLI
npm install --global @socialrobot-io/rachet
rachet --version
The CLI connects to a Rachet server; it does not install the server.
2. Sign in
Open rachet.dev/login, or use the CLI:
rachet auth login
rachet call auth.whoami
The CLI uses https://rachet.dev by default. For your own server, pass --url https://your-domain to rachet auth login. It stores short-lived access and rotating refresh credentials in a protected local file, never your password or browser cookie.
3. Connect an MCP client
Copy the checked-in examples/mcp/cursor.json to .cursor/mcp.json:
{
"mcpServers": {
"rachet": {
"url": "https://rachet.dev/mcp"
}
}
}
For your own server, replace https://rachet.dev with its URL. Do not add a static Authorization header. Rachet publishes OAuth discovery metadata; compatible clients register with PKCE, show the requested scopes, and save their own grant. Operators can revoke the grant from Connected apps. Redirect allowlists are described in Authentication.
The dashboard's Connect your tools section also has setup instructions for Claude Code, ChatGPT, VS Code, Windsurf, Zed, and other remote HTTP MCP clients. Cursor and VS Code have direct install buttons. Step 4 offers a short, copyable welcome journey prompt. Public clients may need their exact OAuth callback origin or scheme added to the deployment allowlist.
Run locally
git clone https://github.com/socialrobot-io/rachet.git
cd rachet
pnpm install
pnpm dev
pnpm dev starts PostgreSQL, Temporal, the API, worker, dispatcher, and dashboard. Open the dashboard URL printed by the launcher. For sign-in, configure either AUTH_RESEND_API_KEY with AUTH_EMAIL_FROM, or GITHUB_CLIENT_ID with GITHUB_CLIENT_SECRET in .env.local. On a fresh database, use the generated RACHET_SETUP_SECRET to create the first administrator. Registration is disabled by default; set ALLOW_REGISTRATION=true in .env.local and restart to test new accounts.
After signing in, connect workflow delivery in Integrations → Email → Resend. Open Enrollments to see people in progress, exits, and the reason a journey ended. To preview sample journeys, run pnpm demo:seed --list and then pnpm demo:seed <workspace-slug>. See Local demo journeys for details. Stop the app with Ctrl+C and its Docker services with pnpm dev:infra:down.
Usage
Create the first journey with MCP
Give your MCP-capable agent this prompt:
Welcome new users with one friendly email, then end the journey.
Rachet's MCP skill guides the agent through discovery, authoring, validation, and simulation. The agent must ask before publishing or enrolling a real contact. For a more involved example with a reminder and activation event, follow the welcome + nudge tutorial.
Send product events
Define the type once for the workspace. Its JSON Schema is immutable; use a new versioned name when the payload changes.
rachet call event_type.define --input '{
"eventType": "product.activated.v1",
"schema": {
"type": "object",
"required": ["plan"],
"properties": { "plan": { "type": "string" } },
"additionalProperties": false
}
}'
rachet call event.emit --input '{
"enrollmentId": "ENROLLMENT_ID",
"eventId": "product-activation:ACTIVITY_ID",
"eventType": "product.activated.v1",
"data": { "plan": "pro" }
}'
Keep eventId stable across retries. Production applications call the same event.emit operation over HTTP with a scoped machine credential, and MCP clients use event_emit. Complete CLI, HTTP, and MCP examples are in Sending product events.
When RACHET_API_KEY and RACHET_WORKSPACE_ID are set, Rachet uses @socialrobot-io/rachet-sdk to enroll each new account in the published workflow named Welcome first workflow, and emits workflow.created.v1 when that person creates a workflow.
Trigger a journey from product code
import { RachetSdk } from '@socialrobot-io/rachet-sdk';
const rachet = new RachetSdk({
url: process.env.RACHET_URL,
workspaceId: process.env.RACHET_WORKSPACE_ID,
apiKey: process.env.RACHET_API_KEY, // user-bound key with the send scope
});
await rachet.trigger({
workflowVersionId: 'WORKFLOW_VERSION_ID',
contact: { email: '[email protected]' },
idempotencyKey: 'activation-welcome:[email protected]',
});
The SDK upserts the contact and starts an idempotent enrollment. Contact fields merge with the fields already stored: a key you send replaces that key, null removes it, and keys you leave out are kept. Keep the API key server-side; browser bundles must call your own backend endpoint.
Operate Rachet
rachet workflow show --name "Activation welcome"
rachet call enrollment.list
rachet call message.list
For marketing email, an organization owner or admin sets the marketing sender and unsubscribe details while configuring Integrations → Email → Resend, or with email_policy.update. Record the recipient's new consent on enrollment.create with consent, or with contact.resubscribe and a stable event ID before enrollment. Published marketing sends include an unsubscribe footer and mailbox one-click headers. subscription_event.list shows which email and workflow led to a link opt-out. See Unsubscribe and consent.
The operations console at rachet.dev shows journey graphs, live enrollments, timelines, messages, OAuth consent, and connected apps. Deployment administrators also get a Users page at /admin/users.
Workflow cards show the number of published versions. Open a workflow and use Version to view v1, v2, or a draft. The graph and enrollment counts match the selected version. Enrollment rows show each person's pinned version and link to that graph. Expand IDs for API and support when you need a workflow or version ID.
The public landing page is at / and /welcome. Signed-in users go to /workflows. Run pnpm dev:dashboard to work on the landing page. Sign-in and the operations console need the full development stack.
Architecture
See Architecture for the full design.
Configuration
Server variables, documented in .env.example:
CLI and SDK environments use RACHET_URL plus RACHET_TOKEN or RACHET_API_KEY; the SDK also reads RACHET_WORKSPACE_ID.
Validation and simulation work without Resend. Before a real enrollment can send email, connect the organization's Resend account in the dashboard and confirm a test send. Domain verification and webhook setup are covered in Resend setup.
API
Every operation is defined once and exposed three ways: HTTP POST /v1/operations/<operation>, an MCP tool with dots converted to underscores, and the generic rachet call CLI command.
MCP also serves rachet://operations, rachet://workflow/schema, and rachet://workflow/actions, plus the design-workflow authoring prompt and the first-party agent skill. The full contract is in Operations and MCP contract.
Project Structure
apps/
├── dashboard/ # React operations console and OAuth UI
└── server/ # Hono API, Better Auth, Temporal workers, Resend adapter
packages/
├── contracts/ # Shared operation and journey schemas
├── cli/ # @socialrobot-io/rachet CLI
├── sdk/ # @socialrobot-io/rachet-sdk for server actions and UI backends
└── mcp-ext-skills/ # MCP skills extension shim
docs/ # Architecture, authentication, deployment, operations, events guides
examples/ # welcome-nudge tutorial and MCP client configs
migrations/ # PostgreSQL migrations
scripts/ # Dev orchestration, deployment, workflow bundling
skills/ # First-party agent skill
tests/ # Repository validation suite
Tech Stack
Deployment
Before enabling public signups, review the production readiness assessment.
Point a hostname at a Linux server with Docker and ports 80/443 available, then run:
./scripts/deploy.sh rachet.example.com [email protected]
The script generates deployment secrets, builds the stack, configures Caddy TLS, runs migrations, and performs idempotent admin setup. See Deployment for Coolify, external ingress, backups, and production topology.
CI runs the same make check gate on every push and pull request.
Contributing
Contributions follow the standard fork, branch, commit, pull request workflow. Before opening a PR, run the complete release gate:
make check
It runs validation, linting, typechecks, tests, replay checks, builds, Compose validation, and an npm package dry run. Read CONTRIBUTING.md and follow the writing guide. Update the docs and agent skill when behavior changes. The CLI release process is in Releasing.
Rachet is early. Open an issue with setup problems or missing journey actions.
For project updates, follow @ntorresdev on X.
License
Rachet is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).
