Get started with GetRatchet

GetRatchet records agent tool execution and lets a separate worker resume durable work after a process stops. Your application still runs the agent and owns the external tools. Start with a workspace and a scoped API key; the console and API reference are available without access to the source repository.

1. Create a workspace and key

Create an account and verify its email.
Open Settings to choose a project and environment. A new account starts with a default project and development, staging, and production environments.
Create an INGEST key scoped to the project and environment. Copy the secret when it is shown, then store it on your server. It is not shown again. Add a separate READ key if your service needs to query runs.

Never put an API key in browser JavaScript, a mobile bundle, a public repository, or a URL. SDK and worker requests send Authorization: Bearer <key> over HTTPS.

2. Send a run

From a server process, create a run with your INGEST key:

curl https://getratchet.app/api/v1/runs \
  -H "Authorization: Bearer $GETRATCHET_INGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customer onboarding"}'

The response contains a run.id. The project and environment come from your scoped key when omitted from the request. Open Runs to inspect it. A READ key can list runs with GET /api/v1/runs; see the API reference for request and response details.

3. Choose an execution mode

Record a local call: The TypeScript SDK wrap() helper records attempts around a function in your own process. If that process dies, GetRatchet cannot restart its closure.
Recover after a crash: Persist a named, versioned call with enqueue(), then run a separate long-lived durable worker that registers that exact name and version. A worker key needs the WORKER scope and an allowlist for the handlers it registers.

Durable jobs may run more than once after a worker crash. Pass a stable idempotency key to the destination service for payments, email, writes, and other external effects.

Where to go next

Read the TypeScript SDK or Python SDK examples, the worker guide, and the API reference. The observability guide explains metrics and traces. For account or key help, contact GetRatchet support.

Continue with the current references

Install the published TypeScript package with npm install @getratchet/sdk, or Python with pip install getratchet. See the TypeScript reference, Python reference, custom policies and error classification, and customer worker deployment. The CLI reference documents its separate build and installation status.

Before adding retries to side-effecting operations, implement destination-side idempotency. Execution is at least once.

See your first recovery

The onboarding quickstart now deliberately fails the first getratchet_echo@1 attempt and returns its harmless input on the next attempt. Choose TypeScript or Python, prepare the scoped 24-hour keys, then run the generated example in Default/development. No external side effect is performed. The setup page detects an online worker for the exact handler version and checks for a successful durable job with a recorded failed attempt; a merely queued job does not complete recovery setup.

The default retry normally becomes eligible after 24–36 seconds. The Node example stays online for 90 seconds. Existing endpoint gates or policies may extend the wait; inspect the run before stopping or restarting the worker. These are two normal durable attempts, not a one-attempt synthetic test. Revoke the setup keys afterward. An existing single-attempt success still completes the integration checklist, but does not count as proof of retry recovery.

On a run's step panel, the observed-state explanation distinguishes parent dependencies, paused endpoints, circuit cooldown/probes, future due dates, missing recent compatible workers, concurrency and rate limits. It is a snapshot, not a promise of immediate execution; refresh to observe changes. For a practical next operation, follow the webhook recovery recipe.