# Resonate Documentation — Full Content

---
url: https://docs.resonatehq.io/debug/errors
title: Errors
---

This page documents known errors that may be encountered when using Resonate and how to troubleshoot them.

If you believe your issue is not covered here, reach out in [Discord](https://resonatehq.io/discord) to discuss.

Known errors will likely have an error code associated with them and a short error message.

Troubleshooting steps are categorized by error code ranges:

- [Server request errors (HTTP 4XX)](#server-request-errors)
- [Server errors (HTTP 5XX)](#server-errors)
- [Python SDK errors (100.x, 200, 201, 300)](#python-sdk-errors)
- [TypeScript SDK errors (1100-1199)](#typescript-sdk-errors)

## Server request errors

These are the errors you may encounter when making requests to Resonate Server v0.9.8.
Request errors signify problems with the request itself — retrying the same request will not resolve the issue.

**Range: HTTP 4XX**

**Error response shape**

Every response from the server (success or error) carries this envelope. On error, `head.status` is the HTTP status code and `data` is the human-readable message.

```json
{
  "kind": "promises.get",
  "head": {
    "corrId": "<correlation id from the request>",
    "status": 404,
    "version": "2026-04-01"
  },
  "data": "Promise not found"
}
```

If the problem persists, open a [GitHub issue](https://github.com/resonatehq/resonate/issues/new) with details, including the response envelope and steps to reproduce.
Or reach out via [Discord](https://resonatehq.io/discord) for support.

### 400 — Bad Request

The request is malformed. Common causes:

- Invalid JSON body or missing required fields
- Validation failure (`data` carries the failed field and reason)
- Unrecognized operation kind
- Invalid `resonate:target` address
- Invalid listener address
- `limit` outside the allowed range (1–1000)

### 401 — Unauthorized

The request did not carry a valid bearer token, or the token failed JWT verification.

### 403 — Forbidden

The request carried a valid token, but the principal is not permitted to perform the requested action.

### 404 — Not Found

The requested resource does not exist. Common cases: promise not found, schedule not found, task not found, awaited promise not found.

### 409 — Conflict

The request would violate an existing resource's lifecycle invariants. Common cases:

- Promise already resolved, rejected, canceled, or timed out (cannot be modified again)
- Schedule with the requested id already exists
- Promise with the requested id already exists
- Lock already acquired
- Task already claimed or completed
- Task claimed with the wrong counter

### 422 — Unprocessable Entity

The request was syntactically valid but semantically unprocessable. Common cases:

- Awaiter promise not found or has no `resonate:target` tag
- Task in invalid state for the requested transition

## Server errors

**Range: HTTP 5XX**

Server errors represent transient or systemic problems that prevent the request from being processed.
Retrying the request may resolve the issue.

If the problem persists, open a [GitHub issue](https://github.com/resonatehq/resonate/issues/new) with details, including the response envelope and steps to reproduce.
Or reach out via [Discord](https://resonatehq.io/discord) for support.

### 500 — Internal Server Error

An unexpected server-side failure. Includes failures in the persistence layer (e.g. unrecoverable database lock contention), the scheduler, or any unhandled internal error path. The `data` field carries the failure description; the server logs carry the underlying cause.

## Python SDK errors

These are the exception classes raised by the Python SDK (`resonate-sdk` v0.6.7).
Each exception has a numeric `code` attribute. Codes are not contiguous integers — they fall into a few ranges keyed off the underlying failure domain.

If the problem persists, open a [GitHub issue](https://github.com/resonatehq/resonate-sdk-py/issues/new) with details, including the error code and steps to reproduce.
Or reach out via [Discord](https://resonatehq.io/discord) for support.

### `ResonateStoreError` (codes `100.x`)

Raised when a store operation against the Resonate Server (or the in-process local store) fails. The fractional part embeds a structured sub-code from the **legacy Resonate Server** (which Python SDK v0.6.7 targets — see the legacy-server callout on the [Python SDK guide](/develop/python)). Common sub-codes:

- `100.40400` — promise/schedule not found
- `100.40303` — promise already timed out
- `100.40305` — task already claimed
- `100.40403` — task not found
- `100.40399` — state-machine transition error
- `100.0` — transport-level failure (request timed out, failed to connect, unknown exception)

The current Rust server (v0.9.8) does not emit these structured sub-codes — it returns standard HTTP status codes (see [Server request errors](#server-request-errors) above). When the Python SDK adds Rust-server compatibility, this section will be updated.

### `ResonateCanceledError` (code `200`)

Raised when a promise is canceled. The `promise_id` attribute identifies the canceled promise.

### `ResonateTimedoutError` (code `201`)

Raised when a promise times out before it is resolved or rejected. Carries `promise_id` and `timeout` attributes.

### `ResonateShutdownError` (code `300`)

Raised when the Resonate client is shutting down and an in-flight operation cannot proceed.

## TypeScript SDK errors

**Range: 1100 - 1199**

These are known errors you may encounter when using the TypeScript SDK.

If the problem persists, open a [GitHub issue](https://github.com/resonatehq/resonate-sdk-ts/issues/new) with details, including the error code and steps to reproduce.
Or reach out via [Discord](https://resonatehq.io/discord) for support.

### 1100

**REGISTRY_VERSION_INVALID**

Function version must be greater than zero (x provided)

### 1101

**REGISTRY_NAME_REQUIRED**

Function name is required

### 1102

**REGISTRY_FUNCTION_ALREADY_REGISTERED**

Function 'x' (version y) is already registered [under 'u']

### 1103

**REGISTRY_FUNCTION_NOT_REGISTERED**

Function 'x' (version y) is not registered. Will drop.

### 1104

**DEPENDENCY_ALREADY_REGISTERED**

Dependency 'x' is already registered

### 1105

**DEPENDENCY_NOT_REGISTERED**

Dependency 'x' is not registered. Will drop.

### 1106

**ENCODING_ARGS_UNENCODEABLE**

Function arguments cannot be encoded.

### 1107

**ENCODING_ARGS_UNDECODEABLE**

Function arguments cannot be decoded.

### 1108

**ENCODING_RETV_UNENCODEABLE**

The return value from a function cannot be encoded.

### 1109

**ENCODING_RETV_UNDECODEABLE**

The return value from a function cannot be decoded.

### 1198

**PANIC**

An unrecoverable internal error occurred in the SDK.

### 1199

**SERVER_ERROR**

An error occurred on the server. Please check for additional error codes for more details.

---

---
url: https://docs.resonatehq.io/debug
title: Debug a Resonate application
---

<img src="/images/banner-debug-dark.png" alt="Debug Resonate applications section" className="hidden dark:block" />
<img src="/images/banner-debug-light.png" alt="Debug Resonate applications section" className="block dark:hidden" />

Something's not working. This section helps you figure out why and fix it.

## When things go wrong

Debugging distributed systems is hard. Resonate's durable execution model helps by preserving execution state across failures, but you still need to know where to look when something breaks.

**Start here:**

1. **Check the logs** - Server and SDK logs show what's happening at each step
2. **Look for error codes** - Resonate returns structured errors with codes you can search
3. **Use the troubleshooting guide** - Common problems and solutions

## What you'll find here

### [Errors](/debug/errors)

Resonate's error codes and what they mean. When you see an error, look it up here to understand what went wrong and how to fix it.

### [Troubleshooting](/debug/troubleshooting)

Common problems and their solutions. Start here if you're seeing unexpected behavior but not sure what's causing it.

## Debug workflow

**When something fails:**

1. **Reproduce it** - Can you make it happen again? Consistent failures are easier to debug
2. **Check the logs** - Server logs (see [Logging](/deploy/logging)) show internal state changes
3. **Look up the error** - Find the error code in the [Errors](/debug/errors) reference
4. **Check common issues** - See if your problem matches something in [Troubleshooting](/debug/troubleshooting)
5. **Ask for help** - If you're stuck, share logs + error codes in [Discord](https://discord.gg/R4ad7T4U)

## What debugging looks like

**Durable execution changes debugging:**

In traditional systems, when a function fails, its execution state is lost. You see an error but can't inspect where it failed or what it was doing.

With Resonate, execution state is preserved in durable promises. When something fails:

- The promise shows the last successful checkpoint
- You can inspect input/output of each step
- You can retry from the failure point (not from scratch)
- Logs show the full execution history

This makes debugging **incremental** rather than blind.

## Beyond this section

- **Deployment issues** → See [Deploy](/deploy) for server startup, configuration, and infrastructure problems
- **Performance tuning** → See [Scaling](/deploy/scaling) for capacity and throughput optimization
- **Observability setup** → See [Logging](/deploy/logging), [Metrics](/deploy/metrics), and [Tracing](/deploy/tracing) to instrument your system

This section is about **fixing what's broken**. The other sections are about **building what works**.

---

---
url: https://docs.resonatehq.io/debug/troubleshooting
title: Troubleshooting
---

This guide covers common issues you might encounter when using Resonate and how to resolve them.

If your problem isn't listed here, check the [Errors](/debug/errors) reference for error codes or ask in [Discord](https://discord.gg/R4ad7T4U).

## Server won't start

### Database connection failures

**Symptoms:**
- Server fails to start with connection errors
- Logs show `failed to connect to database` or similar

**Causes:**
- PostgreSQL not running
- Wrong connection credentials
- Network/firewall blocking connection
- Database doesn't exist

**Solutions:**

1. **Check PostgreSQL is running:**
```bash
# PostgreSQL status
pg_isready -h localhost -p 5432

# For managed services, check cloud console
```

2. **Verify connection string:**
```toml title="resonate.toml"
[storage]
type = "postgres"

[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
```

Or set `RESONATE_STORAGE__POSTGRES__URL` in the environment. Check the host, port, database, user, and password all match what your Postgres instance expects.

3. **Create database if missing:**
```bash
psql -h localhost -U postgres -c "CREATE DATABASE resonate;"
```

4. **Check firewall/security groups:**
- Ensure server can reach database on port 5432
- Check cloud security group rules
- Verify VPC/network configuration

### Port already in use

**Symptoms:**
- Server fails to start
- Logs show `address already in use` or `bind: address already in use`

**Cause:**
Another process is using port 8001 (HTTP).

**Solutions:**

1. **Find what's using the port:**
```bash
# macOS/Linux
lsof -i :8001

# Kill the process if needed
kill -9 <PID>
```

2. **Use a different port:**
Pass `--server-port` to `resonate serve` to bind a different port:
```bash
resonate serve --server-port 8003
```

### Configuration file errors

**Symptoms:**
- Server fails to start
- Logs show a TOML parse error from `figment` or an unknown field name

**Cause:**
Invalid TOML syntax in `resonate.toml`, or a field name that doesn't match the schema.

**Solutions:**

1. **Validate TOML syntax** with any TOML linter, or paste it into [toml-lint.com](https://www.toml-lint.com/).

2. **Check section and field names** against [Run a server](/deploy/run-server#configuration). Sections are nested with dots: `[storage.postgres]`, not `[storage_postgres]`.

3. **Check env var nesting.** Environment variables use the `RESONATE_` prefix and `__` (double underscore) for nesting:
```bash
# WRONG — single underscore
RESONATE_STORAGE_POSTGRES_URL=...

# RIGHT — double underscore between sections
RESONATE_STORAGE__POSTGRES__URL=...
```

## Workers not receiving tasks

### Workers not connecting

**Symptoms:**
- Workers start but never process tasks
- No worker registration in server logs
- Tasks remain pending indefinitely

**Causes:**
- Wrong server URL
- Network/firewall blocking connection
- Server not running
- Authentication misconfigured

**Solutions:**

1. **Verify server URL:**
```typescript
const resonate = new Resonate({
  url: "http://resonate-server:8001",  // Must match server address
  group: "workers",
});
```

2. **Test connectivity:**
```bash
# From worker machine, test server reachability
curl -s -o /dev/null -w "%{http_code}\n" http://resonate-server:8001/health

# Should return 200 when the server is alive
```

3. **Check authentication:**
If server has auth enabled, workers must provide credentials:

```typescript
const resonate = new Resonate({
  url: "http://resonate-server:8001",
  group: "workers",
  token: "your-jwt-token",
});
```

4. **Check server logs:**
```bash
# Look for worker registration messages
resonate serve --level debug

# Should see: "worker registered" or similar
```

### Tasks not reaching workers

**Symptoms:**
- Workers connected but not processing tasks
- Tasks created but remain pending
- No task distribution happening

**Causes:**
- Wrong worker group name
- Worker polling misconfigured
- Task routing rules don't match workers

**Solutions:**

1. **Verify group names match:**
```typescript
// When registering worker:
const resonate = new Resonate({
  group: "workers",  // Note the group name
});

// When creating task:
resonate.rpc(
  taskId,
  "processOrder",
  data,
  resonate.options({
    target: "poll://any@workers",  // Must match worker group
  })
);
```

2. **Check worker is polling:**
Workers must actively poll for tasks. Ensure your worker code calls functions that poll:

```typescript
// Worker polls when you register functions
resonate.register("processOrder", async (ctx, data) => {
  // Task execution
});

// Worker polls automatically after registration
```

3. **Inspect promise state:**
```bash
# Query promises to see if tasks are being created
curl http://localhost:8001/promises?state=pending

# Check if tasks exist for those promises
curl http://localhost:8001/tasks?state=pending
```

## Promises not resolving

### Promise stuck in pending state

**Symptoms:**
- Promise created but never completes
- No worker picks up the task
- `resonate.promises.get()` shows `state: "pending"` indefinitely

**Causes:**
- No workers available for the task's group
- Worker crashed mid-execution and task not reassigned
- Task timeout not configured (waits forever)
- Routing misconfiguration

**Solutions:**

1. **Confirm workers are running:**
```bash
# Check worker processes
ps aux | grep worker

# In Kubernetes:
kubectl get pods -l app=resonate-worker
```

2. **Check promise/task state:**
```bash
# Get promise details
curl http://localhost:8001/promises/{promiseId}

# Check if task exists
curl http://localhost:8001/tasks?promiseId={promiseId}
```

3. **Set task timeouts:**
```typescript
resonate.rpc(
  taskId,
  "processOrder",
  data,
  resonate.options({
    target: "poll://any@workers",
    timeout: 60000,  // 60 second timeout
  })
);
```

4. **Check worker heartbeats:**
If worker crashed, server should detect via heartbeat timeout (default: 60s) and reassign. Check server logs for heartbeat failures.

### Promise failed but retry not working

**Symptoms:**
- Promise fails once and doesn't retry
- Expected automatic retry but it didn't happen

**Cause:**
Resonate doesn't automatically retry failed promises unless you configure retry logic.

**Solutions:**

1. **Implement retry logic explicitly:**
```typescript
async function processOrderWithRetry(ctx, data) {
  let attempts = 0;
  const maxAttempts = 3;

  while (attempts < maxAttempts) {
    try {
      const result = await ctx.run(() => processOrder(data));
      return result;
    } catch (error) {
      attempts++;
      if (attempts >= maxAttempts) throw error;
      await ctx.sleep(1000 * attempts);  // Exponential backoff
    }
  }
}
```

2. **Check error type:**
Some errors shouldn't retry (e.g., invalid input). Handle appropriately:

```typescript
catch (error) {
  if (error.code === "INVALID_INPUT") {
    throw error;  // Don't retry
  }
  // Retry for transient errors
}
```

## Performance issues

### Slow task execution

**Symptoms:**
- Tasks complete but take longer than expected
- High latency between task creation and completion

**Causes:**
- Not enough workers (tasks queue up)
- Worker resource constraints (CPU/memory)
- Database performance issues
- Network latency

**Solutions:**

1. **Scale workers horizontally:**
```bash
# Docker Compose
docker-compose up -d --scale worker=10

# Kubernetes
kubectl scale deployment resonate-workers --replicas=20
```

See [Scaling](/deploy/scaling) for details.

2. **Monitor worker resources:**
```bash
# Check CPU/memory usage
top
htop

# Kubernetes:
kubectl top pods -l app=resonate-worker
```

3. **Optimize database:**
- Add indexes for frequently queried promise/task fields
- Increase PostgreSQL connection pool size
- Use managed PostgreSQL with IOPS scaling

4. **Check network latency:**
```bash
# Measure round-trip time to server
ping resonate-server

# Test HTTP latency
time curl -s http://resonate-server:8001/health
```

### High database load

**Symptoms:**
- Slow promise creation/resolution
- Database CPU/IOPS maxed out
- Connection pool exhausted

**Causes:**
- Too many concurrent promises
- Inefficient queries (missing indexes)
- Insufficient database resources

**Solutions:**

1. **Upgrade database resources:**
- Increase CPU/RAM
- Add IOPS capacity (for cloud databases)
- Use managed PostgreSQL with auto-scaling

2. **Tune connection pool:**
```toml title="resonate.toml"
[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
pool_size = 50  # Increase pool size (default: 10)
```

3. **Add database indexes:**
Check PostgreSQL slow query log and add indexes for common queries.

4. **Batch operations:**
If creating many promises, batch them when possible to reduce database round-trips.

## Authentication issues

### Unauthorized errors

**Symptoms:**
- Workers can't connect
- API requests return `401 Unauthorized`
- Logs show authentication failures

**Causes:**
- Wrong credentials
- Auth enabled on server but not configured in client
- Token expired (JWT)

**Solutions:**

1. **Verify credentials:**
```typescript
const resonate = new Resonate({
  url: "http://resonate-server:8001",
  token: "your-jwt-token",  // Check this matches server config
});
```

2. **Check server auth config:**

The server uses JWT bearer auth signed with an Ed25519 key. Start the server with the public key path:
```bash
resonate serve --auth-publickey /etc/resonate/auth/public.pem
```

Or in `resonate.toml`:
```toml
[auth]
publickey = "/etc/resonate/auth/public.pem"
```

In the SDK, pass a JWT signed by the matching private key:
```typescript
const resonate = new Resonate({
  url: "http://resonate-server:8001",
  token: process.env.RESONATE_TOKEN,
});
```

3. **For JWT tokens, verify:**
- Token hasn't expired
- Signature was produced with the private key matching the server's public key
- `iss` / `aud` claims match what the server expects (if configured)

See [Security](/deploy/security) for the full auth setup.

## Development workflow issues

### Changes not taking effect

**Symptoms:**
- Code changes don't appear when running
- Old behavior persists after updates

**Causes:**
- Using wrong binary (old version still running)
- Cache issues
- Docker image not rebuilt

**Solutions:**

1. **Verify process is new:**
```bash
# Kill old processes
pkill -f resonate

# Restart with fresh binary
resonate serve
```

2. **Rebuild Docker images:**
```bash
docker-compose build --no-cache
docker-compose up -d
```

3. **Clear SDK caches (if applicable):**
```bash
# Node.js
rm -rf node_modules && npm install

# Python
rm -rf __pycache__ && pip install -r requirements.txt
```

### SQLite "database is locked" errors

**Symptoms:**
- SQLite errors about locked database
- Concurrent access failures

**Cause:**
SQLite doesn't handle high concurrency well. Multiple processes/threads trying to write simultaneously.

**Solution:**
Use PostgreSQL for any deployment with concurrent writers:

```toml title="resonate.toml"
[storage]
type = "postgres"

[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
```

SQLite is best for development and single-tenant deployments where there is no concurrent write contention against the server.

## Getting more help

If these troubleshooting steps don't resolve your issue:

1. **Check error codes:** See [Errors](/debug/errors) for detailed error information
2. **Enable debug logging:**
```bash
resonate serve --level debug
```
3. **Collect diagnostics:**
   - Server logs
   - Worker logs
   - Promise/task state from API
   - Database connection status
   - Network connectivity tests

4. **Ask in Discord:** Share diagnostics in the [Resonate Discord](https://discord.gg/R4ad7T4U)
5. **File a bug:** If you've found a bug, [open an issue on GitHub](https://github.com/resonatehq/resonate/issues)

## Quick diagnostic checklist

When debugging, check these in order:

- [ ] Server running and reachable (`curl http://server:8001/health` returns `200`)
- [ ] Storage reachable (`curl http://server:8001/ready` returns `200`)
- [ ] Workers registered with server (check logs)
- [ ] Worker group names match task routing
- [ ] Authentication configured (if enabled)
- [ ] Network/firewall allows communication
- [ ] Adequate resources (CPU, memory, IOPS)
- [ ] No port conflicts
- [ ] `resonate.toml` syntax valid (and env-var nesting uses `__`)
- [ ] Using recent Resonate version

Most issues fall into one of these categories. Work through the checklist systematically.

---

---
url: https://docs.resonatehq.io/deploy/availability
title: Availability
---

Resonate's availability depends primarily on the availability of its persistent storage. Since all execution state is stored in the database, database availability directly determines system reliability.

## Architecture and availability

**The Resonate server coordinates work** but doesn't execute your functions. This separation means:

- Worker failures don't impact the server
- Worker restarts don't lose execution state
- Workers can be added/removed dynamically
- The database is the single source of truth for all execution state

A single Resonate server can coordinate thousands of workers and millions of promises because it's a coordination layer, not a computational bottleneck.

## Persistent storage

### PostgreSQL (recommended)

**Use PostgreSQL for production deployments** when you need:
- High availability and replication
- Multi-tenant deployments (multiple teams/projects sharing one server)
- High write throughput
- Standard HA patterns and tooling

### SQLite

**SQLite works for specific use cases:**
- Single-tenant micro deployments (one server per user/project)
- Embedded use cases where the server runs alongside your app
- Low-traffic production workloads
- Deployments where simplicity matters more than scale

Resonate's server and SDK are lightweight enough to support micro deployments. You can run isolated server instances with SQLite for specific users or projects.

For shared, multi-tenant deployments, PostgreSQL provides better concurrency and HA options.

### Configure PostgreSQL

```bash title="Start server with PostgreSQL"
resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate" \
  --storage-postgres-pool-size 20
```

For SSL connections, include `sslmode` in the connection string:

```bash
--storage-postgres-url "postgres://<USER>:<PASSWORD>@postgres.example.com:5432/resonate?sslmode=require"
```

## PostgreSQL high availability

Since the server stores all promise state in PostgreSQL, database availability directly impacts system reliability.

Use standard PostgreSQL HA patterns:

### Managed services (recommended)

Managed database services handle replication, failover, and backups automatically:

- **AWS RDS** with Multi-AZ deployment
- **Google Cloud SQL** with high availability configuration
- **Azure Database for PostgreSQL** with zone redundancy
- **Supabase** with automatic backups and replication

These services provide:
- Automatic failover (typically &lt;1 minute)
- Automated backups with point-in-time recovery
- Read replicas for scaling read traffic
- Monitoring and alerting built-in


Let your cloud provider handle database operations. They're better at it than you are, and their HA patterns are battle-tested.


### Self-managed replication

If you need to manage PostgreSQL yourself:

**Primary-replica setup:**
- Use Patroni or similar for automatic failover
- Configure streaming replication between primary and replicas
- Set up health checks and automatic promotion

**Point-in-time recovery (PITR):**
- Enable WAL (write-ahead logging) archiving
- Store WAL files in durable storage (S3, GCS, etc.)
- Test recovery procedures regularly

**Example backup strategy:**

```bash title="Automated PostgreSQL backups"
# Daily full backup
pg_dump -h postgres.example.com -U resonate resonate > backup-$(date +%Y%m%d).sql

# Continuous WAL archiving for PITR
# In postgresql.conf:
archive_mode = on
archive_command = 'cp %p /mnt/wal_archive/%f'
```

## Server monitoring

Monitor server health to detect issues before they impact availability:

### Health check

The server exposes two endpoints on the HTTP API port (`:8001`):

- `GET /health` — returns `200 OK` whenever the process is up. Use for liveness probes.
- `GET /ready` — returns `200 OK` when storage is reachable, `503` otherwise. Use for readiness probes.

```bash title="Check server health"
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/health
# 200
```

### Prometheus metrics

```bash title="Scrape metrics"
curl http://localhost:9090/metrics
```

**Key metrics to watch:**

```text
# Promise rate (workload indicator)
rate(promises_total[5m])

# Pending promises (backlog indicator)
promises_total{state="pending"}

# API request latency (performance indicator)
histogram_quantile(0.95, rate(api_duration_seconds_bucket[5m]))

# Server internal queue (capacity indicator)
sum(coroutines_in_flight)
```

See [Metrics](/deploy/metrics) for the full metrics catalog.

### Alerting

Set up alerts for critical conditions:

```yaml title="alerting-rules.yml"
groups:
  - name: resonate-availability
    rules:
      - alert: ResonateServerDown
        expr: up{job="resonate-server"} == 0
        for: 1m
        annotations:
          summary: "Resonate server is unreachable"

      - alert: HighAPIErrorRate
        expr: rate(api_requests_total{status=~"5.."}[5m]) > 10
        for: 5m
        annotations:
          summary: "High server error rate indicates availability issues"

      - alert: PromiseBacklogGrowing
        expr: increase(promises_total{state="pending"}[5m]) > 100
        for: 10m
        annotations:
          summary: "Promise backlog growing - may indicate processing issues"
```

## Server restart procedures

The Resonate server can be restarted safely without losing work:

1. **State preserved in PostgreSQL** - All promise state persists across restarts
2. **Workers handle disconnection** - Workers detect server disconnect and retry connections automatically
3. **Graceful shutdown** - Server responds to `SIGTERM` and attempts graceful cleanup (configurable timeout, default 10s)
4. **Workers resume** - When the server comes back online, workers reconnect and continue from checkpoints

### Restart the server

```bash title="Graceful server restart"
# Stop the server (sends SIGTERM for graceful shutdown)
kill -TERM $(pgrep resonate)

# Wait for shutdown (respects timeout config, default 10s)
sleep 12

# Start server again
resonate serve
```

See [Server configuration](/deploy/run-server#configuration) for the full configuration reference.

### Rolling updates

For zero-downtime updates, the current architecture requires:

1. Upgrade the database schema (if needed) in a backward-compatible way
2. Deploy the new server version
3. Restart the server (brief downtime: ~10s)
4. Workers reconnect automatically

**Multi-server deployments** (where multiple server instances share the same database) are not yet supported. The server-to-server coordination protocol is not implemented.

## When to upgrade server resources

The server's resource needs grow slowly compared to workers. Consider upgrading when you observe:

- **Database connections exhausted** - Increase connection pool size or upgrade server RAM
- **CPU sustained &gt;80%** - Rare, but indicates heavy coordination load
- **Network bandwidth saturated** - Large payloads moving between workers and server

For most deployments, a modest server (2-4 CPUs, 4-8GB RAM) can coordinate hundreds of workers processing thousands of tasks per second.

## What's not available yet

Some features you might expect in a high-availability guide aren't implemented today:

**Multi-server coordination** - Resonate doesn't support running multiple server instances that coordinate with each other. You run one server that coordinates many workers.

**Automatic server failover** - No built-in automatic failover between multiple server instances. Use PostgreSQL HA/replication for state persistence, and restart the server if it crashes.

**Cross-region disaster recovery** - For multi-region setups, use standard PostgreSQL replication patterns and manual failover procedures.

These features aren't implemented because **worker horizontal scaling** handles the vast majority of scale and availability needs. The server coordinates but doesn't execute work, so it's rarely a bottleneck or single point of failure (state lives in PostgreSQL).

If your use case exceeds single-server capacity, contact the Resonate team to discuss your requirements.

## Summary

**Availability in Resonate depends on:**
1. PostgreSQL availability (use managed HA services)
2. Server monitoring and alerting
3. Worker fault tolerance (automatic via heartbeats)

**The pattern:**
- Use managed PostgreSQL with HA configuration
- Monitor server health and database connections
- Scale workers horizontally for capacity
- Scale server vertically if coordination becomes a bottleneck

**Resonate's architecture makes availability simpler** because execution state lives in the database, not in-memory. Worker failures don't lose work, and server restarts are safe.

---

---
url: https://docs.resonatehq.io/deploy/deployment-patterns
title: Deployment patterns
---

Resonate works in any environment where you can run a server and workers. This guide covers common deployment patterns for different infrastructure choices.

## Development and staging

### Docker Compose

Use Docker Compose for local development and staging environments. This gives you a complete Resonate stack (server + database + workers) with one command:

```yaml title="docker-compose.yml"
version: "3.8"

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: resonate
      POSTGRES_USER: resonate
      POSTGRES_PASSWORD: secret
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U resonate"]
      interval: 10s
      timeout: 5s
      retries: 5

  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    ports:
      - "8001:8001"
      - "9090:9090"
    environment:
      RESONATE_SERVER__BIND: "0.0.0.0"
      RESONATE_STORAGE__TYPE: postgres
      RESONATE_STORAGE__POSTGRES__URL: postgres://<USER>:<PASSWORD>@postgres:5432/resonate
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:8001/health || exit 1"]
      interval: 5s
      retries: 10
      start_period: 30s

  worker:
    image: your-app:latest
    environment:
      RESONATE_URL: http://resonate-server:8001
    deploy:
      replicas: 3

volumes:
  postgres-data:
```

**Start the stack:**

```bash
docker-compose up -d
```

**Scale workers:**

```bash
docker-compose up -d --scale worker=10
```

This pattern works for:

- Local development
- CI/CD testing
- Staging environments
- Small production deployments

## Kubernetes

### Server deployment

The Resonate server runs as a single replica (multi-server coordination is not yet implemented). Use a Deployment with health checks:

```yaml title="server-deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
  name: resonate-server
spec:
  replicas: 1 # Single server coordinates all workers
  selector:
    matchLabels:
      app: resonate-server
  template:
    metadata:
      labels:
        app: resonate-server
    spec:
      containers:
        - name: server
          image: resonatehqio/resonate:v0.9.8
          ports:
            - containerPort: 8001
              name: http
            - containerPort: 9090
              name: metrics
          env:
            - name: RESONATE_SERVER__BIND
              value: "0.0.0.0"
            - name: RESONATE_STORAGE__TYPE
              value: "postgres"
            - name: RESONATE_STORAGE__POSTGRES__URL
              valueFrom:
                secretKeyRef:
                  name: postgres-credentials
                  key: url
          livenessProbe:
            httpGet:
              path: /health
              port: 8001
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8001
            initialDelaySeconds: 5
            periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
  name: resonate-server
spec:
  selector:
    app: resonate-server
  ports:
    - name: http
      port: 8001
      targetPort: 8001
    - name: metrics
      port: 9090
      targetPort: 9090
```

### Worker deployment

Workers scale horizontally. Use a Deployment with HorizontalPodAutoscaler:

```yaml title="worker-deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
  name: resonate-workers
spec:
  replicas: 10 # Initial worker count
  selector:
    matchLabels:
      app: resonate-worker
  template:
    metadata:
      labels:
        app: resonate-worker
    spec:
      containers:
        - name: worker
          image: your-app:latest
          env:
            - name: RESONATE_URL
              value: "http://resonate-server:8001"
            - name: WORKER_GROUP
              value: "workers"
          resources:
            requests:
              cpu: "500m"
              memory: "512Mi"
            limits:
              cpu: "1000m"
              memory: "1Gi"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: resonate-workers-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: resonate-workers
  minReplicas: 5
  maxReplicas: 50
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
```

The HPA automatically scales worker pods based on CPU utilization.

## Serverless platforms

### Google Cloud Run

Cloud Run workers can scale to zero and handle variable load automatically:

```dockerfile title="Dockerfile"
FROM node:22-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
CMD ["node", "worker.js"]
```

```bash title="Build and deploy"
# Build container
docker build -t gcr.io/your-project/resonate-worker:latest .

# Push to GCR
docker push gcr.io/your-project/resonate-worker:latest

# Deploy to Cloud Run
gcloud run deploy resonate-worker \
  --image gcr.io/your-project/resonate-worker:latest \
  --set-env-vars RESONATE_URL=https://resonate.example.com \
  --min-instances 1 \
  --max-instances 100 \
  --cpu 1 \
  --memory 512Mi \
  --region us-central1
```

Cloud Run workers stay alive polling for tasks and scale automatically based on load.

### AWS Lambda

Lambda workers can run as functions that poll for tasks or respond to events:

```typescript title="lambda-worker.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: process.env.RESONATE_URL!,
  group: "lambda-workers",
});

// Lambda handler polls for tasks
export async function handler(event: any) {
  // Poll and process tasks
  // Return when done or Lambda timeout approaches
}
```

**Deployment (using AWS CDK):**

```typescript title="worker-stack.ts"
import * as cdk from "aws-cdk-lib";
import * as lambda from "aws-cdk-lib/aws-lambda";

export class ResonateWorkerStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string) {
    super(scope, id);

    new lambda.Function(this, "ResonateWorker", {
      runtime: lambda.Runtime.NODEJS_22_X,
      handler: "lambda-worker.handler",
      code: lambda.Code.fromAsset("dist"),
      environment: {
        RESONATE_URL: "https://resonate.example.com",
      },
      timeout: cdk.Duration.minutes(15),
      memorySize: 512,
    });
  }
}
```


Lambda has a 15-minute execution limit. Cloud Run supports longer executions (up to 60 minutes). Design your functions to complete within these limits, or use containerized workers for long-running workflows.


### AWS Fargate

Fargate runs containers without managing servers, similar to Cloud Run:

```json title="task-definition.json"
{
  "family": "resonate-worker",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "containerDefinitions": [
    {
      "name": "worker",
      "image": "your-account.dkr.ecr.us-east-1.amazonaws.com/resonate-worker:latest",
      "environment": [
        {
          "name": "RESONATE_URL",
          "value": "https://resonate.example.com"
        }
      ],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/resonate-worker",
          "awslogs-region": "us-east-1",
          "awslogs-stream-prefix": "ecs"
        }
      }
    }
  ]
}
```

Create a Fargate service that runs the task definition, and Fargate handles scheduling and scaling.

## Bare metal / VMs

### Systemd service

Run Resonate server as a systemd service on bare metal or VMs:

```ini title="/etc/systemd/system/resonate.service"
[Unit]
Description=Resonate Server
After=network.target postgresql.service

[Service]
Type=simple
User=resonate
WorkingDirectory=/etc/resonate
ExecStart=/usr/local/bin/resonate serve
Restart=on-failure
RestartSec=10
# Configuration is loaded from /etc/resonate/resonate.toml (the working directory).
# Secrets can be injected as environment variables, e.g. RESONATE_STORAGE__POSTGRES__URL.

[Install]
WantedBy=multi-user.target
```

**Enable and start:**

```bash
sudo systemctl enable resonate
sudo systemctl start resonate
```

### Worker processes

Run workers as separate systemd services or use a process manager like PM2:

```bash title="PM2 worker management"
# Start 10 workers
pm2 start worker.js -i 10 --name "resonate-worker"

# Scale to 20 workers
pm2 scale resonate-worker 20

# Monitor
pm2 monit
```

## Hybrid deployments

You can mix deployment patterns:

**Example:** Server on Kubernetes, workers on Cloud Run

- Central server in GKE for stability
- Workers on Cloud Run for auto-scaling and cost efficiency

**Example:** Server on VM, workers in Lambda

- Self-hosted server for control
- Serverless workers for variable load

Resonate doesn't care where workers run as long as they can reach the server.

## Which pattern to choose?

**Start simple, scale as needed:**

| Use case                           | Recommended pattern         |
| ---------------------------------- | --------------------------- |
| Local development                  | Docker Compose              |
| Small production (&lt;10 workers)  | Docker Compose or single VM |
| Medium production (10-100 workers) | Kubernetes or Cloud Run     |
| Large production (&gt;100 workers) | Kubernetes with HPA         |
| Variable/unpredictable load        | Cloud Run or Fargate        |
| Event-driven workloads             | Lambda workers              |
| Cost-sensitive                     | Cloud Run (scales to zero)  |

**General guidance:**

- Use managed services for PostgreSQL (RDS, Cloud SQL, etc.)
- Start with containers (easier debugging than serverless)
- Add auto-scaling when you understand your load patterns
- Use serverless for unpredictable or bursty workloads

## Summary

Resonate works in any environment:

- **Containers:** Docker Compose, Kubernetes, Fargate, Cloud Run
- **Serverless:** Lambda, Cloud Functions
- **Bare metal:** Systemd, PM2, manual processes

**The pattern is always the same:**

1. Run one Resonate server (coordinates work)
2. Run N workers (execute your code)
3. Connect workers to server via `RESONATE_URL`

Choose your infrastructure based on your operational preferences and scale requirements. Resonate adapts to where you want to run.

---

---
url: https://docs.resonatehq.io/deploy
title: Deploy a Resonate application
---

<img src="/images/banner-deploy-dark.png" alt="Deploy Resonate applications section" className="hidden dark:block" />
<img src="/images/banner-deploy-light.png" alt="Deploy Resonate applications section" className="block dark:hidden" />

Deployment is how you take Resonate from your laptop to production. This section covers everything you need to run Resonate reliably at any scale.

## What you're deploying

Resonate has two components:

1. **Resonate Server** - Coordinates work, stores durable promise state, routes tasks to workers
2. **Workers** - Execute your application code (functions you write)

**Key insight:** The server coordinates. Workers execute. This separation means you scale execution capacity (workers) independently from coordination (server).

## The deployment spectrum

"Production" means different things depending on your scale:

### Development

**Local testing** - Start with `resonate dev`:

- Single command starts server with SQLite
- No Docker or PostgreSQL required
- Logs to stdout, hot-reload friendly
- Perfect for development iteration

**When you need more:**
- Docker Compose for full stack (server + database + workers together)
- Useful for testing worker scaling or database behavior

**What matters:** Fast iteration, easy debugging.

### Staging

**Pre-production testing** - Similar to production but isolated:

- PostgreSQL for realistic behavior
- Multiple workers to test load distribution
- Observability setup (logs, metrics)
- Authentication enabled

**What matters:** Catch integration issues before they hit production.

### Production

**Real workloads** - Scale and reliability matter:

- PostgreSQL with high availability
- Workers scaled to handle load (5-100+)
- Full observability (logging, metrics, tracing)
- Authentication enabled
- Monitoring and alerting

**What matters:** Uptime, performance, security.

## How to deploy Resonate

### 1. Choose your infrastructure

Where do you want to run Resonate?

- **Containers** (Docker, Kubernetes) → See [Deployment patterns](/deploy/deployment-patterns)
- **Serverless** (Cloud Run, Lambda, Fargate) → See [Deployment patterns](/deploy/deployment-patterns)
- **Bare metal / VMs** → See [Deployment patterns](/deploy/deployment-patterns)

Resonate works anywhere. Choose based on your operational preferences.

### 2. Run the server

Start the Resonate server with persistent storage:

- **Development:** SQLite is fine
- **Production:** Use PostgreSQL (see [Run server](/deploy/run-server))

The server coordinates work for all your workers.

Already run ScyllaDB, NATS, or Postgres and would rather not add a database beside it? Resonate publishes a separate server implementation of the protocol for each. The ScyllaDB and NATS providers are source-available under BUSL-1.1; the Postgres provider is Apache 2.0. See [Server providers](/deploy/providers).

### 3. Deploy workers

Workers execute your application code:

- Start with 2-4 workers
- Scale horizontally based on load (see [Scaling](/deploy/scaling))
- Workers connect to the server via `RESONATE_URL`

### 4. Set up observability

You can't manage what you can't measure:

- **Logging** → See [Logging](/deploy/logging)
- **Metrics** → See [Metrics](/deploy/metrics)
- **Tracing** → See [Tracing](/deploy/tracing)

### 5. Secure it

Enable authentication for production:

- **Authentication** → Token-based (JWT) or basic auth
- **Secrets** → Store credentials safely

See [Security](/deploy/security) for details.

### 6. Ensure availability

Make your deployment resilient:

- **PostgreSQL HA** → Use managed services (RDS, Cloud SQL)
- **Worker fault tolerance** → Automatic via heartbeats
- **Server monitoring** → Health checks and alerts

See [Availability](/deploy/availability) for HA patterns.

## What to read first

**If you're just starting:**

1. [Run server](/deploy/run-server) - Get the server running locally
2. [Deployment patterns](/deploy/deployment-patterns) - See your infrastructure options
3. [Scaling](/deploy/scaling) - Understand how workers scale

**If you're going to production:**

1. [Deployment patterns](/deploy/deployment-patterns) - Choose your infrastructure
2. [Production readiness](/deploy/production-readiness) - Configuration checklist before sending real traffic
3. [Availability](/deploy/availability) - Set up PostgreSQL HA
4. [Security](/deploy/security) - Enable authentication
5. [Scaling](/deploy/scaling) - Plan for load
6. [Logging](/deploy/logging), [Metrics](/deploy/metrics), [Tracing](/deploy/tracing) - Observe everything

**If you're debugging issues:**
Go to [Debug](/debug) - that section is for troubleshooting.

## Decision tree

Not sure where to start? Follow this:

```
Are you developing locally?
  └─ Yes → Start with `resonate dev` (simplest, no Docker needed)
  └─ No → Continue

Do you need production reliability?
  └─ No → Use Docker Compose with PostgreSQL for staging
  └─ Yes → Continue

What infrastructure do you prefer?
  ├─ Kubernetes → See Kubernetes deployment pattern
  ├─ Serverless (Cloud Run, Lambda) → See serverless deployment pattern
  ├─ Bare metal / VMs → See systemd deployment pattern
  └─ Not sure → Start with Docker Compose, migrate later

How many workers do you need?
  ├─ &lt;10 → Start with Docker Compose or simple VM deployment
  ├─ 10-100 → Use Kubernetes with HPA or Cloud Run with auto-scaling
  └─ &gt;100 → Use Kubernetes with horizontal pod autoscaling

Do you have variable/unpredictable load?
  └─ Yes → Use serverless (Cloud Run, Fargate) for auto-scaling
  └─ No → Use containers with manual scaling
```

## Common patterns

### Small production (1-10 workers)

**Pattern:** Docker Compose + managed PostgreSQL

```yaml
services:
  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    environment:
      RESONATE_STORAGE__TYPE: postgres
      RESONATE_STORAGE__POSTGRES__URL: postgres://<USER>:<PASSWORD>@your-postgres.rds.amazonaws.com:5432/resonate

  worker:
    image: your-app:latest
    environment:
      RESONATE_URL: http://resonate-server:8001
    deploy:
      replicas: 5
```

**Why:** Simple, low-cost, easy to manage. Perfect for small teams. See [Deploy to Railway](/deploy/railway) for a step-by-step walkthrough of the same pattern on a PaaS.

### Medium production (10-100 workers)

**Pattern:** Kubernetes + Cloud SQL + HPA

- Resonate server: 1 replica (single server coordinates all workers)
- Workers: Deployment with HorizontalPodAutoscaler
- PostgreSQL: Managed service (Cloud SQL, RDS)

**Why:** Kubernetes handles scaling, managed services handle ops.

### Large production (100+ workers)

**Pattern:** Kubernetes + replicated PostgreSQL + regional deployment

- Same as medium, but with PostgreSQL replication for HA
- Regional worker deployments for latency
- Advanced monitoring and alerting

**Why:** Scale requires automation and redundancy.

### Variable load

**Pattern:** Cloud Run or Fargate workers + managed PostgreSQL

- Workers scale to zero when idle
- Auto-scale to 100+ during load spikes
- Pay only for what you use

**Why:** Serverless auto-scaling handles unpredictable workloads.

## Architecture principles

Understanding these principles helps you deploy Resonate effectively:

### 1. Server coordinates, workers execute

The server never runs your code. It coordinates work and stores durable promise state. This means:

- Server resource needs are modest (2-4 CPUs, 4-8GB RAM)
- Workers scale to handle load
- You can restart workers without losing work

### 2. State lives in the database

All execution state is stored in PostgreSQL (or SQLite for dev). This means:

- Server restarts don't lose work
- Worker failures don't lose work
- Database availability = system availability

### 3. Workers are stateless and interchangeable

Workers poll for tasks and execute them. Any worker in a group can handle any task. This means:

- Workers scale horizontally (add as many as you need)
- Workers can be restarted safely
- Load balances automatically

### 4. Fault tolerance is built-in

Resonate handles worker failures automatically via heartbeat timeouts. This means:

- No manual intervention for worker crashes
- Work is reassigned automatically
- Execution resumes from last checkpoint

## What's not covered yet

Some features you might expect in a production deployment:

**Multi-server coordination** - Resonate doesn't support running multiple server instances that coordinate with each other. One server coordinates many workers.

**Automatic server failover** - No built-in failover between multiple servers. Use PostgreSQL HA/replication for state persistence.

**Cross-region disaster recovery** - Use standard PostgreSQL replication patterns and manual failover procedures.

These features aren't implemented because **worker horizontal scaling** handles the vast majority of scale needs. The server coordinates work but doesn't execute it, so it's rarely a bottleneck.

## Summary

**To deploy Resonate:**

1. Run one server (coordinates all work)
2. Run N workers (execute your code)
3. Use PostgreSQL for production
4. Scale workers horizontally for capacity
5. Enable observability and security

**Start simple, scale as needed.** You can begin with Docker Compose on a single VM and grow to Kubernetes with 100+ workers when your workload requires it.

---

**Next:** Ready to run the server? See [Run server](/deploy/run-server).

---

---
url: https://docs.resonatehq.io/deploy/kafka
title: Kafka integration
---

## TL;DR

Resonate does not ship a native Kafka transport in the current server. The supported integration today is the **Kafka worker pattern**: your code consumes Kafka with a normal client library and dispatches a Resonate workflow per message. Native `kafka://` transport is specified in the [Message Passing Protocol](https://distributed-async-await.io/spec/execution-model/message-passing#address-schemes) and is on the roadmap — when it ships, the server will deliver task messages over Kafka directly.

## The Kafka worker pattern

Use a regular Kafka consumer (`kafkajs`, `confluent-kafka-python`, `rdkafka`, etc.) and call `beginRun` on each message. A stable per-message identifier becomes the Resonate promise ID, so the dispatch is idempotent — duplicate deliveries reconnect to the in-flight execution rather than starting over.

```ts title="src/consumer.ts"
import { Kafka } from "kafkajs";
import { resonate } from "./workflow";

const kafka = new Kafka({ brokers: ["localhost:9092"] });
const consumer = kafka.consumer({ groupId: "workers" });

await consumer.connect();
await consumer.subscribe({ topic: "records_to_process", fromBeginning: true });

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    // topic-partition-offset uniquely identifies the message even when no key is set
    const messageId = `${topic}-${partition}-${message.offset}`;
    await resonate.beginRun(messageId, "workflow", messageId, message.offset);
  },
});
```

If your producer sets a stable message key (or your payload carries a domain ID like a record UUID), that's also a valid promise ID — the only requirement is that the same logical message always resolves to the same string.

Full TypeScript / Python / Rust walkthroughs and runnable repos are on the [Kafka worker example page](/get-started/examples/kafka-worker). Source repos:

- [example-kafka-worker-ts](https://github.com/resonatehq-examples/example-kafka-worker-ts)
- [example-kafka-worker-py](https://github.com/resonatehq-examples/example-kafka-worker-py)
- [example-kafka-worker-rs](https://github.com/resonatehq-examples/example-kafka-worker-rs)

## Idempotent dispatch

Every Kafka message has a stable identifier you can derive from its coordinates: `${topic}-${partition}-${offset}` is unique by construction, and a producer-supplied key (or a domain ID inside the payload) works equally well when present. Pass that identifier as the Resonate promise ID:

```ts
await resonate.beginRun(messageId, "workflow", ...args);
```

Resonate dedupes by promise ID. A consumer that crashes after starting a workflow but before committing the offset will redeliver the same message on restart. The redelivery hits `beginRun` with the same ID, Resonate recognizes the in-flight execution, and the workflow resumes from its last checkpoint instead of starting over. No per-message dedup table, no idempotency key bookkeeping — the workflow ID is the idempotency key.

This is the property that makes the worker pattern crash-safe: the consumer can be at-least-once, and the dispatch into Resonate stays exactly-once.

## What about `@resonatehq/kafka`?

The `@resonatehq/kafka` NPM package (and the [resonatehq/resonate-transport-kafka-ts](https://github.com/resonatehq/resonate-transport-kafka-ts) repo) targets the **legacy Go server**, not the current Rust server. It expects server flags like `--api-kafka-enable` that don't exist in the current server binary. Don't install it expecting it to wire up against a current Resonate Server — it won't.

If you want native Kafka transport, watch:

- The [`kafka://` address scheme](https://distributed-async-await.io/spec/execution-model/message-passing#address-schemes) in the protocol specification.
- The [Planned section](/deploy/message-transports#planned) of the Message transports page — it gets updated when transports land in the server.

## Roadmap

Native Kafka transport is on the roadmap. See [Message transports — Planned](/deploy/message-transports#planned) for status, and the [Kafka worker example](/get-started/examples/kafka-worker) for the supported integration today.

---

---
url: https://docs.resonatehq.io/deploy/logging
title: Logging
---

Both the Resonate Server and Resonate SDK emit structured logs that can help you observe and diagnose the behavior of your application.

## Server logs

Resonate emits structured logs via the Rust `tracing` ecosystem.
On startup the server installs a text subscriber that writes key/value records to standard output at the operator-selected minimum log level.

### Configuring the log level

Log levels: `debug`, `info`, `warn`, or `error`. The default is `info`.

Set it in `resonate.toml`:

```toml title="resonate.toml"
level = "debug"
```

Or via environment variable:

```shell
RESONATE_LEVEL=debug
```

Or via CLI flag (takes precedence over the file and env):

```shell
resonate serve --level debug
```

### Log levels and common messages

#### Debug – detailed flow diagnostics

Enabled with `RESONATE_LEVEL=debug` or `--level debug`.

Useful for tracing individual request outcomes, especially around promise lifecycle and task dispatch.

- Promise lifecycle: messages like `Promise not found`, `Promise created already timedout`, `Promise settle: promise not found`, and `Promise settle: TOCTOU race detected, treating as not found` explain why an incoming promise request returned what it did.
- Task lifecycle: `Task acquire: task not found`, `Task continue: not found`, `Task fulfill rejected: version mismatch or invalid state`, `Task fence rejected: task not found`.
- Listener / callback registration: `Listener registration: awaited promise not found`, `Callback registration: awaited promise not found`.
- Schedule lookups: `Schedule not found`, `Schedule delete: not found`.

Every debug line includes structured fields such as `promise_id`, `task_id`, `schedule_id`, `version`, and (where relevant) `fenced_action`.

#### Info – lifecycle and service announcements

Emitted by default (the default `level` is `info`).

- Server startup: `Resonate Server starting` reports the listener port; `Operational config` and `Transport config` follow with the resolved configuration.
- Storage initialization: `SQLite initialized` or `PostgreSQL initialized` (`PostgreSQL pool configured` lists the pool size).
- Auth state: `Auth disabled — all requests accepted`, or `Auth enabled` with the public key path (and `Auth issuer configured` / `Auth audience configured` when those claims are enforced).
- Transport state: `GCP Pub/Sub transport enabled` when `[transports.gcps]` is configured.
- Task recovery: `Task continued from halted state` indicates a previously halted task resumed.

#### Warn – recoverable or throttling conditions

Warnings surface when Resonate recovers automatically but an operator may want to know.

- Auth in unsigned mode: `Auth enabled — unsigned mode (no signature verification)` when `[auth].publickey = "none"`. Fine for dev, dangerous in prod.
- Task dispatch quirk: `Task fulfilled but promise not found` — the task completed but its promise record has since disappeared.
- Shutdown pressure: `Background tasks did not finish within shutdown timeout, forcing exit` when the graceful shutdown window was exceeded.

#### Error – actionable failures

Errors identify conditions that usually require operator action.

- Startup failures: `Fatal: ...` to stderr plus an `ERROR` record describing what aborted `resonate serve` (for example, `storage.type=postgres requires RESONATE_STORAGE__POSTGRES__URL`).
- Metrics bind failures: `Failed to bind metrics port` with the port that was in use.
- Background loop failures: `Background timeout processing failed: storage error` indicates the background timeout scanner hit a storage-layer problem.
- Readiness probe failures: `Readiness check failed: storage database unavailable` is emitted each time `GET /ready` returns 503.

### Log output format

Logs are written to stdout in `tracing`'s default key-value text format:

```
2026-04-15T10:30:00.123Z  INFO resonate: Resonate Server starting port=8001
2026-04-15T10:30:00.456Z  INFO resonate: Using SQLite backend path="resonate.db"
2026-04-15T10:30:00.789Z  INFO resonate: Auth disabled — all requests accepted
```

**Fields:**
- ISO 8601 timestamp with millisecond precision
- Level (`DEBUG`, `INFO`, `WARN`, `ERROR`)
- Target (e.g. `resonate`)
- Human-readable message plus structured key=value fields


## SDK logs

The Resonate SDKs also emit logs for observing application behavior.

### TypeScript SDK

The TypeScript SDK uses console logging by default:

```typescript
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  logLevel: "debug",  // debug | info | warn | error
});
```

**What gets logged:**
- Function execution (start, completion, errors)
- Context operations (`ctx.run()`, `ctx.sleep()`, etc.)
- RPC calls to workers
- Promise resolution attempts
- Retry attempts and failures

### Python SDK

The Python SDK uses Python's standard `logging` module:

```python
import logging
from resonate import Resonate

# Configure Python logging
logging.basicConfig(level=logging.INFO)

resonate = Resonate.remote(
    host="http://localhost",
    store_port="8001",
    message_source_port="8001",
    log_level="DEBUG",  # DEBUG | INFO | WARNING | ERROR | CRITICAL (or a logging.* int)
)
```

## Production logging patterns

### Log aggregation

In production, collect logs from all servers and workers into a centralized system:

**Common patterns:**
- **ELK Stack** (Elasticsearch, Logstash, Kibana)
- **Datadog** logs
- **CloudWatch Logs** (AWS)
- **Google Cloud Logging**
- **Azure Monitor Logs**
- **Grafana Loki** (lightweight alternative)

### Docker / Kubernetes

**Docker Compose:**

```yaml
services:
  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"
```

**Kubernetes:**

Logs are automatically collected from stdout. Use a log aggregation solution like:

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: resonate-server
  annotations:
    # Datadog log collection
    ad.datadoghq.com/resonate.logs: '[{"source":"resonate","service":"resonate-server"}]'
spec:
  containers:
  - name: server
    image: resonatehqio/resonate:v0.9.8
```

Or use Fluent Bit / Fluentd as a DaemonSet to forward logs to your aggregation system.

### Structured logging for analysis

Parse structured logs into fields for querying:

**Logstash filter example:**

```ruby
filter {
  grok {
    match => { "message" => "time=%{TIMESTAMP_ISO8601:timestamp} level=%{WORD:level} msg=\"%{DATA:message}\"" }
  }
}
```

**Query examples (CloudWatch Insights):**

```sql
# Find all errors
fields @timestamp, level, msg
| filter level = "ERROR"
| sort @timestamp desc

# Count warnings by type
fields msg
| filter level = "WARN"
| stats count() by msg
```

## What to log and monitor

### Critical events

Always monitor these log messages:

**Server startup failures:**
```
ERROR resonate: Fatal: storage.type=postgres requires RESONATE_STORAGE__POSTGRES__URL
ERROR resonate: Failed to bind metrics port port=9090
```
**Action:** Check configuration and that required ports are free.

**Readiness failures:**
```
ERROR resonate: Readiness check failed: storage database unavailable
```
**Action:** Investigate database health — `GET /ready` is returning 503 until storage recovers.

**Background loop failures:**
```
ERROR resonate: Background timeout processing failed: storage error
```
**Action:** Check database health and connection pool; sustained failures block timeout handling.

**Shutdown pressure:**
```
WARN resonate: Background tasks did not finish within shutdown timeout, forcing exit
```
**Action:** Consider raising `[server].shutdown_timeout` or investigating what's blocking shutdown.

### Normal operational events

These logs indicate healthy operation:

```
INFO resonate: Resonate Server starting port=8001
INFO resonate: PostgreSQL initialized
INFO resonate: Auth disabled — all requests accepted
```

## Log retention and storage

### Development

- **Retention:** 1-7 days
- **Level:** `debug` or `info`
- **Storage:** Local files or stdout

### Staging

- **Retention:** 7-30 days
- **Level:** `info`
- **Storage:** Centralized log aggregation

### Production

- **Retention:** 30-90 days (or per compliance requirements)
- **Level:** `info` (use `debug` temporarily for troubleshooting)
- **Storage:** Centralized log aggregation with archival to object storage (S3, GCS)

## Performance considerations

### Log volume

**Debug logging produces significant volume.** In production:
- Use `info` by default
- Enable `debug` temporarily when troubleshooting
- Monitor log storage costs

**Estimate:** Debug logging can produce 10-100x more log data than info level.

### Log sampling

For very high-throughput systems, consider sampling:

```yaml
# Hypothetical config (not currently supported)
logSampling:
  enabled: true
  rate: 0.1  # Log 10% of requests at debug level
```

**Alternative:** Use tracing (see [Tracing](/deploy/tracing)) for detailed execution visibility without overwhelming logs.

## Correlating logs across components

Use **request IDs** to trace requests across server and workers:

**Server logs:**
```
level=INFO msg="api:sqe:enqueue" requestId="req-abc123" method="POST" path="/promises"
```

**SDK logs:**
```
level=INFO msg="promise created" requestId="req-abc123" promiseId="order.123"
```

Search logs by `requestId` to see the full request lifecycle.

## Common debugging scenarios

### Task not being processed

**Look for:**
1. Worker registration: `starting poll server` (server) + connection logs (worker)
2. Task creation: `api:sqe:enqueue` with promise/task IDs
3. Task routing: Check for `failed to match promise` warnings
4. Worker heartbeat: Look for heartbeat timeout warnings

### Promise stuck pending

**Look for:**
1. Promise creation: `api:sqe:enqueue` with promiseId
2. Task assignment: Check if task was created and routed
3. Worker processing: Worker should log function execution start
4. Completion: Look for promise resolution logs

### Slow performance

**Look for:**
1. `scheduler queue full` - Capacity exhausted
2. Database query latency - Check database logs
3. High request volume - Count `api:sqe:enqueue` per second

## Best practices

1. **Start with `info` level** - Debug is too verbose for production
2. **Use structured logging** - Parse key-value pairs for analysis
3. **Aggregate centrally** - Don't rely on local log files
4. **Set up alerts** - Monitor critical error patterns
5. **Retain logs adequately** - Balance cost vs troubleshooting needs
6. **Correlate with metrics** - Cross-reference logs with metrics for complete picture
7. **Test log queries** - Ensure you can find what you need during incidents

## Summary

**For development:**
- Use `debug` or `info` level
- Logs to stdout are fine
- Focus on understanding normal behavior

**For production:**
- Use `info` level (enable `debug` only when troubleshooting)
- Centralize logs (ELK, Datadog, CloudWatch, etc.)
- Alert on critical errors (startup failures, database errors)
- Retain logs 30-90 days minimum
- Correlate logs with metrics and traces

Logs are your debugging lifeline. Set them up properly from day one.

---

---
url: https://docs.resonatehq.io/deploy/message-transports
title: Message transports
---

The Resonate Server delivers task messages to workers over a configurable set of transports. As of v0.9.8, four transports ship in the server binary:

| Transport | Address scheme | Enable flag | Default |
|---|---|---|---|
| HTTP push | `http://` / `https://` | `--transports-http-push-enabled` | `true` |
| HTTP poll (SSE) | (used by SDK clients that long-poll the server) | `--transports-http-poll-enabled` | `true` |
| GCP Pub/Sub | `gcps://` | `--transports-gcps-enabled` | `false` |
| Bash exec | `bash://` | `--transports-bash-exec-enabled` | `false` |

Each transport can be turned on or off independently. The full CLI flag list is on the [Run a server](/deploy/run-server#cli-flags) page; the equivalent `resonate.toml` keys live under `[transports.<name>]`.

## HTTP push

The HTTP push transport delivers task messages by `POST`ing to a worker URL embedded in the task address (for example `https://workers.example.com/tasks`). It's enabled by default and needs no further configuration for unauthenticated targets.

For deployments where the target service requires authentication, the server can sign outbound requests with a static bearer token or a GCP OIDC ID token. See [Outbound HTTP push authentication](/deploy/security#outbound-http-push-authentication) on the Security page.

## HTTP poll (SSE)

The HTTP poll transport lets SDK clients receive tasks over a long-lived Server-Sent Events stream instead of an inbound HTTP push. It's enabled by default and requires no per-deployment configuration; concurrency limits are tunable via `--transports-http-poll-max-connections` and `--transports-http-poll-buffer-size`.

## GCP Pub/Sub

The GCP Pub/Sub transport puts task messages onto Pub/Sub topics for consumption by SDK clients using the matching client-side plugin.

Enable it at runtime with the GCP project ID:

```shell
resonate serve \
  --transports-gcps-enabled true \
  --transports-gcps-project my-gcp-project-id
```

Or in `resonate.toml`:

```toml
[transports.gcps]
enabled = true
project = "my-gcp-project-id"
```

Or via env var: `RESONATE_TRANSPORTS__GCPS__ENABLED=true` and `RESONATE_TRANSPORTS__GCPS__PROJECT=my-gcp-project-id`.

Authentication uses Application Default Credentials (ADC) — make sure the server process has access to credentials with publish rights on the target project.

## Bash exec

The bash exec transport runs an inline shell script for each delivered task. It's intended for local-process workers, lightweight wrappers around CLI tools, agent sandboxes, and self-hosted single-host deployments where running a separate worker process is overkill.

The transport is **disabled by default**. Enable it explicitly:

```shell
resonate serve --transports-bash-exec-enabled true
```

Or in `resonate.toml`:

```toml
[transports.bash_exec]
enabled = true
```

Or via env var: `RESONATE_TRANSPORTS__BASH_EXEC__ENABLED=true`.

Enabling is the only configuration the transport takes — there are no script-directory or working-directory settings.


The bash exec transport runs arbitrary shell scripts. The **local** backend runs them as the user running the server, so only enable it on hosts where every promise creator is trusted. The **docker** and **tensorlake** backends isolate execution in a container or remote sandbox.


### Backends

The script body is always **inline** — it travels in the promise's `param.data` (base64-encoded). The task address selects which backend runs it:

| Address | Backend | What runs |
|---|---|---|
| `bash://` | Local | `bash -c "<script>"` on the server host |
| `bash://docker/<image>` | Docker | `docker run --rm --entrypoint bash <image> -c "<script>"` (requires the `docker` CLI on the server host; the promise environment variables are passed through with `-e`) |
| `bash://tensorlake/<image>` | Tensorlake | the script in a [Tensorlake](https://tensorlake.ai) sandbox; requires `TENSORLAKE_API_KEY` in the server's environment. An empty `<image>` uses Tensorlake's default sandbox |

Named scripts (a filesystem path after the scheme, e.g. `bash:///path/to/script.sh`) are **not supported** — `bash://` carries no path, and the local backend rejects an address that includes one.

### Inline scripts

Set the promise's `param.data` to the base64-encoded script body:

```bash
echo -n 'echo "hello from $RESONATE_PROMISE_ID"' | base64
# ZWNobyAiaGVsbG8gZnJvbSAkUkVTT05BVEVfUFJPTUlTRV9JRCI=
```

Then create a task targeting `bash://` (or `bash://docker/<image>` / `bash://tensorlake/<image>`) with that base64 as `param.data`.

### Script environment

The server sets three variables in the script's environment. All three are **stable across retries**, so a re-delivered task reproduces the same values:

| Variable | Value |
|---|---|
| `RESONATE_PROMISE_ID` | the originating promise id (correlate logs, metrics, or follow-on calls) |
| `RESONATE_PROMISE_CREATED_AT` | promise creation time, epoch milliseconds |
| `RESONATE_PROMISE_TIMEOUT_AT` | promise timeout, epoch milliseconds |

### Settle behavior

The promise is settled from the script's exit status:

- **Exit `0`** — the promise resolves with the script's `stdout` (trimmed of trailing whitespace) as the resolved value.
- **Exit non-zero** — the promise rejects. The rejection reason is the script's `stderr` if non-empty, otherwise the literal string `exit code N`.

A failure to spawn the backend — for example `docker` not on `PATH`, or a missing `TENSORLAKE_API_KEY` — rejects the promise with a descriptive reason, as does a `param.data` that is missing or not valid base64/UTF-8.

If the script is **killed by a signal** (a local kill, a docker OOM, or an exceeded Tensorlake sandbox lifetime), the run is treated as an infrastructure failure rather than a workflow failure: the task is dropped, the lease expires, and the message is re-dispatched to a fresh worker.

While the script runs, the server refreshes the task lease so long-running scripts don't lose it.

For the `resonate-bash` MCP tool, which drives this transport from Claude Code, see [Durable bash](/get-started/claude-code).

## Planned

The transports below are specified in the [Message Passing Protocol](https://distributed-async-await.io/spec/execution-model/message-passing#address-schemes) but are not yet implemented in the current server.

### Kafka


The published `@resonatehq/kafka` NPM plugin (v0.1.x) targets the **legacy Go-based** Resonate Server. It does **not** work with the current Rust server (v0.9.x). Use the [Kafka worker pattern](/deploy/kafka) today; native `kafka://` transport is on the roadmap below.


**Not available in the current server.** Native `kafka://` transport is on the roadmap.

For Kafka integration today, use a normal Kafka consumer to dispatch a Resonate workflow per message — see the [Kafka integration guide](/deploy/kafka) and the [Kafka worker example](/get-started/examples/kafka-worker).

The published `@resonatehq/kafka` plugin (and the [resonatehq/resonate-transport-kafka-ts](https://github.com/resonatehq/resonate-transport-kafka-ts) repo) targets the **legacy Go server** and does not work against the current Rust server. Don't install it expecting it to wire up.

### SQS

**Not available in the current server.** AWS SQS transport support is on the roadmap.

---

---
url: https://docs.resonatehq.io/deploy/metrics
title: Metrics
---

The Resonate server exposes a metrics endpoint `:9090/metrics` that is compatible with Prometheus.

The `aio` prefix refers to stuff that “goes out” of the server such as requests to the store, sending tasks to nodes, etc.
Coroutines refers to the units of business logic in the Server.

## Metrics exposed

### aio_connection

Number of aio subsystem connections.

- gauge
- `aio_connection{type="sender:poll"} 0`

### aio_in_flight_submissions

Number of in flight aio submissions.

- gauge
- `aio_in_flight_submissions{type="store"} 0`

### aio_total_submissions

Total number of aio submissions.

- counter
- `aio_total_submissions{status="success",type="store"} 0`

### aio_worker_count

Number of aio subsystem workers.

- gauge
- `aio_worker_count{type="router"} 0`
- `aio_worker_count{type="sender"} 0`
- `aio_worker_count{type="sender:http"} 0`
- `aio_worker_count{type="sender:poll"} 0`
- `aio_worker_count{type="store:sqlite"} 0`

### aio_worker_in_flight_submissions

Number of in flight aio submissions.

- gauge
- `aio_worker_in_flight_submissions{type="router",worker="0"} 0`
- `aio_worker_in_flight_submissions{type="sender",worker="0"} 0`
- `aio_worker_in_flight_submissions{type="sender:http",worker="0"} 0`
- `aio_worker_in_flight_submissions{type="sender:poll",worker="0"} 0`
- `aio_worker_in_flight_submissions{type="store:sqlite",worker="0"} 0`

### coroutines_in_flight number

Number of in flight coroutines.

- gauge
- `coroutines_in_flight{type="EnqueueTasks"} 0`
- `coroutines_in_flight{type="SchedulePromises"} 0`
- `coroutines_in_flight{type="TimeoutLocks"} 0`
- `coroutines_in_flight{type="TimeoutPromises"} 0`
- `coroutines_in_flight{type="TimeoutTasks"} 0`

### coroutines_total

Total number of coroutines.

- counter
- `coroutines_total{type="EnqueueTasks"} 0`
- `coroutines_total{type="SchedulePromises"} 0`
- `coroutines_total{type="TimeoutLocks"} 0`
- `coroutines_total{type="TimeoutPromises"} 0`
- `coroutines_total{type="TimeoutTasks"} 0`

## Using Prometheus

### Quick start

1. **Download Prometheus:** https://prometheus.io/download/

2. **Configure Prometheus** to scrape Resonate metrics:

```yml title="prometheus.yml"
global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  - job_name: "resonate-server"
    static_configs:
      - targets: ["localhost:9090"]  # Resonate metrics endpoint
        labels:
          app: "resonate"
          env: "production"
```

3. **Start Prometheus:**

```bash
# Run on port 9091 to avoid conflict with Resonate (which uses 9090)
./prometheus --config.file=prometheus.yml --web.listen-address=:9091
```

4. **Access Prometheus UI:**

Open http://localhost:9091 to query metrics and build dashboards.

### Prometheus in Docker

```yaml title="docker-compose.yml"
version: '3.8'
services:
  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    ports:
      - "8001:8001"
      - "9090:9090"  # Metrics endpoint

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9091:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus-data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'

volumes:
  prometheus-data:
```

### Prometheus in Kubernetes

```yaml title="prometheus-config.yaml"
apiVersion: v1
kind: ConfigMap
metadata:
  name: prometheus-config
data:
  prometheus.yml: |
    global:
      scrape_interval: 15s
    scrape_configs:
      - job_name: 'resonate'
        kubernetes_sd_configs:
          - role: pod
            namespaces:
              names:
                - default
        relabel_configs:
          - source_labels: [__meta_kubernetes_pod_label_app]
            regex: resonate-server
            action: keep
```

## Using Grafana

Grafana visualizes metrics from Prometheus.

### Quick start

1. **Download Grafana:** https://grafana.com/grafana/download

2. **Start Grafana:**

```bash
./grafana server
```

3. **Add Prometheus as a data source:**
   - Open http://localhost:3000 (default Grafana UI)
   - Go to Configuration → Data Sources
   - Add Prometheus
   - URL: `http://localhost:9091` (your Prometheus instance)

4. **Create dashboards** using PromQL queries.

### Example dashboard panels

**Promise workload:**

```text
# Total pending promises
promises_total{state="pending"}

# Promise rate by state
rate(promises_total[5m])
```

**Task processing:**

```text
# Total tasks by state
tasks_total{state="acquired"}
tasks_total{state="fulfilled"}

# Task completion rate
rate(tasks_total{state="fulfilled"}[5m])
```

**Server load:**

```text
# API request rate
rate(api_requests_total[5m])

# Coroutines in flight (internal queue depth)
sum(coroutines_in_flight)
```

## Key metrics to track

### Workload metrics

**Promise rate:**
```text
rate(promises_total[5m])
```
Indicates incoming workload. Track trends and spikes across all promise states.

**Pending promises:**
```text
promises_total{state="pending"}
```
Backlog of work. Should stay near zero. Growth indicates insufficient worker capacity or processing issues.

**Promise state distribution:**
```text
promises_total{state="resolved"}
promises_total{state="rejected"}
promises_total{state="canceled"}
```
Track outcomes to understand success/failure patterns.

### Task metrics

**Task completion rate:**
```text
rate(tasks_total{state="fulfilled"}[5m])
```
How fast tasks are being processed. Compare with promise rate to understand throughput.

**Acquired vs fulfilled:**
```text
tasks_total{state="acquired"}
tasks_total{state="fulfilled"}
```
Large gap between acquired and fulfilled indicates tasks are stalling.

### Server metrics

**API request rate:**
```text
rate(api_requests_total[5m])
```
Overall server load. High values indicate heavy traffic.

**API request latency:**
```text
histogram_quantile(0.95, rate(api_duration_seconds_bucket[5m]))
```
P95 latency for API requests. High values indicate performance bottlenecks.

**HTTP requests:**
```text
rate(http_requests_total[5m])
```
HTTP API usage. Track by method and path to understand traffic patterns.

**Coroutines in flight:**
```text
sum(coroutines_in_flight)
```
Server's internal work queue. High values indicate server capacity issues.

**AIO submissions:**
```text
rate(aio_total_submissions{status="success"}[5m])
rate(aio_total_submissions{status="failure"}[5m])
```
Server's asynchronous I/O operations (database, worker communication). Failures indicate infrastructure issues.

## Alerting rules

Set up alerts for critical conditions:

```yml title="alerts.yml"
groups:
  - name: resonate-alerts
    rules:
      - alert: ResonateServerDown
        expr: up{job="resonate-server"} == 0
        for: 1m
        labels:
          severity: critical
        annotations:
          summary: "Resonate server is down"
          description: "Resonate server has been down for more than 1 minute"

      - alert: HighAPIErrorRate
        expr: rate(api_requests_total{status=~"5.."}[5m]) > 10
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High API error rate"
          description: "More than 10 API errors per minute"

      - alert: PromiseBacklogGrowing
        expr: increase(promises_total{state="pending"}[5m]) > 100
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Promise backlog is growing"
          description: "Pending promises are accumulating - scale workers or check processing"

      - alert: TasksNotCompleting
        expr: tasks_total{state="acquired"} - tasks_total{state="fulfilled"} > 1000
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Tasks acquired but not completing"
          description: "Large gap between acquired and fulfilled tasks"

      - alert: HighAPILatency
        expr: histogram_quantile(0.95, rate(api_duration_seconds_bucket[5m])) > 5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "High API latency"
          description: "P95 API latency is over 5 seconds"
```

Load alerting rules in Prometheus:

```yml title="prometheus.yml"
global:
  scrape_interval: 15s

rule_files:
  - "alerts.yml"

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['localhost:9093']  # Alertmanager endpoint

scrape_configs:
  - job_name: "resonate-server"
    static_configs:
      - targets: ["localhost:9090"]
```

## Cloud provider integration

### AWS CloudWatch

Export metrics to CloudWatch using a bridge:

```yaml
# Use Prometheus CloudWatch exporter
- name: cloudwatch-exporter
  image: prom/cloudwatch-exporter:latest
```

Or use AWS Managed Prometheus (AMP):
- Creates a workspace for Prometheus
- Automatically scrapes metrics from ECS/EKS
- Integrated with CloudWatch dashboards

### Google Cloud Monitoring

Use Google Cloud Managed Prometheus:

```yaml title="prometheus.yaml"
global:
  external_labels:
    cluster: 'my-cluster'
    project_id: 'my-project'

scrape_configs:
  - job_name: 'resonate'
    kubernetes_sd_configs:
      - role: pod
```

Google Cloud Monitoring automatically imports Prometheus metrics.

### Datadog

Use the Datadog Agent to scrape Prometheus metrics:

```yaml title="datadog-agent-config.yaml"
apiVersion: v1
kind: ConfigMap
metadata:
  name: datadog-config
data:
  prometheus.yaml: |
    - prometheus_url: http://resonate-server:9090/metrics
      namespace: resonate
      metrics:
        - resonate_*
```

## Best practices

1. **Set retention policies** - Prometheus defaults to 15 days. Adjust based on needs:
```bash
./prometheus --storage.tsdb.retention.time=90d
```

2. **Use recording rules** for expensive queries:
```yml
groups:
  - name: resonate-recording-rules
    interval: 1m
    rules:
      - record: resonate:promise_creation_rate:5m
        expr: rate(resonate_promises_created_total[5m])
```

3. **Monitor Prometheus itself**:
```text
prometheus_tsdb_storage_blocks_bytes  # Storage usage
prometheus_target_scrapes_exceeded_sample_limit_total  # Cardinality issues
```

4. **Use labels strategically** - Don't add high-cardinality labels (e.g., user IDs, promise IDs)

5. **Alert on trends, not thresholds** - Use `rate()` and time windows to detect anomalies

6. **Test alerts** - Trigger alerts intentionally to verify they work

## Troubleshooting metrics

### Metrics endpoint not accessible

**Check server is running:**
```bash
curl http://localhost:9090/metrics
```

Should return Prometheus-formatted metrics.

**Check metrics port configuration:**

The metrics port defaults to `:9090`. Override via `resonate.toml`:

```toml
[observability]
metrics_port = 9091
```

via env var (`RESONATE_OBSERVABILITY__METRICS_PORT=9091`), or via CLI flag (`resonate serve --observability-metrics-port 9091`). Set the port to `0` to disable the metrics endpoint entirely.

### Prometheus not scraping metrics

**Check Prometheus targets:**
- Open http://localhost:9091/targets
- Look for your Resonate server job
- Status should be "UP" with green indicator

**Common issues:**
- Wrong target address (hostname/port)
- Network/firewall blocking access
- Prometheus config not loaded (restart Prometheus)

### Missing metrics

**Not all metrics appear immediately.** Some are only emitted when events occur:
- `promises_total` - Only increments when promises are created/resolved
- `tasks_total` - Only increments when tasks are created/completed
- `http_requests_total` - Only increments when HTTP requests are made

Run workload to generate metrics.

**Metrics not currently exposed:**
- Worker heartbeat failures (monitor worker pod restarts at infrastructure level)
- Database connection pool stats (PostgreSQL exposes these separately)
- Per-worker execution metrics (not tracked at server level)

## Summary

**For development:**
- Run Prometheus locally
- Use Prometheus UI for ad-hoc queries
- Focus on understanding baseline metrics

**For production:**
- Use managed Prometheus (AWS AMP, GCP Managed Prometheus, Grafana Cloud)
- Set up Grafana dashboards
- Configure alerting for critical conditions
- Monitor trends, not just point-in-time values
- Integrate with your existing observability stack

**Key metrics to always track:**
- `promises_total` by state (workload)
- `tasks_total` by state (processing throughput)
- `api_requests_total` (server load)
- `coroutines_in_flight` (server capacity)

**What's not metricked:**
- Individual worker health (monitor at infrastructure level: K8s pod restarts, container health)
- Database connection pools (use PostgreSQL's own metrics)
- Promise/task latency histograms (not currently exposed)

Metrics give you visibility into system health. Set them up before you need them.

---

---
url: https://docs.resonatehq.io/deploy/production-readiness
title: Production readiness
---

This page describes the recommended production configuration for the Resonate server, what operational surface the server exposes, and what to verify before you send real traffic.

## Recommended deployment shape

The standard production deployment has three layers:

1. **One Resonate server** — coordinates promises, schedules tasks, routes work to workers. Runs as a single process backed by persistent storage.
2. **A managed PostgreSQL database with HA** — stores all execution state. The server's durability guarantee is only as strong as the database's.
3. **Horizontally scaled workers** — execute your application code. Add as many as the workload requires; there is no fixed limit.

Workers scale horizontally without any server-side coordination because they pull work from the server rather than requiring the server to know about them statically. The server does not execute your functions, so worker pod restarts or crashes do not lose in-flight execution state — state is always in the database.

For the Kubernetes manifest that wires this together, see [Run server](/deploy/run-server#run-on-kubernetes). For the full set of infrastructure patterns (Cloud Run, Fargate, bare-metal systemd), see [Deployment patterns](/deploy/deployment-patterns).

## Server constraints

### No horizontal server scaling

The server runs as a single instance — multi-server coordination is not yet implemented (true of the current released version, v0.9.8, and of `main`). In practice this is rarely a capacity limit: the server coordinates work but never executes your functions, so a single instance comfortably handles thousands of task dispatches per second. Scale vertically if you observe the server as a bottleneck, and keep scaling workers horizontally; see [Scaling](/deploy/scaling). Two independent servers sharing one database race to process the same timeouts and task queues, so keep `replicas: 1` (or `--max-instances=1` on Cloud Run) — the checklist below carries this as its first server item.

### State in the database

All durable promise state lives in PostgreSQL (or MySQL). A server restart is safe — workers detect the disconnect, reconnect automatically, and resume from their last checkpoint. This also means database availability is the primary availability concern. See [Availability](/deploy/availability) for PostgreSQL HA options.

## Health and readiness endpoints

The server exposes `GET /health` (liveness — always `200` while the process is up) and `GET /ready` (readiness — `503` when storage is unreachable, logged as `Readiness check failed: storage database unavailable`) on the API port (`:8001` by default). A liveness probe on `/health` and a readiness probe on `/ready` is the recommended Kubernetes configuration. See [Run server > Health and readiness](/deploy/run-server#health-and-readiness) for the endpoint reference, probe configuration, and examples; the checklist below captures what to configure in your orchestrator.

## Prometheus metrics

The server runs a separate HTTP listener that exposes Prometheus metrics. The default port is `9090`; the endpoint is `GET /metrics`.

```shell title="Scrape metrics"
curl http://localhost:9090/metrics
```

The metrics port is controlled by `RESONATE_OBSERVABILITY__METRICS_PORT`. Set it to `0` to disable the endpoint entirely — for example, when your platform routes all external traffic through port `8001` and you want to block metrics from being publicly reachable:

```toml title="resonate.toml — disable metrics"
[observability]
metrics_port = 0
```

Or via environment variable:

```shell
RESONATE_OBSERVABILITY__METRICS_PORT=0
```

See [Metrics](/deploy/metrics) for the full metrics catalog, Prometheus scrape configuration, and Grafana dashboard examples.


Platforms that auto-detect a single primary port (Railway, Render, Fly.io) may route traffic to `:9090` instead of `:8001`. Explicitly route your platform to port `8001`. Consider disabling the metrics port or binding it to a private network interface if the platform exposes both ports publicly.


## Logs

The server writes structured key-value logs to stdout via the Rust `tracing` ecosystem. The default log level is `info`. Set `RESONATE_LEVEL=debug` for verbose request-level diagnostics; revert to `info` in production once the issue is resolved, since debug output is significantly higher volume.

For log aggregation, alerting on critical error patterns, and correlation with metrics, see [Logging](/deploy/logging).

## Graceful shutdown

The server handles `SIGTERM` and `SIGINT` for graceful shutdown. When a signal is received, the server:

1. Stops accepting new connections on the API port.
2. Signals background processing loops (timeout scanner, message dispatcher) to stop.
3. Waits up to the configured `shutdown_timeout` for background tasks to finish, then exits.

The default `shutdown_timeout` is `10000` milliseconds (10 seconds). Raise it if background loops are consistently interrupted before completing:

```toml title="resonate.toml"
[server]
shutdown_timeout = 30000  # milliseconds
```

Or via environment variable:

```shell
RESONATE_SERVER__SHUTDOWN_TIMEOUT=30000
```

Because all execution state is persisted in the database, a forceful exit during the shutdown window does not lose work — workers reconnect and tasks are reassigned after the server comes back up.

## Configuration for production

Configuration fields are reachable as environment variables (`RESONATE_` prefix, double-underscore nesting) or via `resonate.toml`; the full surface, defaults, and layering order are in [Run a server > Configuration](/deploy/run-server#configuration). The settings below are the ones with production-specific consequences:

| Setting | Default | Production guidance |
|---|---|---|
| `RESONATE_STORAGE__TYPE` | `sqlite` | Set to `postgres` — SQLite is not recommended for shared production workloads |
| `RESONATE_SERVER__URL` | — | No runtime default; set to the externally-reachable URL so workers can call back. Required on Cloud Run and similar |
| `RESONATE_TASKS__RETRY_TIMEOUT` | `30000` (ms) | Set to `500` for chained or recursive workflows; the default adds significant latency per suspend/wake cycle |
| `RESONATE_AUTH__PUBLICKEY` | — | Strongly recommended; without it the server logs `Auth disabled — all requests accepted`. See [Security](/deploy/security) |

Inject secrets (`RESONATE_STORAGE__POSTGRES__URL`, key paths, push-auth tokens) via environment variables or a secret manager — never commit them.

## Pre-launch checklist

Use this list before sending production traffic to a new deployment.

**Storage**
- [ ] `RESONATE_STORAGE__TYPE=postgres` — SQLite is not recommended for shared or multi-user production workloads
- [ ] PostgreSQL is a managed HA instance (Multi-AZ, Cloud SQL HA, Supabase, or equivalent)
- [ ] Connection string uses a dedicated database user with the minimum required permissions
- [ ] Backup and point-in-time recovery are confirmed and tested

**Server**
- [ ] `replicas: 1` (or equivalent) — multi-server is not supported; verify the container scheduler will not auto-scale the server
- [ ] `RESONATE_SERVER__BIND=0.0.0.0` so the API port is reachable from workers and the orchestrator
- [ ] `RESONATE_SERVER__URL` is set to the externally-reachable URL when workers call back from outside the server's local network
- [ ] `RESONATE_TASKS__RETRY_TIMEOUT` is tuned — `500` for chained workflows, `30000` only if low latency is not required

**Authentication**
- [ ] `RESONATE_AUTH__PUBLICKEY` is configured — the server logs `Auth disabled — all requests accepted` at startup when auth is off
- [ ] JWT keys are generated with `openssl genpkey -algorithm Ed25519`; private key is in a secret manager, not on disk or in a repo
- [ ] See [Security](/deploy/security) for the full auth configuration guide

**Observability**
- [ ] Liveness probe on `GET /health` (port `8001`)
- [ ] Readiness probe on `GET /ready` (port `8001`)
- [ ] Prometheus scraper pointed at port `9090` (or the configured `RESONATE_OBSERVABILITY__METRICS_PORT`)
- [ ] Log aggregation ingesting stdout from the server container
- [ ] Alert on `Readiness check failed: storage database unavailable` in server logs
- [ ] Alert on `Background tasks did not finish within shutdown timeout, forcing exit` in server logs

**Workers**
- [ ] Workers connect to the server via the `RESONATE_URL` environment variable (or equivalent SDK config)
- [ ] Worker Deployment has at least 2 replicas so worker restarts do not stall in-flight promises
- [ ] `RESONATE_TASKS__LEASE_TIMEOUT` on the server is larger than the maximum expected task execution time; otherwise tasks will be re-queued while still in progress

{/* Maintainers: if you have public-facing production users who have consented to being named, add a brief "Used by" or "Case studies" section here. Do not add users without explicit consent. */}

## Related pages

- [Run server](/deploy/run-server) — full configuration reference, CLI flags, and platform-specific manifests
- [Availability](/deploy/availability) — PostgreSQL HA setup, server restart procedures, and rolling update process
- [Security](/deploy/security) — JWT authentication, CORS, and outbound push auth
- [Scaling](/deploy/scaling) — worker scaling patterns and when to scale
- [Metrics](/deploy/metrics) — full Prometheus metrics catalog, Grafana setup, and alerting rules
- [Logging](/deploy/logging) — log levels, aggregation patterns, and critical error reference

---

---
url: https://docs.resonatehq.io/deploy/providers
title: Server providers
---

## TL;DR

Durable execution is a protocol, not a product. Any platform that gives you durable storage and an atomic compare-and-swap can implement the Resonate server protocol. A **provider** is one of those implementations: a separate artifact built for a specific platform — its own server binary, or in one case a SQL file you load into the database — not a storage flag on the core server. Resonate builds and maintains the three below, independently of the platforms they run on.

Most teams should run the core server. Reach for a provider when the platform it targets is one you already operate and would rather not add a database beside.

## What ships today

| Provider | Storage | Transport | License | Drop-in? |
|---|---|---|---|---|
| [Core server](/deploy/run-server) | Postgres, MySQL, SQLite | HTTP | Apache 2.0 | — |
| [ScyllaDB](/deploy/providers/scylladb) | ScyllaDB (CQL) | HTTP | Source-available (BUSL-1.1) | Yes |
| [NATS](/deploy/providers/nats) | NATS JetStream | NATS | Source-available (BUSL-1.1) | No |
| [Postgres](/deploy/providers/postgres) | Postgres | SQL (`resonate_rpc`); optional HTTP push | Apache 2.0 | No |

"Drop-in" means the provider speaks the same HTTP/JSON protocol the core server speaks, so your SDK and your application code do not change. Workers point at a different `RESONATE_URL`.

The NATS provider is not drop-in. It replaces both storage *and* transport, so it has no HTTP interface at all and workers connect over NATS using the `NatsNetwork` client built into the SDK. Your workflow code is unchanged; the client wiring is not, and only the TypeScript and Python SDKs have that client today.

The Postgres provider is not drop-in either, for a different reason. There is no server process to point a URL at — workers reach the protocol by calling a function inside the database, which needs a client that speaks SQL rather than HTTP. Only the TypeScript SDK has one today.


The core server *supports* Postgres: you run a binary, and Postgres is where it keeps its state. The Postgres provider *is* Postgres: there is no binary at all. Storage, queue, and timer are the database itself, with `pg_cron` driving all three. If you want a Resonate server that happens to store data in Postgres, run the core server. If you want durable execution with no process to deploy beside your database, read on.


## What a provider is not

- **Not a plugin.** There is no adapter interface to register a new backend against the core server. A provider is an independent implementation of the published protocol.
- **Not a configuration flag.** You do not get ScyllaDB by passing an option to `resonate serve`. You run a different binary. You do not get the Postgres provider by pointing `resonate serve` at a Postgres database — that is the core server using Postgres for storage, which is a different thing.
- **Licensing varies.** The core server and the Postgres provider are Apache 2.0. The ScyllaDB and NATS providers are source-available under BUSL-1.1 — free for development, testing, and evaluation, with production use requiring a commercial license until each version's Change Date. Read the license in the repository before you plan a production rollout.

## Maturity

The core server is the reference implementation and the default recommendation. The providers are newer, and they are not equally proven.

- **ScyllaDB** ships oracle-diff, crash, and linearizability suites — the deepest test coverage of the three.
- **NATS** has unit tests over the store, schedules, and tasks, but none of those suites.
- **Postgres** has no test suite in the repository at all. What it ships is a shim that lets an external conformance harness drive the database, and there are open correctness issues against task leasing and settlement that the tracker records honestly.

None of the three has a production reference deployment yet. Neither ScyllaDB nor NATS implements search; the Postgres provider does. Server-side authentication is absent from ScyllaDB and NATS, while the Postgres provider inherits Postgres's own — a dedicated role and an explicit grant surface.

Each provider page has a "What's not there yet" section. Read it before you commit to one.

## Building your own

The protocol is public. If you want durable execution on a platform that isn't listed here, the [server specification](https://distributed-async-await.io/) is the contract to implement, and the existing providers are worked examples of what a complete implementation looks like.

---

---
url: https://docs.resonatehq.io/deploy/providers/nats
title: Resonate on NATS
---

## TL;DR

[`resonate-on-nats`](https://github.com/resonatehq/resonate-on-nats) is a Go server that implements the Resonate protocol on NATS JetStream. JetStream KV holds the state and NATS carries the messages, so the provider needs no separate database.

Unlike the [ScyllaDB provider](/deploy/providers/scylladb), this one is **not drop-in**. It has no HTTP interface at all — workers reach it over NATS using the `NatsNetwork` client built into the TypeScript and Python SDKs. Your workflow code is unchanged; the client wiring is not.

It is source-available under BUSL-1.1, not Apache 2.0, and it is early. Read [What's not there yet](#whats-not-there-yet) before you plan a production rollout.

## When to use it

Use it when NATS is already your backbone and you would rather not add a database and an HTTP service beside it. If you aren't already running NATS, run the [core server](/deploy/run-server) on Postgres instead.

If you want durable execution without changing how your workers connect, the ScyllaDB provider speaks the same HTTP/JSON protocol as the core server and is the smaller change.

## Requirements

- **nats-server 2.14.x with JetStream enabled.** Durable timers use JetStream's built-in message schedules, and schedules carry cron-style recurrence, which landed in 2.14. The repository builds against 2.14.2, so treat 2.14 as the supported floor.
- Go 1.25+ to build from source.

## Run it

Build the binary:

```shell
git clone https://github.com/resonatehq/resonate-on-nats
cd resonate-on-nats
go build -o resonate-on-nats .
```

For local development, `dev` starts an embedded NATS server with a fresh store in a temporary directory, discarded on exit:

```shell
./resonate-on-nats dev
```

Against a NATS deployment you already operate:

```shell
./resonate-on-nats serve --nats-url nats://localhost:4222
```

### Flags

| Flag | `serve` default | `dev` default | Purpose |
|---|---|---|---|
| `--nats-url` | `nats://127.0.0.1:4222` | — | NATS server to connect to |
| `--partitions` | `16` | `1` | Total partition count for the stream |
| `--subscribe` | all | all | Partition indices this instance handles |
| `--debug` | `false` | `true` | Enables deterministic testing endpoints |
| `--port` | — | `4222` | Port for the embedded NATS server |
| `--log-level` | `info` | `info` | Global flag — `debug`, `info`, `warn`, `error` |

`--debug` exposes endpoints that let tests drive logical time (`debug.start`, `debug.stop`, `debug.reset`, `debug.tick`, `debug.snap`). It defaults **on** in `dev` and **off** in `serve`.


`debug.reset` purges the entire stream and every key in the KV bucket, and `debug.start` halts outbox delivery server-wide. Since the server has no authentication of its own, anyone who can publish to the request subject can invoke both. Never enable `--debug` on `serve`.


## Partitioning across instances

State lives in JetStream KV, partitioned across instances. Each instance subscribes to a subset of partitions and processes messages **serially per origin**, using optimistic concurrency for conflict-free multi-instance deployments.

To run several instances, give them all the same `--partitions` and split the work with `--subscribe`:

```shell
./resonate-on-nats serve --partitions 16 --subscribe 0,1,2,3
./resonate-on-nats serve --partitions 16 --subscribe 4,5,6,7
```

Every instance must agree on `--partitions`. Treat it the way you'd treat any partition count: pick it with room to grow, because changing it later means resharding.

## Connecting workers

Workers connect over NATS, not HTTP, using `NatsNetwork` — which ships inside the main SDKs rather than as a separate package.

### TypeScript

Requires `@resonatehq/sdk` and the `@nats-io/transport-node` peer dependency.

```typescript title="worker.ts"
import { Resonate } from "@resonatehq/sdk";
import { NatsNetwork } from "@resonatehq/sdk/nats";
import { connect } from "@nats-io/transport-node";

const conn = await connect({ servers: "nats://localhost:4222" });

const resonate = new Resonate({
  network: new NatsNetwork({ conn }),
});
```

### Python

Requires the `nats` extra, which pulls in `nats-py`:

```shell
uv add "resonate-sdk[nats]"
```

```python title="worker.py"
import asyncio

import nats
from resonate.resonate import Resonate
from resonate.network.nats import NatsNetwork


async def main():
    conn = await nats.connect("nats://localhost:4222")
    resonate = Resonate(network=NatsNetwork(conn))
    ...


asyncio.run(main())
```

`Resonate` is imported from `resonate.resonate`, not the package root, and it has to be constructed inside a running event loop — its `__init__` schedules background tasks.


In the Python SDK, network selection resolves `url` before `network` before the `RESONATE_URL` environment variable. If you pass a `url` **and** a `network`, the URL wins and your `NatsNetwork` is silently ignored. Pass one or the other.


### Other languages

`NatsNetwork` exists in the TypeScript and Python SDKs only. The Go, Rust, and Java SDKs have no NATS support, so a team on those languages can't use this provider today.

## Subjects and addressing

Worth knowing if you run a NATS deployment with subject-level permissions.

- Requests go to `resonate.requests.{base64url(origin)}`, where the encoding is unpadded base64url. The request carries a `Resonate-Reply-To` header naming a private inbox, and the reply comes back on that inbox — the server ignores the NATS reply subject.
- Workers receive on two subjects: a unicast `resonate.recv.{group}.{pid}` and an anycast `resonate.recv.{group}`, queue-subscribed on the group so exactly one member gets each anycast message.
- Task addresses use the `nats://` scheme; the server maps `nats://{subject}` back to a subject.

Both prefixes are configurable per client (`serverTopic` / `server_topic` and `workerTopic` / `worker_topic`), and the request timeout defaults to 30 seconds.


Subjects are case-sensitive end to end, and nothing normalizes case for you, so a publisher and a subscriber that disagree on capitalization will not find each other. Default pids are lowercase hex, so staying lowercase keeps hand-set values consistent with them.


## What's not there yet

- **No production reference deployments.** Nobody is running this in production yet.
- **No search.** Neither `promise.search` nor `task.search` is a recognized kind, so both come back as `400 bad request`. Unlike the ScyllaDB provider there is no `501` stub to probe for. Anything that depends on querying promises by tag will not work.
- **Lighter test coverage than the ScyllaDB provider.** There are unit tests over the store, schedules, and tasks, but no oracle-diff, crash, or linearizability suites of the kind [that provider ships](/deploy/providers/scylladb#how-its-tested).
- **No authentication.** The server has no auth layer of its own. Anything protecting it has to come from your NATS deployment — accounts, users, and subject permissions.
- **No HTTP interface.** There is no REST surface, no health endpoint, and no way to point an HTTP-based SDK client at it.
- **TypeScript and Python only.** `NatsNetwork` ships in those two SDKs. The Go, Rust, and Java SDKs have no NATS client, so a team on those languages cannot use this provider today.
- **The layout is not settled.** This is a young repository, and the subject scheme and partition model can still change. Check open pull requests before you build tooling against them.
- **Source-available under BUSL-1.1, not Apache 2.0.** All non-production use is free, including modifying and redistributing. There is no additional production use grant, so production use requires a commercial license from Resonate HQ until the Change Date (2030-07-01), when each released version converts to Apache 2.0. Contact `licensing@resonatehq.io`.

## See also

- [Server providers](/deploy/providers) — what a provider is and what else ships
- [Resonate on ScyllaDB](/deploy/providers/scylladb) — the drop-in provider
- [Resonate on Postgres](/deploy/providers/postgres) — the in-database provider
- [Durable Execution on NATS](https://www.resonatehq.io/providers/nats) — the overview page
- [resonatehq/resonate-on-nats](https://github.com/resonatehq/resonate-on-nats) — the source
- [resonatehq/nats-demos](https://github.com/resonatehq/nats-demos) — runnable TypeScript and Python examples

---

---
url: https://docs.resonatehq.io/deploy/providers/postgres
title: Resonate on Postgres
---

## TL;DR

[`resonate-pg`](https://github.com/resonatehq/resonate-pg) implements the Resonate protocol as a schema of stored procedures. You load one SQL file into a Postgres 16+ database and the database becomes the server: storage, queue, and timer, with `pg_cron` driving all three. There is no process to deploy, no port to expose, and no binary to keep running.

This is not the same thing as running the [core server](/deploy/run-server) on Postgres. There, you run a binary and Postgres is where it keeps its state. Here, there is no binary — the protocol *is* the database.

It is **not drop-in**, for the opposite reason the [NATS provider](/deploy/providers/nats) isn't. NATS has no HTTP interface because it replaced the transport; this has no HTTP interface because there is no server process to host one. Workers call `resonate.resonate_rpc()` over a database connection, which needs a client that speaks SQL. Only the TypeScript SDK has one today.

It is Apache 2.0, unlike the other two providers. It is also the youngest of the three — read [What's not there yet](#whats-not-there-yet) before you plan a production rollout.

## When to use it

Use it when you already run Postgres and want durable execution without deploying anything beside it. That is a real category: a Supabase project, a managed Postgres instance with no accompanying compute, a small service where one more process to operate is one too many.

If you are willing to run a process, run the [core server](/deploy/run-server) on Postgres instead. It is the reference implementation, it has the deepest production track record, and every SDK can talk to it. Reach for this provider when *no process* is the requirement, not when Postgres is.

If you are on Python, Go, Rust, or Java, this provider is not usable today — see [Connecting workers](#connecting-workers).

## Requirements

- **Postgres 16+.**
- **`pg_cron`** — required. It is the sole timer driver. Without it, timers never fire: durable sleeps never wake, task timeouts never expire, and nothing tells you at runtime.
- **`pg_net` or `pgsql_http`** — optional, and either one will do. These enable HTTP push delivery, which is how the database reaches out to your workers. Without one of them there is no push, and workers have to poll.

## Run it

Install the extensions, then apply the schema:

```shell
psql -d yourdb -c "create extension if not exists pg_cron; create extension if not exists pg_net;"
psql -d yourdb -f resonate.sql
```

Applying the file also schedules the timer job — it registers `resonate_process_timeouts` with `pg_cron` to run every five seconds.


If `pg_cron` isn't available, the install still succeeds. It raises a warning and leaves the timer unscheduled, which means promises are created and settled normally while every durable sleep hangs forever. Check for the `resonate: pg_cron enabled` notice in the install output, and confirm the job exists in `cron.job` before you trust a timer.

Scheduling also degrades quietly. The installer prefers `cron.schedule_in_database` at a five-second interval and falls back through plain `cron.schedule` to a once-a-minute schedule if the shorter interval is refused. A minute-granularity fallback still works, but timer resolution drops accordingly.


### Supabase quickstart

Supabase is the shortest path to a running instance, because both extensions are available and the whole install goes over the Management API with no connection string:

```shell
supabase projects create resonate-countdown
supabase link --project-ref <project-ref>
supabase db query --linked "create extension if not exists pg_cron; create extension if not exists pg_net;"
supabase db query --linked -f resonate.sql
```

Workers then run as Edge Functions. The repository's [`example/countdown`](https://github.com/resonatehq/resonate-pg/tree/main/example/countdown) goes from an empty project to a running durable workflow in about five minutes.

Supabase is a convenient host, not a boundary — `resonate-pg` is plain Postgres and runs anywhere Postgres 16+ and `pg_cron` do.

## Connecting workers

Workers do not point at a `RESONATE_URL`. They open a database connection and reach the protocol through a single function:

```sql
SELECT resonate.resonate_rpc('{"kind":"promise.get","head":{},"data":{"id":"invoke:foo"}}');
```

### TypeScript

The [`@resonatehq/supabase`](https://jsr.io/@resonatehq/supabase) package on JSR wraps `@resonatehq/sdk` with a `Network` implementation that speaks `resonate_rpc` over a Postgres connection, plus an HTTP handler for hosting the worker in an Edge Function. Despite the name it is a Postgres client, not a Supabase-only one.

```typescript
import { type Context, Resonate } from "jsr:@resonatehq/supabase@0.4.1";

const resonate = new Resonate();

resonate.register("countdown", async function countdown(ctx: Context, n: number) {
  // ... your workflow
});

resonate.httpHandler();
```

There is no URL to configure — the connection comes from the environment. The full worker is in [`example/countdown/index.ts`](https://github.com/resonatehq/resonate-pg/blob/main/example/countdown/index.ts).

The package is pre-1.0. Expect its surface to move.

### Other languages

There is no `resonate_rpc` client in the Python, Go, Rust, or Java SDKs, so teams on those languages cannot use this provider today. Each is tracked as an open issue on the repository.


`resonate-pg`'s README links all five Resonate SDKs under "SDK" without qualification. Only TypeScript has a client that can reach `resonate_rpc`. Treat that list as the SDKs Resonate publishes, not the SDKs this provider supports.


## Starting a workflow

Invocations start from SQL, and delivery is push-based — the database calls out to the address you give it:

```sql
SELECT resonate.invoke(
  'countdown-1',                                    -- promise id
  'countdown',                                      -- registered function name
  '[3]'::jsonb,                                     -- arguments
  'https://<project-ref>.functions.supabase.co/countdown');  -- worker address
```

The last two parameters, `version` and `timeout`, default to `1` and **24 hours from now**. A workflow still running when its timeout lands is timed out, so pass an explicit `timeout` for anything long-lived — a multi-day sleep will otherwise expire mid-run.

Push delivery goes through `pg_net`'s `net.http_post` where available, falling back to `pgsql_http`. A failed push is logged as a warning rather than raised, so the workflow does not fail — but a persistently unreachable worker shows up in the Postgres log, not in your application.

## How state is stored

Seven tables in a `resonate` schema: `promises`, `tasks`, `task_resumes`, `callbacks`, `listeners`, `schedules`, and `outbox`. Every protocol action is a stored procedure over them, dispatched by kind through `resonate.resonate_rpc()`.

The outbox is the delivery queue. `pg_cron` calls `resonate.process_timeouts()` on its schedule, which expires what is due and enqueues what is now runnable; a trigger on the outbox performs the HTTP push.

Search is implemented — `promise.search`, `task.search`, and `schedule.search` all return results rather than an error, which is not true of the other two providers.

## Access control

Authentication is Postgres's, not the server's, and the schema is set up for that rather than left open. The install revokes all table, sequence, and function privileges from `PUBLIC`, creates a `resonate_worker` role, and grants it usage on the schema plus execute on the six functions a worker actually needs. `resonate_rpc` and the two dequeue functions are `SECURITY DEFINER`, and every function in the schema has its `search_path` pinned.

Give workers the `resonate_worker` role rather than a superuser connection. Anyone who can execute `resonate_rpc` can drive the whole protocol, so the database connection is the security boundary.

## How it's tested

`resonate-pg` has **no test suite in the repository**. What it ships is `test/conformance.py` — a shim that exposes `resonate_rpc` over HTTP so an external, model-based conformance harness can drive the database as if it were a Resonate server. Running it means standing up that harness separately.

That is materially less than either sibling: there are no unit tests of the kind the NATS provider has, and none of the oracle-diff, crash, or linearizability suites [the ScyllaDB provider ships](/deploy/providers/scylladb#how-its-tested).

## What's not there yet

- **Open correctness issues against task lifecycle.** The tracker carries several confirmed bugs in task leasing and settlement — a task that can be halted after it reports fulfilled, a lease claimed by `task.create` that `task.acquire` then refuses as timed out, timeout handlers redispatching workflows that are already finished, and a settlement cascade that can wake an awaiter whose own promise is already dead. Read the [open issues](https://github.com/resonatehq/resonate-pg/issues) before you commit to this provider.
- **No test suite in the repository.** See [How it's tested](#how-its-tested).
- **No production reference deployments.** Nobody is running this in production yet.
- **TypeScript only.** No other SDK has a client that can reach `resonate_rpc`.
- **The worker client is pre-1.0.** `@resonatehq/supabase` has not reached a stable release.
- **Timers depend entirely on `pg_cron`.** There is no in-database fallback. If the cron job is unscheduled, paused, or lost in a restore, durable sleeps stop waking and nothing surfaces the failure.
- **Retention is yours to run.** Completed workflows stay in the database until you delete them, and ids are idempotent only while their row exists — so a garbage-collection horizon shorter than your retry window turns a duplicate submission into a second execution. Schedule it deliberately:

  ```sql
  -- daily at 03:00: delete workflows finished more than 7 days ago
  select cron.schedule('resonate-gc', '0 3 * * *',
    $$select resonate.gc((extract(epoch from now())*1000 - 7*86400000)::bigint)$$);
  ```

- **No horizontal story beyond Postgres's own.** Throughput, connection limits, and failover are whatever your Postgres deployment provides. There is nothing to scale independently of the database.

## See also

- [Server providers](/deploy/providers) — what a provider is and what else ships
- [Run the core server](/deploy/run-server) — the reference implementation, including on Postgres
- [Resonate on NATS](/deploy/providers/nats) — the other non-drop-in provider
- [Resonate on ScyllaDB](/deploy/providers/scylladb) — the drop-in provider
- [Durable Execution on Postgres](https://www.resonatehq.io/providers/postgres) — the overview page
- [resonatehq/resonate-pg](https://github.com/resonatehq/resonate-pg) — the source

---

---
url: https://docs.resonatehq.io/deploy/providers/scylladb
title: Resonate on ScyllaDB
---

## TL;DR

[`resonate-on-scylladb`](https://github.com/resonatehq/resonate-on-scylladb) is a Go server that implements the Resonate protocol against ScyllaDB. It speaks the same HTTP/JSON protocol as the core server, so **your application code and SDK do not change** — you point `RESONATE_URL` at it.

It is source-available under BUSL-1.1, not Apache 2.0, and it is early. Read [What's not there yet](#whats-not-there-yet) before you plan a production rollout.

## When to use it

Use it when you already run ScyllaDB and would rather not stand up a second database for durable execution. If you don't already run ScyllaDB, run the [core server](/deploy/run-server) on Postgres instead — it is the reference implementation and the default recommendation.

## Requirements

- A ScyllaDB cluster reachable over CQL.
- Docker and Docker Compose for the local stack below.
- Go 1.25.4+ to build the binary from source.

## Run it locally

```shell title="Start the server against a local ScyllaDB"
git clone https://github.com/resonatehq/resonate-on-scylladb
cd resonate-on-scylladb
docker compose --profile server up
```


`docker compose up` on its own starts ScyllaDB and nothing else. The `server` service in the bundled `docker-compose.yaml` declares `profiles: [server]`, so you have to name the profile — or the service — to get a server.


The server listens on `:8001`. Point a worker at it exactly as you would the core server:

```shell
RESONATE_URL=http://localhost:8001
```

## Schema provisioning

This is the part to get right before you go anywhere near a cluster that matters.

The server only touches DDL when `--debug` (or `SERVER_DEBUG`) is set. In that mode it **drops the keyspace and recreates it** on every connect, then applies the tables. The bundled `server` service runs `serve --debug`, which is why the local stack above comes up with a working schema — and also why a local restart starts from empty.


Debug mode issues `DROP KEYSPACE IF EXISTS` before creating anything. Pointing a debug-mode server at a populated keyspace destroys it. Debug mode is for local development and the test suites only.


Outside debug mode the server applies no DDL at all — it opens a keyspace-bound session and assumes the schema is already there. So for any real deployment, **you provision the schema yourself**.

## Run against an existing cluster

Create the keyspace yourself, with a replication strategy you chose deliberately — leaving it to a default is rarely right on a multi-datacenter cluster. The bundled `internal/dbms/schema.cql` opens with a bare `CREATE KEYSPACE IF NOT EXISTS resonate;` and a `USE resonate;`, so do not apply it as-is unless both the name and the default replication are what you want:

```shell
cqlsh -e "CREATE KEYSPACE resonate WITH replication = {'class': 'NetworkTopologyStrategy', 'dc1': 3};"
```

Then apply the table definitions into it. The first three lines of the file are the `CREATE KEYSPACE` and `USE` you just replaced, so skip them:

```shell
tail -n +4 internal/dbms/schema.cql > tables.cql
cqlsh -k resonate -f tables.cql
```

Build the binary and start it pointed at the cluster, with debug off. The keyspace you provisioned has to match `SCYLLADB_KEYSPACE`:

```shell
go build -o resonate ./cmd/resonate

SCYLLADB_HOSTS=node-0.example.com,node-1.example.com,node-2.example.com \
SCYLLADB_KEYSPACE=resonate \
SCYLLADB_TLS_ENABLED=true \
./resonate serve
```


The provider's CLI is also called `resonate`, and it also takes `serve` — but it is built from `resonatehq/resonate-on-scylladb`, not from the core server repository. Make sure the binary on your `PATH` is the one you meant.


`SCYLLADB_REPLICATION` is only read when the server creates the keyspace, which means only in debug mode. Since you provision the keyspace yourself, that setting does nothing on this path.

## Configuration

Configuration resolves in priority order: CLI flags, then environment variables, then an optional `resonate.yaml`, then built-in defaults.

| Variable | Description |
|---|---|
| `SERVER_ADDR` | Server listen address (default `:8001`) |
| `SERVER_DEBUG` | Debug mode — **drops and recreates the keyspace on connect**; never enable against real data |
| `SERVER_LOG_LEVEL` | `debug`, `info`, `warn`, or `error` (default `info`); any other value is a fatal startup error |
| `SCYLLADB_HOSTS` | Comma-separated seed hosts |
| `SCYLLADB_PORT` | CQL port |
| `SCYLLADB_USERNAME` | Username |
| `SCYLLADB_PASSWORD` | Password |
| `SCYLLADB_TLS_ENABLED` | Enable TLS |
| `SCYLLADB_TLS_INSECURE` | Skip certificate verification |
| `SCYLLADB_KEYSPACE` | Keyspace name |
| `SCYLLADB_REPLICATION` | Replication clause used when creating the keyspace — debug mode only |
| `TIMEOUTS_BUCKET_WIDTH` | Timeout bucket width (e.g. `1h`, `30m`) |
| `TIMEOUTS_BUCKET_LOOKBACK` | Past buckets to scan |
| `TIMEOUTS_SHARDS` | Shard count for the timeout tables — must match across all server instances |
| `WORKER_TTL` | Worker row TTL (e.g. `15s`) |
| `WORKER_TICK_INTERVAL` | Coordinator tick interval (e.g. `1s`) |

The equivalent `resonate.yaml` keys are nested under `server:`, `scylladb:`, `timeouts:`, and `worker:`.

## How state is stored

The schema has six tables.

- **`promises`** — one row per durable promise, keyed `PRIMARY KEY (origin, id)`. State fans out across many small partitions rather than concentrating into a fixed few.
- **Task state lives on the promise row.** The `task_*` columns sit in `promises`, so acquiring, fencing, or completing a task is a single-row operation.
- **`promise_timeouts`, `task_timeouts`, `schedule_timeouts`** — keyed `PRIMARY KEY ((bucket, shard), timeout_at, …)`. Durable timers are bucketed by time and sharded, so an expiry scan is a clustering-key range read inside one partition.
- **`schedules`** — recurring schedules, keyed the same way as promises.
- **`workers`** — worker liveness, with a row TTL set by `WORKER_TTL`.

There is no per-execution event log. State is the current row, not a sequence to replay, so nothing accumulates without bound and a long-running execution has no history-size ceiling.

`TIMEOUTS_SHARDS` sets how many partitions the timeout scan spreads across. `TIMEOUTS_BUCKET_WIDTH` and `TIMEOUTS_BUCKET_LOOKBACK` together decide how much of the recent past each tick re-scans.


The shard is a hash of the record id, baked into the partition key of every timeout row. Every instance must use the same value, and changing it on a populated cluster strands existing rows in partitions no server scans — durable timers stop firing, silently.


## How it's tested

The repository ships three test suites, all runnable from a clone under Docker Compose:

```shell title="Diff tests — every step checked against an in-memory oracle"
docker compose -f docker-compose.test.yml -p resonate-diff --profile diff \
  up --build --abort-on-container-exit --exit-code-from tester-diff
```

```shell title="Kill tests — crash mid-transaction, assert invariants on what survives"
docker compose -f docker-compose.test.yml -p resonate-kill --profile kill \
  up --build --abort-on-container-exit --exit-code-from tester-kill
```

```shell title="Linearizability — concurrent interleavings, model-checked"
docker compose -f docker-compose.test.yml -p resonate-linz --profile linearizability \
  up --build --abort-on-container-exit --exit-code-from tester-linearizability
```

The kill tests abort an operation at every cooperative yield checkpoint — reads, cursor scans, non-transactional pre-inserts, lightweight-transaction commits, rollbacks, cleanups and batches — a thousand iterations by default, and check named state invariants on whatever is left. Nine of those invariants describe *accepted* orphans: states that are harmless after an abort, because the recovery design writes a timeout entry before the transaction that commits the state change. An abort in that gap leaves a stale entry to be cleaned up rather than losing state.

Linearizability is checked with the [Porcupine](https://github.com/anishathalye/porcupine) model checker against the same oracle the diff tests use.

## What's not there yet

Read this section before you plan a production rollout.

- **No production reference deployments.** Nobody is running this in production yet.
- **Search is unimplemented.** `task.search` returns `501`. `promise.search` and `schedule.search` aren't recognized kinds at all, so they come back as `400` with `unknown kind: <kind>` rather than `501` — worth knowing if you plan to probe for capability. Anything that depends on querying promises by tag will not work.
- **No authentication.** An auth hook exists in the code, but nothing wires it up and its check is an unimplemented stub, so every request reaching the server is served. Put it behind your own network controls.
- **Behavior under database-layer failure is an open question.** A repair path exists in the code but is not wired into the running server, so a lost node or a partition is not something the current tests characterize.
- **Known bug:** deleting a schedule can leave stale rows in `schedule_timeouts`.
- **The schema is not settled.** This is a young repository. Check open pull requests before you build tooling against the column layout above.
- **Source-available under BUSL-1.1, not Apache 2.0.** All non-production use is free, including modifying and redistributing. There is no additional production use grant, so production use requires a commercial license from Resonate HQ until the Change Date (2030-07-01), when each released version converts to Apache 2.0. Contact `licensing@resonatehq.io`.

## See also

- [Server providers](/deploy/providers) — what a provider is and what else ships
- [Resonate on NATS](/deploy/providers/nats) — the provider that replaces the transport
- [Resonate on Postgres](/deploy/providers/postgres) — the in-database provider
- [Durable Execution on ScyllaDB](https://www.resonatehq.io/providers/scylladb) — the overview page
- [resonatehq/resonate-on-scylladb](https://github.com/resonatehq/resonate-on-scylladb) — the source

---

---
url: https://docs.resonatehq.io/deploy/railway
title: Deploy to Railway
---

This page walks through deploying the Resonate server to [Railway](https://railway.com) using the official Docker image and Railway's managed Postgres database.

## Prerequisites

- A Railway account with a project created
- The Resonate server Docker image: [`resonatehqio/resonate`](https://hub.docker.com/r/resonatehqio/resonate)

## Overview

You will create two services in one Railway environment:

1. **Postgres** — Railway's managed Postgres database, provisioned directly from the project canvas
2. **resonate-server** — the Resonate server, deployed from the official Docker Hub image

Workers run separately (in your own services or elsewhere) and connect to the Resonate server over Railway's private network or via its public URL.

## Step 1 — Add a Postgres database

From your Railway project canvas, click **+ New** and choose **Database > Postgres**. Railway provisions the database and immediately exposes connection variables, including `DATABASE_URL`, on the Postgres service.

No additional configuration is required. The database is ready to accept connections once the provisioning step completes.

## Step 2 — Add the Resonate server service

From the project canvas, click **+ New** and choose **Docker Image**. Enter the image path:

```
resonatehqio/resonate:v0.9.8
```

Railway pulls the image from Docker Hub. The service is created in a stopped state — you configure environment variables before the first deploy in the next step.


Tags track server release versions (e.g. `v0.9.8`) plus a rolling `latest`. Pin to a version tag in production so redeployments are predictable.


## Step 3 — Configure environment variables

Open the Resonate server service, go to **Variables**, and add the following:

```shell title="Environment variables"
# Tell Railway which port to route external traffic to.
# Without this, Railway may pick the metrics port (9090) and return 502 errors.
PORT=8001

# Use Railway's managed Postgres as the storage backend.
RESONATE_STORAGE__TYPE=postgres
RESONATE_STORAGE__POSTGRES__URL=${{Postgres.DATABASE_URL}}

# Set the externally-reachable URL so task dispatch headers are correct.
# Fill this in after generating a public domain in Step 4.
RESONATE_SERVER__URL=https://<your-railway-domain>

# Lower the task retry interval for chained workflows.
# The 30-second default adds significant latency to multi-step executions.
RESONATE_TASKS__RETRY_TIMEOUT=500
```

The `${{Postgres.DATABASE_URL}}` syntax is Railway's [service variable reference](https://docs.railway.com/guides/variables). Replace `Postgres` with the exact name of your Postgres service if you renamed it.


The Resonate server listens on two ports: `8001` (HTTP API) and `9090` (Prometheus metrics).
Railway's port detection picks one port to route public traffic to. Setting `PORT=8001` tells Railway to route to the API port.
Without this, Railway may route to `9090` and all API requests will receive unexpected responses.


## Step 4 — Generate a public domain and configure health checks

In the Resonate server service settings:

1. Under **Networking > Public Networking**, click **Generate Domain**. Copy the generated URL.
2. Go back to **Variables** and set `RESONATE_SERVER__URL` to the generated URL (e.g. `https://resonate-server-production.up.railway.app`).
3. Under **Health Checks**, set the **Path** to `/health`. The server also exposes `/ready`, which returns `503` when Postgres is not reachable — useful for readiness gating, though Railway's health check mechanism uses a single path. See [Run server > Health and readiness](/deploy/run-server#health-and-readiness) for the full endpoint spec.

## Step 5 — Deploy

Trigger a deploy. Railway pulls `resonatehqio/resonate:v0.9.8`, starts the container, and runs the health check against `/health` on port `8001`. Postgres migrations are applied automatically on first startup — no manual migration step is required.

Once the deploy reports healthy, confirm the server is up:

```shell title="Verify the deployment"
curl -s -o /dev/null -w "%{http_code}\n" https://<your-railway-domain>/health
# 200
```

## Connecting workers

Workers running inside the same Railway environment can reach the Resonate server over Railway's private network using the internal DNS hostname:

```
http://resonate-server.railway.internal:8001
```

Replace `resonate-server` with the exact name of your Railway service if you renamed it. Private networking is zero-configuration — no additional setup is needed for services in the same project environment.

Workers running outside Railway (or in a different Railway environment) use the public domain generated in Step 4.

Configure your worker SDK to point at the server URL. Example for TypeScript:

```typescript
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: process.env.RESONATE_URL, // set to the internal or public server URL
  group: "workers",
});
```

Set the `RESONATE_URL` environment variable on your worker service to:
- `http://resonate-server.railway.internal:8001` — for workers in the same Railway environment
- `https://<your-railway-domain>` — for workers outside Railway

## Environment variable reference

Full variable reference: [Run a server > Environment variables](/deploy/run-server#environment-variables). The two Railway-specific pieces — `PORT` (tells Railway which port to route external traffic to; not a Resonate variable) and the `${{Postgres.DATABASE_URL}}` service variable reference — are shown in Step 3 above.

---

---
url: https://docs.resonatehq.io/deploy/run-server
title: Run a server
---

This page will help you install and run the Resonate Server.

First install the Server on your machine.

## Install with Homebrew

You can install the latest Resonate Server version with Homebrew via:

```shell
brew install resonatehq/tap/resonate
```

All available releases and associated release artifacts are available on [Github](https://github.com/resonatehq/resonate/releases).

Once installed, you can start the server with an in-memory store by running:

```shell title="Run using an in-memory store"
resonate dev
```

Or, you can run the server with the default SQLite store by running:

```shell title="Run using the default SQLite store"
resonate serve
```

You will see log output like the following:

```
INFO resonate: Resonate Server starting port=8001
INFO resonate: Using SQLite backend path="resonate.db"
INFO resonate: Auth disabled — all requests accepted
```

The HTTP API is on port `8001` and the Prometheus metrics endpoint is on port `9090`.
Both default ports can be changed.

## Run with Docker

The Resonate Server is published as an official image on Docker Hub at [`resonatehqio/resonate`](https://hub.docker.com/r/resonatehqio/resonate).
Tags track the server release versions (e.g. `v0.9.8`) plus a rolling `latest`.

```shell title="Run the Resonate Server in Docker"
docker run --rm -p 8001:8001 -p 9090:9090 resonatehqio/resonate:v0.9.8
```

`resonate serve` is the default command. Override only when you need to change behavior:

```shell title="Use Postgres storage"
docker run --rm -p 8001:8001 -p 9090:9090 \
  -e RESONATE_STORAGE__TYPE=postgres \
  -e RESONATE_STORAGE__POSTGRES__URL="postgres://<USER>:<PASSWORD>@host:5432/resonate" \
  resonatehqio/resonate:v0.9.8
```

The image exposes both `8001` (HTTP API) and `9090` (Prometheus metrics).

## Configuration

The server is configured by layering, in this order — each layer overrides the previous:

1. Built-in defaults
2. `resonate.toml` (optional, looked up in the working directory)
3. Environment variables prefixed with `RESONATE_` using `__` to nest
4. CLI flags passed to `resonate serve`

The recommended approach for any non-trivial deployment is a `resonate.toml` file checked into your infra repo, with secrets injected via environment variables.

### `resonate.toml`

```toml title="resonate.toml"
level = "info"

[server]
host = "localhost"
port = 8001

[storage]
type = "sqlite"

[storage.sqlite]
path = "resonate.db"

[tasks]
lease_timeout = 15000
retry_timeout = 30000
```

For Postgres, swap the `[storage]` section:

```toml title="resonate.toml — Postgres"
[storage]
type = "postgres"

[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@host:5432/resonate"
pool_size = 20
```

For MySQL, the equivalent block is:

```toml title="resonate.toml — MySQL"
[storage]
type = "mysql"

[storage.mysql]
url = "mysql://<USER>:<PASSWORD>@host:3306/resonate"
pool_size = 20
```

To enable JWT auth, add an `[auth]` section:

```toml title="resonate.toml — auth enabled"
[auth]
publickey = "/etc/resonate/auth/public.pem"
```

### Environment variables

Every config field is also reachable as an environment variable. The convention is `RESONATE_<SECTION>__<FIELD>`, with `__` separating nested keys:

```shell
RESONATE_LEVEL=info
RESONATE_SERVER__PORT=8001
RESONATE_STORAGE__TYPE=postgres
RESONATE_STORAGE__POSTGRES__URL=postgres://<USER>:<PASSWORD>@host:5432/resonate
RESONATE_AUTH__PUBLICKEY=/etc/resonate/auth/public.pem
```

This is the form used in the [official Docker Compose file](https://github.com/resonatehq/resonate/blob/main/docker-compose.yml) and is the right choice for container platforms that prefer env-var injection.

### CLI flags

For the full client + server CLI surface (subcommands, scenarios, worked examples), see [CLI reference](/reference/cli). The table below covers the operator flags most commonly needed when running `resonate serve`.

Most settings can also be passed as CLI flags — useful for ad-hoc overrides:

```shell
resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate" \
  --storage-postgres-pool-size 20
```

Run `resonate serve --help` for the full list. Common flags:

| Flag | Default | Description |
|------|---------|-------------|
| `--server-host` | `localhost` | HTTP server host |
| `--server-port` | `8001` | HTTP server port |
| `--server-bind` | `0.0.0.0` | Bind address |
| `--server-url` | `http://{host}:{port}` | Externally-reachable URL (required for distributed deployments where workers call back to the server) |
| `--level` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `--storage-type` | `sqlite` | Storage backend: `sqlite`, `postgres`, or `mysql` |
| `--storage-postgres-url` | — | Postgres connection string |
| `--storage-postgres-pool-size` | `10` | Postgres connection pool size |
| `--storage-mysql-url` | — | MySQL connection string |
| `--storage-mysql-pool-size` | `10` | MySQL connection pool size |
| `--auth-publickey` | — | Path to JWT public key (PEM format) for authentication |
| `--server-cors-allow-origin` | — | Allowed CORS origin (repeatable; use `*` for permissive). See [Security › CORS](/deploy/security#cors-cross-origin-resource-sharing) |
| `--tasks-lease-timeout` | `15000` (ms) | Task lease timeout |
| `--tasks-retry-timeout` | `30000` (ms) | Suspend/wake retry interval. Lower values (e.g. `500`) significantly reduce latency for chained or recursive workflows |
| `--observability-metrics-port` | `9090` | Prometheus metrics port (`0` to disable) |


The default `--tasks-retry-timeout` of 30 seconds adds significant latency to chained workflows (sagas, recursive fan-out).
For most deployments, set this to `500` (milliseconds) to keep suspend/wake cycles fast.


#### Transport flags

v0.9.5 added explicit enable/disable flags for every transport so operators can shape which delivery paths are live per deployment. See [Message transports](/deploy/message-transports) for the per-transport behaviour.

| Flag | Default | Description |
|------|---------|-------------|
| `--transports-http-push-enabled` | `true` | Enable the `http://` / `https://` push transport |
| `--transports-http-poll-enabled` | `true` | Enable the SSE poll transport used by long-polling SDK clients |
| `--transports-gcps-enabled` | `false` | Enable the `gcps://` GCP Pub/Sub transport |
| `--transports-gcps-project` | — | Default GCP project ID for the Pub/Sub transport |
| `--transports-bash-exec-enabled` | `false` | Enable the `bash:///` local-script transport (see [Bash exec](/deploy/message-transports#bash-exec)) |

#### Outbound HTTP push authentication flags

v0.9.5 added outbound authentication for HTTP push deliveries so workers behind authenticated endpoints (for example GCP Cloud Run with `--no-allow-unauthenticated`) can verify the server's identity. See [Outbound HTTP push authentication](/deploy/security#outbound-http-push-authentication) for the full configuration guide.

| Flag | Default | Description |
|------|---------|-------------|
| `--transports-http-push-auth-mode` | `none` | Outbound auth mode: `none`, `bearer`, or `gcp` |
| `--transports-http-push-auth-token` | — | Static bearer token (used only when `mode = bearer`) |
| `--transports-http-push-auth-aud` | delivery target URL | Fixed OIDC audience (used only when `mode = gcp`; defaults to the per-delivery target URL) |
| `--transports-http-push-auth-header` | `Authorization` | Name of the request header that carries the token |

## Run with PostgreSQL

For production deployments, use PostgreSQL as the storage backend.

With a `resonate.toml` (recommended):

```toml title="resonate.toml"
[storage]
type = "postgres"

[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
pool_size = 20
```

Or with CLI flags:

```shell
resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate" \
  --storage-postgres-pool-size 20
```

Migrations are applied automatically on first startup.

See the [Availability](/deploy/availability) guide for high-availability PostgreSQL configuration.

## Run with MySQL

MySQL is a third storage option alongside SQLite and PostgreSQL. Use it when your operational tooling already centers on MySQL.

With a `resonate.toml` (recommended):

```toml title="resonate.toml"
[storage]
type = "mysql"

[storage.mysql]
url = "mysql://<USER>:<PASSWORD>@localhost:3306/resonate"
pool_size = 20
```

Or with CLI flags:

```shell
resonate serve \
  --storage-type mysql \
  --storage-mysql-url "mysql://<USER>:<PASSWORD>@localhost:3306/resonate" \
  --storage-mysql-pool-size 20
```

Or with environment variables:

```shell
RESONATE_STORAGE__TYPE=mysql
RESONATE_STORAGE__MYSQL__URL=mysql://<USER>:<PASSWORD>@localhost:3306/resonate
RESONATE_STORAGE__MYSQL__POOL_SIZE=20
```

Migrations are applied automatically on first startup. MySQL 8.0 or later is required (the schema relies on generated columns and JSON path expressions).

A minimal Docker Compose stack that boots the server against a MySQL service:

```yaml title="docker-compose.yml — MySQL"
services:
  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    ports:
      - "8001:8001"
      - "9090:9090"
    environment:
      RESONATE_SERVER__BIND: "0.0.0.0"
      RESONATE_STORAGE__TYPE: mysql
      RESONATE_STORAGE__MYSQL__URL: mysql://resonate:resonate@mysql:3306/resonate
      RESONATE_STORAGE__MYSQL__POOL_SIZE: 20
    depends_on:
      mysql:
        condition: service_healthy

  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: resonate
      MYSQL_USER: resonate
      MYSQL_PASSWORD: resonate
      MYSQL_DATABASE: resonate
    ports:
      - "3306:3306"
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "resonate", "-presonate"]
      interval: 5s
      timeout: 5s
      retries: 10
```


The MySQL schema stores promise IDs, task IDs, listener addresses, and a few derived tag values (`resonate:target`, `resonate:origin`, `resonate:branch`) as `VARCHAR(255)`.
Inputs that exceed 255 characters fail with a `400 InvalidInput` response. SQLite and Postgres do not enforce this bound, so applications written against those backends should verify ID lengths before switching to MySQL.


## Deploy to GCP Cloud Run

Cloud Run can pull the official image directly:

```shell
gcloud run deploy resonate-server \
  --image=resonatehqio/resonate:v0.9.8 \
  --region=<your-region> \
  --port=8001 \
  --allow-unauthenticated \
  --max-instances=1
```

Set the `--server-url` flag in the container args (or `RESONATE_SERVER__URL` env var) to your service URL after the first deploy so workers can call back correctly. For Postgres, set `RESONATE_STORAGE__TYPE=postgres` and `RESONATE_STORAGE__POSTGRES__URL`.

For a worked end-to-end example, see [Cloud Run workers](/get-started/examples/durable-serverless-cloud-run-workers).

## Run on Kubernetes

The recommended Kubernetes deployment is a single-replica Deployment that pulls the official image:

```yaml
---
apiVersion: v1
kind: Service
metadata:
  name: resonate
spec:
  selector:
    app: resonate
  ports:
    - port: 8001
      name: api
    - port: 9090
      name: metrics
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: resonate
spec:
  replicas: 1
  selector:
    matchLabels:
      app: resonate
  template:
    metadata:
      labels:
        app: resonate
    spec:
      containers:
        - name: resonate
          image: resonatehqio/resonate:v0.9.8
          env:
            - name: RESONATE_SERVER__BIND
              value: "0.0.0.0"
            - name: RESONATE_STORAGE__TYPE
              value: "postgres"
            - name: RESONATE_STORAGE__POSTGRES__URL
              valueFrom:
                secretKeyRef:
                  name: resonate-secrets
                  key: database-url
            - name: RESONATE_TASKS__RETRY_TIMEOUT
              value: "500"
          ports:
            - name: api
              containerPort: 8001
            - name: metrics
              containerPort: 9090
          livenessProbe:
            httpGet:
              path: /health
              port: 8001
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /ready
              port: 8001
            initialDelaySeconds: 5
            periodSeconds: 5
```

Create a file named `resonate-k8s.yaml` and apply the manifest:

```console
kubectl apply -f resonate-k8s.yaml
```

To remove Resonate from your cluster:

```console
kubectl delete -f resonate-k8s.yaml
```

## Health and readiness

The server exposes two HTTP endpoints for liveness and readiness checks:

| Endpoint | Returns | Use for |
|----------|---------|---------|
| `GET /health` | `200 OK` always (as long as the process is up) | Liveness probes |
| `GET /ready` | `200 OK` if storage is reachable, `503` otherwise | Readiness probes |

```shell title="Quick health check"
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/health
# 200
```

## Build from source

If you don't have Homebrew, you can build the server from source. The server is written in Rust:

```shell
git clone https://github.com/resonatehq/resonate
cd resonate
cargo build --release
./target/release/resonate serve
```

## Defaults

The most commonly referenced server defaults:

- **HTTP API port** — `8001` (`--server-port`)
- **Bind address** — `0.0.0.0` (`--server-bind`); host advertised as `localhost`
- **Storage backend** — `sqlite` at `resonate.db`
- **`--tasks-lease-timeout`** — `15_000 ms`
- **`--tasks-retry-timeout`** — `30_000 ms` (lower to `500 ms` for chained / recursive workflows)
- **Prometheus metrics port** — `9090` (`0` disables)
- **Log level** — `info`
- **Postgres / MySQL pool size** — `10`
- **`--transports-http-push-enabled` / `--transports-http-poll-enabled`** — `true`
- **`--transports-gcps-enabled` / `--transports-bash-exec-enabled`** — `false`

These mirror the operator surface above; the canonical cross-component reference (including SDK init, `ctx.run`, retry policy, and env-var defaults) is the [Defaults reference](/reference/defaults).

## Ports

The server binds two ports by default:

| Port | Purpose |
|------|---------|
| `:8001` | HTTP API (all SDK traffic, SSE polling, and task dispatch) |
| `:9090` | Prometheus metrics |


On platforms like Railway, Render, or Fly.io that auto-detect a single primary port, explicitly route to `8001`.
Without this, the platform may pick the metrics port (`9090`) and route all traffic there, resulting in 502 errors.

---

---
url: https://docs.resonatehq.io/deploy/scaling
title: Scaling
---

Worker scaling is the primary way to handle increased load in Resonate. Since workers execute your application code, adding more workers directly increases your system's execution capacity.

## How worker scaling works

Workers register with the Resonate server using a **group name**. All workers in the same group can handle the same tasks, and Resonate automatically distributes work across available workers.

### Worker registration

```typescript title="TypeScript worker registration"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://resonate-server:8001",
  group: "workers", // All workers in this group can handle the same tasks
});
```

```python title="Python worker registration"
from resonate import Resonate

resonate = Resonate.remote(
    host="http://resonate-server",
    store_port="8001",
    message_source_port="8001",
    group="workers",  # All workers in this group can handle the same tasks
)
```

### Task distribution

When you invoke a function targeting a worker group, Resonate distributes work across any available worker in that group:

```typescript title="Targeting a worker group"
// This task goes to ANY available worker in the "workers" group
resonate.rpc(
  taskId,
  "processOrder",
  { orderId: "123" },
  resonate.options({
    target: "poll://any@workers",
  })
);
```

The server automatically load-balances across workers. You don't need to implement distribution logic.

## Worker concurrency

A single worker process handles multiple tasks concurrently.
When the server dispatches a task to a worker, the worker begins executing it immediately — it does not wait for prior tasks to finish first.
Understanding this behavior is important for designing your application, especially when workers hold in-process state.

### TypeScript

The TypeScript SDK runs on the Node.js event loop.
All incoming tasks are processed concurrently via `async/await` — each task progresses independently whenever it hits an `await` point.
There is no built-in concurrency limit.

```typescript title="Default: unlimited concurrent tasks"
const resonate = new Resonate({
  url: "http://resonate-server:8001",
  group: "workers",
  // No concurrency config — all tasks run concurrently on the event loop
});
```

This means a single TypeScript worker can handle many tasks at once, which is efficient for I/O-bound work (HTTP calls, database queries, file reads).
CPU-intensive tasks will block the event loop and starve other in-flight tasks — offload heavy computation to worker threads or separate processes.

### Python

The Python SDK uses a thread pool to execute functions concurrently.
The pool size is controlled by the `workers` parameter:

```python title="Configure thread pool size"
from resonate import Resonate

# Default: min(32, os.cpu_count()) threads
resonate = Resonate.remote(
    host="http://resonate-server",
    store_port="8001",
    message_source_port="8001",
)

# Explicit: limit to 4 concurrent function executions
resonate = Resonate.remote(
    host="http://resonate-server",
    store_port="8001",
    message_source_port="8001",
    workers=4,
)
```

The default is `min(32, os.cpu_count())` — on a 4-core machine that's 4 threads, on a 16-core machine it's 16, with a hard cap at 32.
Each thread executes one function at a time, so `workers=4` means up to 4 functions run in parallel within that single process.

### When concurrency matters

For most applications, per-worker concurrency is beneficial — it keeps the worker busy while individual tasks wait on I/O.

However, if your worker holds **in-process state** that cannot be shared across tasks (for example, a browser automation session, a stateful protocol connection, or a GPU context), concurrent tasks will interfere with each other.

**Strategies for stateful workers:**

1. **Scale horizontally instead.** Run multiple single-purpose worker processes, each handling one task at a time. Resonate's load balancing distributes tasks across them automatically.
2. **In Python, set `workers=1`** to limit the thread pool to a single thread. This ensures only one function executes at a time within the process.
3. **Design for isolation.** If tasks can each create their own isolated state (for example, each task launches its own browser context), concurrency is safe.

```python title="Single-threaded worker for stateful workloads"
from resonate import Resonate

# Only one function runs at a time in this process
resonate = Resonate.remote(
    host="http://resonate-server",
    store_port="8001",
    message_source_port="8001",
    workers=1,
)
```

```bash title="Scale horizontally with multiple single-threaded workers"
# Each process handles one task at a time
# Resonate load-balances across all of them
python worker.py &
python worker.py &
python worker.py &
python worker.py &
```

## When to scale workers

Scale workers horizontally when you observe:

- **High CPU usage** across worker processes (&gt;70% sustained)
- **Task queue buildup** (promises pending longer than expected)
- **Slow response times** for synchronous RPC calls
- **Memory pressure** (workers running out of RAM)

You can run as many workers as needed - there's no fixed limit. Start with 2-4 workers and scale based on observed load.

## Worker fault tolerance

If a worker crashes mid-task, Resonate automatically detects the failure (via heartbeat timeout) and reassigns the work to another available worker in the same group.

The new worker replays the function from the last checkpoint stored in the durable promise.

**This means:**
- Worker crashes don't lose in-flight work
- You can safely restart workers for deployments
- Load rebalances automatically when workers go down
- No manual intervention required for worker failures

## Scaling patterns

### Multiple processes

Run multiple worker processes on the same machine or across different machines:

```bash title="Start 4 worker processes"
# Terminal 1
node worker.js &

# Terminal 2
node worker.js &

# Terminal 3
node worker.js &

# Terminal 4
node worker.js &
```

All processes share the same worker group and receive tasks from the server.

### Docker containers

Scale workers using container orchestration:

```yaml title="docker-compose.yml"
version: '3.8'
services:
  resonate-server:
    image: resonatehqio/resonate:v0.9.8
    ports:
      - "8001:8001"
    environment:
      RESONATE_STORAGE__TYPE: postgres
      RESONATE_STORAGE__POSTGRES__URL: postgres://<USER>:<PASSWORD>@postgres:5432/resonate
    depends_on:
      - postgres

  worker:
    image: your-app:latest
    environment:
      RESONATE_URL: http://resonate-server:8001
    deploy:
      replicas: 5  # Scale to 5 workers
```

Adjust the `replicas` count to scale worker capacity.

### Kubernetes

Deploy workers as a Kubernetes Deployment with horizontal pod autoscaling:

```yaml title="worker-deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
  name: resonate-workers
spec:
  replicas: 10  # Scale to 10 workers
  selector:
    matchLabels:
      app: resonate-worker
  template:
    metadata:
      labels:
        app: resonate-worker
    spec:
      containers:
      - name: worker
        image: your-app:latest
        env:
        - name: RESONATE_URL
          value: "http://resonate-server:8001"
        resources:
          requests:
            cpu: "500m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "1Gi"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: resonate-workers-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: resonate-workers
  minReplicas: 5
  maxReplicas: 50
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70
```

The HPA automatically adjusts worker count based on CPU utilization.

### Serverless workers

Workers can run as serverless functions that wake up to claim tasks:

```typescript title="Cloud Run worker"
// Worker runs on Cloud Run, polls for tasks
const resonate = new Resonate({
  url: process.env.RESONATE_URL,
  group: "cloud-run-workers",
});

// Cloud Run container stays alive polling for work
// Scales to zero when idle, scales up under load
```

**Deploy to Cloud Run:**

```bash title="Deploy serverless worker"
gcloud run deploy resonate-worker \
  --image gcr.io/your-project/worker:latest \
  --set-env-vars RESONATE_URL=https://resonate.example.com \
  --min-instances 1 \
  --max-instances 100 \
  --cpu 1 \
  --memory 512Mi
```


Containerized workers are easier to debug and lower-cost at low scale. Move to serverless when you need auto-scaling or have highly variable load.


## Server scaling limitations

**The Resonate server does not currently support horizontal scaling across multiple server instances.**

A single server can coordinate thousands of workers and millions of promises because it coordinates work but doesn't execute your functions. The server is rarely a bottleneck.

**What this means:**
- You can run one server that coordinates many workers
- Workers scale horizontally (add as many as you need)
- Server scales vertically (add more CPU/RAM if needed)
- Message passing between multiple servers is not yet implemented

For most deployments, a modest server (2-4 CPUs, 4-8GB RAM) can coordinate hundreds of workers processing thousands of tasks per second.

If your workload exceeds single-server capacity, contact the Resonate team to discuss your use case.

## Monitoring worker scale

Track these metrics to know when to scale:

```text
# Task completion rate
rate(tasks_total{state="fulfilled"}[5m])

# Promise backlog
promises_total{state="pending"}

# Tasks acquired but not fulfilled (stalled tasks)
tasks_total{state="acquired"} - tasks_total{state="fulfilled"}

# Worker CPU usage (from your infrastructure metrics)
avg(container_cpu_usage_seconds_total{app="resonate-worker"})
```

**Note:** Worker health metrics (heartbeat failures, active worker count) are not exposed by Resonate server. Monitor workers at the infrastructure level:
- Kubernetes: `kubectl get pods -l app=resonate-worker`
- Docker: `docker ps | grep worker`
- Use infrastructure monitoring (Prometheus node exporter, Datadog, etc.) for worker health

See [Metrics](/deploy/metrics) for the full metrics catalog.

## Summary

**Worker scaling is how Resonate handles load:**
- Add more workers to increase execution capacity
- Workers automatically load-balance via server coordination
- Worker failures are handled transparently
- Server coordination scales vertically (not horizontally yet)

**Pattern:** Start small (2-4 workers), monitor load, scale horizontally as needed.

---

---
url: https://docs.resonatehq.io/deploy/security
title: Security
---

This page covers authentication options for securing your Resonate Server and SDK connections.

## Overview

Resonate uses **JWT token-based authentication** for securing server and SDK connections.

Authentication is **optional by default** but strongly recommended for production deployments.

## SDK Support Matrix

| Authentication Method | Server | TypeScript SDK | Rust SDK | Python SDK |
|-----------------------|--------|----------------|----------|------------|
| Token-based (JWT)     | ✅     | ✅             | ✅       | ❌ (planned) |


The Python SDK does not yet support token-based authentication. Token auth support is planned for a future release.
The Python SDK currently works with the legacy Resonate server only.


## Token-based authentication

Token-based authentication uses JWT bearer tokens signed with Ed25519 keys. The server validates tokens using a public key; clients sign tokens using the corresponding private key.

### Generate keys

Generate an Ed25519 key pair:

```bash title="Generate key pair"
openssl genpkey -algorithm Ed25519 -out private.pem
openssl pkey -in private.pem -pubout -out public.pem
```

### Server configuration

Start the server with the public key:

```bash title="Enable JWT auth"
resonate serve --auth-publickey public.pem
```

Or set it in `resonate.toml`:

```toml title="resonate.toml"
[auth]
publickey = "/etc/resonate/auth/public.pem"
# Optional: enforce expected claims
# iss = "your-issuer"
# aud = "your-audience"
```

When auth is enabled, all API requests must include a valid JWT token in the `Authorization: Bearer <token>` header.

### TypeScript SDK

```typescript title="index.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  token: process.env.RESONATE_TOKEN,
});
```

The SDK sends the token as a `Bearer` token in the `Authorization` header automatically.

#### Example: Secure production setup

```typescript title="resonate-client.ts"
import { Resonate } from "@resonatehq/sdk";

const token = process.env.RESONATE_TOKEN;

if (!token) {
  throw new Error("RESONATE_TOKEN environment variable is required");
}

const resonate = new Resonate({
  url: process.env.RESONATE_URL || "http://localhost:8001",
  token: token,
});

export default resonate;
```

### Rust SDK

```rust title="main.rs"
use resonate::prelude::*;

let resonate = Resonate::new(ResonateConfig {
    token: std::env::var("RESONATE_TOKEN").ok(),
    url: Some("http://localhost:8001".into()),
    ..Default::default()
});
```

`ResonateConfig::token` is `Option<String>`, so `std::env::var("RESONATE_TOKEN").ok()` is the idiomatic way to populate it from the environment. `Resonate::new` returns `Resonate` directly (not a `Result`).

## CORS (Cross-Origin Resource Sharing)

Browser-based clients — SDK applications running in a tab, internal dashboards, agent UIs — need CORS headers to call the Resonate Server from a different origin. CORS is **disabled by default**; the server only emits CORS headers when you configure one or more allowed origins.

### Why CORS matters

If your server is at `https://resonate.yourcompany.com` and your client runs at `https://app.example.com`, the browser will block the request unless the server returns the appropriate `Access-Control-Allow-Origin` headers. CORS configuration covers the HTTP API and the long-poll/SSE delivery endpoint together — both are served from the same router.

Server-to-server traffic (workers calling the API from a backend process) is not affected by CORS. Configure it only if a browser is in the request path.

### Server configuration

Configure allowed origins in `resonate.toml`:

```toml title="resonate.toml — CORS"
[server.cors]
allow_origins = ["https://app.example.com"]
```

Or via environment variable:

```bash title="Environment variable"
RESONATE_SERVER__CORS__ALLOW_ORIGINS=https://app.example.com
```

Or via repeatable CLI flag:

```bash title="CLI flags"
resonate serve \
  --server-cors-allow-origin https://app.example.com \
  --server-cors-allow-origin https://admin.example.com
```

### Behavior

| Configuration | Result |
|---|---|
| `allow_origins` empty (default) | No CORS headers emitted; browser cross-origin requests are blocked. |
| `allow_origins = ["https://app.example.com", ...]` | Server reflects the request `Origin` header only when it matches an entry in the list. |
| `allow_origins = ["*"]` | Permissive mode: any origin is accepted, and `Access-Control-Allow-Credentials: true` is also set. |

Allowed methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`.
Allowed request headers: `Origin`, `Content-Length`, `Content-Type`, `Authorization`.

Preflight `OPTIONS` requests are handled by the server automatically — no additional configuration required.


Setting `allow_origins = ["*"]` enables permissive mode, which also sends `Access-Control-Allow-Credentials: true`. This combination is broadly accepting and should generally be reserved for development. For production, list each trusted origin explicitly.


### Example: production with explicit origins

```toml title="resonate.toml — production"
[auth]
publickey = "/etc/resonate/auth/public.pem"

[server.cors]
allow_origins = [
  "https://app.example.com",
  "https://admin.example.com",
]
```

Combined with JWT authentication, this restricts the server to a known set of browser origins while still requiring a valid token on every request.

CORS support was introduced in Resonate Server v0.9.4.

## Outbound HTTP push authentication

Inbound JWT auth (above) protects the server from unauthenticated SDK clients. The matching server-side concern is **outbound** authentication: when the server pushes a task to a worker URL via HTTP push, the worker may itself sit behind an authenticated endpoint (for example a GCP Cloud Run service deployed with `--no-allow-unauthenticated`, or any internal service that validates a bearer token).

v0.9.5 introduced three outbound auth modes for the HTTP push transport. All three apply only to the `http://` / `https://` push transport — they do not affect Pub/Sub or bash exec deliveries.

| Mode | What the server sends |
|---|---|
| `none` (default) | No `Authorization` header. Suitable for unauthenticated workers or networks with trust enforced at another layer. |
| `bearer` | A static `Authorization: Bearer <token>` header on every delivery. The token is configured once and never refreshed. |
| `gcp` | A GCP-issued OIDC ID token, minted per-audience using Application Default Credentials. Suitable for Cloud Run, Cloud Functions, and other GCP services that natively validate Google-signed ID tokens. |

The mode is set with `--transports-http-push-auth-mode`, the matching `[transports.http_push.auth].mode` TOML key, or `RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__MODE`.

### Static bearer token

Use this mode when every worker shares a single secret you control end-to-end (an internal service mesh, a self-hosted deployment with a shared HMAC).

```toml title="resonate.toml"
[transports.http_push.auth]
mode = "bearer"
# Token is typically supplied by env var rather than checked-in config:
#   RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__TOKEN=<token>
```

```shell title="CLI form"
resonate serve \
  --transports-http-push-auth-mode bearer \
  --transports-http-push-auth-token "$RESONATE_PUSH_TOKEN"
```

The token is sent verbatim as `Authorization: Bearer <token>` on every push. It is never rotated by the server — rotation is your responsibility.

### GCP OIDC ID token

Use this mode when workers run on GCP and validate Google-signed ID tokens (Cloud Run, Cloud Functions, IAP-protected services, etc.). The server mints an ID token per audience using the GCP credentials available to the server process (Application Default Credentials).

```toml title="resonate.toml"
[transports.http_push.auth]
mode = "gcp"
# Optional: override the audience used when minting tokens. When absent,
# each delivery target URL is used as its own audience.
# audience = "https://workers.example.com"
```

```shell title="CLI form"
resonate serve --transports-http-push-auth-mode gcp
```

Two notes on audience handling:

- **Default** — if you do not set `audience`, the server uses each delivery target URL verbatim as the audience. This is the right setting for Cloud Run services where each worker validates tokens against its own URL.
- **Override** — set `audience` (or `--transports-http-push-auth-aud`) when every worker validates against a single shared audience (for example an API gateway in front of multiple workers).

Tokens are cached per audience inside the server process, so audience reuse across deliveries does not re-mint on every call.


If the GCP credentials provider fails to mint a token (missing ADC, network failure, IAM misconfiguration), the server logs a warning and **delivers the request without an `Authorization` header**. The delivery is not retried at the auth layer; the worker will reject the unauthenticated request and the standard task-retry path applies. Watch server logs for `OIDC ID token mint failed` to detect this state.


### Custom header name

By default the token is sent in the `Authorization` header. Override with `--transports-http-push-auth-header` (or the matching TOML / env key) when the worker expects a different header — for example `X-Goog-IAP-JWT-Assertion` for some IAP setups:

```shell
resonate serve \
  --transports-http-push-auth-mode gcp \
  --transports-http-push-auth-header X-Goog-IAP-JWT-Assertion
```

### Quick reference

| TOML key | CLI flag | Env var |
|---|---|---|
| `[transports.http_push.auth].mode` | `--transports-http-push-auth-mode` | `RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__MODE` |
| `[transports.http_push.auth].token` | `--transports-http-push-auth-token` | `RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__TOKEN` |
| `[transports.http_push.auth].audience` | `--transports-http-push-auth-aud` | `RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__AUDIENCE` |
| `[transports.http_push.auth].header` | `--transports-http-push-auth-header` | `RESONATE_TRANSPORTS__HTTP_PUSH__AUTH__HEADER` |

## Production best practices

### Token management

1. **Generate strong tokens** — Use properly signed JWTs with appropriate claims and expiry
2. **Store securely** — Use environment variables, AWS Secrets Manager, Google Secret Manager, etc.
3. **Rotate regularly** — Implement key rotation policies
4. **Scope appropriately** — Use different keys for different environments (dev, staging, prod)

### Network security

Even with authentication enabled, follow network security best practices:

- **Restrict network access** with firewalls and security groups
- **Use private networks** when possible (VPC, private subnets)
- **Enable rate limiting** at the load balancer or API gateway level

### Monitoring

Monitor authentication failures and suspicious activity:

- Enable server logging with `--level debug` to see auth events
- Set up alerts for repeated auth failures
- Track token usage patterns

See the [Observability](/deploy/logging) documentation for logging configuration.

## Multi-environment setup

Use different credentials for each environment:

```bash title=".env.development"
RESONATE_URL=http://localhost:8001
RESONATE_TOKEN=dev-token-here
```

```bash title=".env.production"
RESONATE_URL=https://resonate.yourcompany.com
RESONATE_TOKEN=prod-token-from-secrets-manager
```

## Troubleshooting

### "401 Unauthorized" errors

**Symptom**: SDK requests fail with 401 status code

**Common causes**:
- Token not provided
- Token signature doesn't match the server's public key
- Token expired
- Environment variable not loaded correctly

**Solution**:
1. Verify the server was started with `--auth-publickey` pointing to the correct public key
2. Verify the SDK token was signed with the matching private key
3. Check token expiry claims
4. Review server logs (`--level debug`) for auth failure details

## Examples and tutorials

For a working example of authenticated applications:

- **TypeScript**: See the [token authentication example](https://github.com/resonatehq-examples/example-token-auth-ts) repository

## Next steps

- [Deploy to production](/deploy/run-server) with authentication enabled
- [Set up observability](/deploy/logging) to monitor auth events
- [Configure message transports](/deploy/message-transports) for distributed workers
- Review [server configuration](/deploy/run-server#configuration) for all server flags

## Related documentation

- [Develop with TypeScript SDK](/develop/typescript) — SDK reference with auth examples
- [Develop with Rust SDK](/develop/rust) — SDK reference with auth examples
- [Server configuration](/deploy/run-server#configuration) — Complete server flag reference

---

---
url: https://docs.resonatehq.io/deploy/serverless-workers
title: Serverless workers
---

Currently only the TypeScript SDK supports serverless worker shims.

## What is a serverless worker shim?

A serverless worker shim, also referred to as a binding, is a lightweight adapter that allows Resonate Workers to run in serverless (FaaS) environments such as Cloudflare Workers, AWS Lambda, Google Cloud Functions, etc.
The shim handles the communication between the Resonate SDK and the serverless platform, allowing you to run long-running workflows in ephemeral serverless functions with relative ease.

## Supported platforms

The following serverless platforms are supported with official Resonate worker shims:

### AWS Lambda

[Amazon Lambda worker shim | **TypeScript**](https://github.com/resonatehq/resonate-faas-aws-ts)

**Quick example:**

```shell title="Install the shim package"
npm install @resonatehq/aws
```

Instead of importing Resonate from the SDK package, import it from the AWS shim package.

```ts title="index.ts"
import { Resonate } from "@resonatehq/aws";
import { countdown } from "./count";

const resonate = new Resonate();

resonate.register("countdown", countdown);

export const handler = resonate.httpHandler();
```

### Cloudflare Workers

[Cloudflare Workers worker shim | **TypeScript**](https://github.com/resonatehq/resonate-faas-cloudflare-ts)

**Quick example:**

```shell title="Install the shim package"
npm install @resonatehq/cloudflare
```

Instead of importing Resonate from the SDK package, import it from the Cloudflare shim package.

```ts title="index.ts"
import { Resonate } from "@resonatehq/cloudflare";
import { countdown } from "./count";

const resonate = new Resonate();

resonate.register("countdown", countdown);

export default resonate.handlerHttp();
```

Ready to use example apps:

- [Durable Counter with Cloudflare Workers | TypeScript](https://github.com/resonatehq-examples/example-countdown-cloudflare-ts)
- [Deep Research Agent with Cloudflare Workers | TypeScript](https://github.com/resonatehq-examples/example-openai-deep-research-agent-cloudflare-ts)

### Google Cloud Functions

[Google Cloud Functions worker shim | **TypeScript**](https://github.com/resonatehq/resonate-faas-gcp-ts)

**Quick example:**

```shell title="Install the shim package"
npm install @resonatehq/gcp
```

Instead of importing Resonate from the SDK package, import it from the GCP shim package.

```ts title="index.ts"
import { Resonate } from "@resonatehq/gcp";
import { countdown } from "./count";

const resonate = new Resonate();

resonate.register("countdown", countdown);

export const handler = resonate.handlerHttp();
```

Ready to use example apps:

- [Durable Counter with GCP Functions | TypeScript](https://github.com/resonatehq-examples/example-countdown-gcp-ts)
- [Deep Research Agent with GCP Functions | TypeScript](https://github.com/resonatehq-examples/example-openai-deep-research-agent-gcp-ts)

### Supabase Edge Functions

[Supabase Edge Functions worker shim | **TypeScript**](https://github.com/resonatehq/resonate-faas-supabase-ts)

Supabase Edge Functions run on Deno; the shim is published on [JSR](https://jsr.io/@resonatehq/supabase) rather than npm.

**Quick example:**

```shell title="Install the shim package"
deno add jsr:@resonatehq/supabase
```

Instead of importing Resonate from the SDK package, import it from the Supabase shim package.

```ts title="index.ts"
import { Resonate } from "@resonatehq/supabase";
import { countdown } from "./count";

const resonate = new Resonate();
resonate.register("countdown", countdown);

resonate.httpHandler();
```

Ready to use example apps:

- [Durable Counter with Supabase Edge Functions | TypeScript](https://github.com/resonatehq-examples/example-countdown-supabase-ts)
- [Deep Research Agent with Supabase Edge Functions | TypeScript](https://github.com/resonatehq-examples/example-openai-deep-research-agent-supabase-ts)

## Serverless-specific constraints

Serverless workers run inside platform-imposed invocation timeouts. Resonate's acquired-task lease (`ttl`) interacts with that timeout: the lease is the window the server gives the worker to make progress on a task before it considers the task abandoned and reassigns it. Workflows that accumulate many promises in a single root will eventually fail to replay within the lease, even if individual steps are fast.

### Platform timeouts

| Platform | Max invocation timeout | Notes |
|---|---|---|
| AWS Lambda | 15 min | Check `@resonatehq/aws` for default `ttl` |
| Google Cloud Functions Gen 2 | 9 min (540s) | `@resonatehq/gcp` defaults `ttl` to 5 min — bump to 10 min so the lease always exceeds the function timeout |
| Google Cloud Run | 60 min | Check `@resonatehq/gcp` for default `ttl` |
| Cloudflare Workers | varies (CPU-time vs wall-clock differ by plan) | See [Cloudflare Workers limits](https://developers.cloudflare.com/workers/platform/limits/) |
| Supabase Edge Functions | varies | See [Supabase Edge Functions limits](https://supabase.com/docs/guides/functions/limits) |


A workflow that loops forever inside one root promise — `while(true) { doWork() }` — accumulates child promises with every iteration. After thousands of iterations (10k+ in practice), replay duration exceeds the acquired-task lease, the server emits error code `1199 — Task is not acquired` and reassigns the task mid-execution, and cadence collapses. The longer the workflow runs, the worse it gets.


### The fix: recursive tail call with `ctx.detached`

Have the per-iteration function play exactly *one* iteration, and as its **last yield**, spawn the next iteration as a brand-new root via `ctx.detached`. The current invocation returns; the next invocation starts with a fresh origin id and an empty history.

```typescript
function* playGame(ctx: Context, n: number) {
  // ...play exactly one game (ctx.run, ctx.sleep, etc.)...
  yield* ctx.detached(playGame, n + 1); // ✅ last yield, fresh root, bounded replay
}
```

The split must happen *inside* the per-iteration function. A parent loop that calls `ctx.detached` repeatedly — `for (;;) yield* ctx.detached(work, n)` — still records each call in the parent's history, reproducing the bug on the parent. See [Bound the promise count of a single execution](/develop/constraints#bound-the-promise-count-of-a-single-execution) for the full explanation.

### Configuring `ttl`

The shim `Resonate` constructor accepts a `ttl` option (milliseconds):

```typescript
import { Resonate } from "@resonatehq/gcp";

const resonate = new Resonate({ ttl: 10 * 60 * 1000 }); // 10 min
```

`ttl` should exceed the platform's max invocation timeout. The lease tells the server how long to wait before assuming the worker is dead. If `ttl` is shorter than the platform timeout, the server may reassign the task to a fresh invocation while the original is still legitimately running, leading to mid-execution task reassignment (error code 1199) and duplicate work.

**See also:**
- [Bound the promise count of a single execution](/develop/constraints#bound-the-promise-count-of-a-single-execution)

---

---
url: https://docs.resonatehq.io/deploy/tracing
title: Tracing
---

Distributed tracing shows you the complete execution flow of your Resonate functions across workers and the server. This is invaluable for debugging performance issues and understanding complex workflows.

## What is distributed tracing?

Traditional logs show what happened on individual services. Tracing shows the **entire path** a request takes through your system:

```
Request enters → Server creates promise → Worker A starts task →
Worker A calls Worker B → Worker B completes → Worker A completes →
Promise resolves
```

Each step is a **span**. Spans are linked together into a **trace** that shows the complete request lifecycle.

## OpenTelemetry support

The Resonate TypeScript SDK supports [OpenTelemetry](https://opentelemetry.io/) for automatic tracing of:
- Function execution (start, completion, duration)
- Context operations (`ctx.run()`, `ctx.sleep()`)
- RPC calls between workers
- Promise creation and resolution
- Retries and failures

Use the [@resonatehq/opentelemetry](https://github.com/resonatehq/resonate-opentelemetry-ts) package to enable tracing.

## Setup

### Install the package

```bash
npm install @resonatehq/opentelemetry
```

### Configure OpenTelemetry

```typescript
import { ResonateOpenTelemetry } from "@resonatehq/opentelemetry";
import { Resonate } from "@resonatehq/sdk";

// Initialize OpenTelemetry
const otel = new ResonateOpenTelemetry({
  serviceName: "my-resonate-app",
  exporterEndpoint: "http://localhost:4318/v1/traces",  // OTLP endpoint
});

// Create Resonate instance with tracing
const resonate = new Resonate({
  url: "http://localhost:8001",
  // OpenTelemetry context automatically propagated
});
```

### OTLP Exporter endpoint

OpenTelemetry Protocol (OTLP) is the standard way to send traces. Point it to your collector or backend:

- **Jaeger:** `http://localhost:4318/v1/traces`
- **Zipkin:** `http://localhost:9411/api/v2/spans`
- **Tempo:** `http://localhost:4318/v1/traces`
- **Datadog:** `http://localhost:8126/v0.4/traces` (via Datadog Agent)
- **Honeycomb:** `https://api.honeycomb.io/v1/traces` (with API key)

## Trace backends

Choose a backend to visualize and query traces:

### Jaeger (open source)

**Quick start with Docker:**

```bash
docker run -d --name jaeger \
  -p 4318:4318 \
  -p 16686:16686 \
  jaegertracing/all-in-one:latest
```

Access UI at http://localhost:16686

### Grafana Tempo (open source)

Lightweight, cost-effective tracing backend:

```yaml title="docker-compose.yml"
version: '3.8'
services:
  tempo:
    image: grafana/tempo:latest
    ports:
      - "4318:4318"  # OTLP receiver
    volumes:
      - ./tempo.yaml:/etc/tempo.yaml
    command: ["-config.file=/etc/tempo.yaml"]

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_INSTALL_PLUGINS=grafana-tempo-datasource
```

### Datadog APM

Commercial solution with powerful features:

```typescript
import { ResonateOpenTelemetry } from "@resonatehq/opentelemetry";

const otel = new ResonateOpenTelemetry({
  serviceName: "my-resonate-app",
  exporterEndpoint: "http://localhost:8126/v0.4/traces",  // Datadog Agent
});
```

Traces appear in Datadog APM UI automatically.

### Honeycomb

Cloud-native observability platform:

```typescript
import { ResonateOpenTelemetry } from "@resonatehq/opentelemetry";

const otel = new ResonateOpenTelemetry({
  serviceName: "my-resonate-app",
  exporterEndpoint: "https://api.honeycomb.io/v1/traces",
  headers: {
    "x-honeycomb-team": process.env.HONEYCOMB_API_KEY,
  },
});
```

### AWS X-Ray

AWS-native tracing:

```typescript
import { AWSXRayPropagator } from "@opentelemetry/propagator-aws-xray";
import { AWSXRayIdGenerator } from "@opentelemetry/id-generator-aws-xray";

const otel = new ResonateOpenTelemetry({
  serviceName: "my-resonate-app",
  exporterEndpoint: "http://localhost:2000",  // X-Ray daemon
  idGenerator: new AWSXRayIdGenerator(),
  propagator: new AWSXRayPropagator(),
});
```

## What gets traced

### Function execution

Every Resonate function creates a span:

```typescript
resonate.register("processOrder", function* (ctx, order) {
  // Span: "processOrder" (duration = function execution time)
  const result = yield* ctx.run(validateOrder, order);
  return result;
});
```

**Span attributes:**
- `resonate.function.name` - Function name
- `resonate.promise.id` - Promise ID
- `resonate.worker.group` - Worker group

### Context operations

Each `ctx.run()`, `ctx.sleep()`, etc. creates child spans:

```typescript
resonate.register("checkout", function* (ctx, cart) {
  // Parent span: "checkout"

  const validated = yield* ctx.run(validateCart, cart);
  // Child span: "validateCart"

  yield* ctx.sleep(1000);
  // Child span: "sleep(1000ms)"

  const charged = yield* ctx.run(chargeCard, cart.total);
  // Child span: "chargeCard"

  return charged;
});
```

### RPC calls

When one worker calls another, spans are linked across workers:

```typescript
// Worker A
resonate.register("orderWorkflow", function* (ctx, order) {
  // Span: "orderWorkflow" on Worker A

  const result = yield* ctx.rpc(
    "checkInventory",
    order.items,
    ctx.options({ target: "poll://any@inventory-workers" })
  );
  // Creates linked span on Worker B

  return result;
});

// Worker B (inventory-workers group)
resonate.register("checkInventory", (ctx, items) => {
  // Span: "checkInventory" on Worker B
  // Parent: "orderWorkflow" on Worker A
});
```

Parent-child relationships are maintained via OpenTelemetry context propagation.

### Retries and failures

Failed attempts create error spans:

```typescript
resonate.register("unreliableTask", async (ctx) => {
  // Each retry attempt gets its own span
  // Failed attempts marked with error: true
  // Successful retry shows full history
});
```

## Analyzing traces

### Find slow functions

Look for spans with high duration:

**Jaeger:** Filter by min duration (e.g., >5s)
**Datadog:** Sort by latency, look at p95/p99
**Honeycomb:** Use `HEATMAP(duration_ms)` to visualize distribution

### Identify bottlenecks

Trace view shows where time is spent:

```
orderWorkflow (10s total)
├─ validateOrder (0.1s)
├─ checkInventory (8s) ← BOTTLENECK
└─ chargeCard (1.9s)
```

Focus optimization on `checkInventory`.

### Debug failures

Failed spans show error details:

```
orderWorkflow (FAILED)
├─ validateOrder (SUCCESS)
├─ checkInventory (FAILED) ← error: "out of stock"
```

Click into failed span to see error message, stack trace, and context.

### Track distributed workflows

See how work flows across workers:

```
Worker A: orderWorkflow
  ├─ Worker B: checkInventory
  ├─ Worker B: reserveInventory
  └─ Worker C: sendConfirmation
```

Understand the complete execution path.

## Sampling

High-volume systems generate too many traces. Use sampling to reduce overhead:

```typescript
import { ParentBasedSampler, TraceIdRatioBasedSampler } from "@opentelemetry/sdk-trace-base";

const otel = new ResonateOpenTelemetry({
  serviceName: "my-resonate-app",
  sampler: new ParentBasedSampler({
    root: new TraceIdRatioBasedSampler(0.1),  // Sample 10% of traces
  }),
});
```

**Strategies:**
- **Head-based sampling:** Sample at trace creation (10% of all traces)
- **Tail-based sampling:** Keep interesting traces (all errors, slow requests)
- **Adaptive sampling:** Adjust rate based on traffic

Most backends support tail-based sampling (sample after seeing full trace).

## Correlation with logs and metrics

**Trace ID in logs:**

```typescript
import { trace } from "@opentelemetry/api";

const span = trace.getActiveSpan();
const traceId = span?.spanContext().traceId;

console.log(`Processing order [traceId=${traceId}]`);
```

Search logs by trace ID to see detailed context.

**Metrics from traces:**

Backends can generate metrics from span data:
- Request rate by function name
- Latency percentiles (p50, p95, p99)
- Error rates
- Span counts

## Best practices

1. **Enable tracing from day one** - Hard to add later
2. **Use meaningful span names** - "processOrder" not "function_123"
3. **Add custom attributes** - Enrich spans with business context:
```typescript
span.setAttribute("order.id", orderId);
span.setAttribute("user.id", userId);
```
4. **Trace sparingly in hot paths** - Use sampling for high-throughput functions
5. **Correlate traces with logs** - Include trace ID in log messages
6. **Set up alerts on trace metrics** - Monitor error rate, latency from spans
7. **Review traces regularly** - Don't wait for incidents to look at traces

## Limitations

**Python SDK:** OpenTelemetry support is not yet implemented. Use logs and metrics for observability until tracing is added.

**Server tracing:** The Resonate server itself doesn't emit traces yet. You can trace SDK/worker activity, but server coordination isn't visible in traces.

## Troubleshooting

### No traces appearing

**Check exporter endpoint:**
```bash
curl http://localhost:4318/v1/traces
# Should return 404 (endpoint exists but needs POST)
```

**Check OpenTelemetry initialization:**
```typescript
console.log("OpenTelemetry initialized:", otel);
```

**Enable debug logging:**
```typescript
const otel = new ResonateOpenTelemetry({
  serviceName: "my-app",
  logLevel: "debug",  // See what's being exported
});
```

### Spans not linked across workers

**Cause:** Context propagation not working.

**Solution:** Ensure `@resonatehq/opentelemetry` is initialized on all workers. Context is automatically propagated via Resonate's RPC mechanism.

### High cardinality warnings

**Cause:** Too many unique span attributes (e.g., user IDs, promise IDs).

**Solution:** Use sampling or limit high-cardinality attributes:
```typescript
// Don't add unique IDs as span names
span.setAttribute("order.id", orderId);  // Attribute, not name
```

## Summary

**For development:**
- Use Jaeger locally (easy Docker setup)
- Enable tracing from day one
- Trace a few example workflows to understand behavior

**For production:**
- Use managed backend (Datadog, Honeycomb, Tempo)
- Enable sampling (10-30% of traces)
- Correlate traces with logs and metrics
- Set up alerts on trace-derived metrics

**Key insights from tracing:**
- Where time is spent (find bottlenecks)
- How work flows across workers (understand distributed execution)
- Why failures happen (error context and stack traces)

Tracing complements logs and metrics. Together, they give you complete observability:
- **Logs:** What happened (events)
- **Metrics:** How much/how fast (aggregates)
- **Traces:** Why and where (causality)

---

---
url: https://docs.resonatehq.io/deploy/upgrade-server
title: Upgrade server
---

When you upgrade your Resonate Server, you are replacing the current binary with a new one.

You will not need to touch or reconfigure your existing database.

If a database schema migration is required, you will be notified by server logs when you start the new version.
Migration instructions will be provided in the release notes.

### Upgrade with brew

If you installed the Resonate Server using Homebrew, you can upgrade it with the following commands:

```shell
brew update
brew upgrade resonate
```

### Upgrade manually

If you installed the Resonate Server manually by downloading the binary, you can upgrade it by downloading the latest version and replacing the existing binary.
You can download the latest version of the Resonate Server from the [Releases](https://github.com/resonatehq/resonate/releases).

---

---
url: https://docs.resonatehq.io/develop/constraints
title: Constraints and gotchas
---

Resonate enables you to write distributed applications that survive failures and restarts, but this power comes with a few important rules you need to follow. This page explains what those rules are and, more importantly, **why they exist**.

## The four rules

When writing durable functions with Resonate, you must follow these constraints:

1. **Functions must be deterministic** - Same inputs always produce the same outputs
2. **Functions must be idempotent** - Safe to retry multiple times
3. **Activations cannot outlive the process** - Long-running work needs Resonate primitives
4. **Bound the promise count of a single execution** - Replay cost scales with accumulated child promises

Let's explore each one.

---

## Functions must be deterministic

### What does deterministic mean?

A function is **deterministic** if calling it with the same inputs always produces the same outputs and side effects, in the same order.

When your process crashes mid-execution, Resonate replays your function from the beginning using recorded results from previous steps. If your function behaves differently during replay (non-deterministic), Resonate won't be able to reconstruct the correct state, and your execution will diverge from what actually happened.

### Examples of non-deterministic operations

These operations will cause problems if used directly in durable functions:

❌ **Random number generation**

```typescript
function* processOrder(ctx: Context, orderId: string) {
  const confirmationCode = Math.random(); // ⚠️ Different value on replay!
  // ...
}
```

❌ **Current time**

```typescript
function* scheduleReminder(ctx: Context, userId: string) {
  const now = Date.now(); // ⚠️ Different value on replay!
  // ...
}
```

❌ **External API calls**

```typescript
function* getUserData(ctx: Context, userId: string) {
  const response = await fetch(`https://api.example.com/users/${userId}`); // ⚠️ Could return different data on replay!
  // ...
}
```

❌ **Reading from files or databases**

```typescript
function* processData(ctx: Context) {
  const data = fs.readFileSync("./data.json"); // ⚠️ File might have changed!
  // ...
}
```

### The solution: Use Context methods

Resonate provides **deterministic versions** of these operations through the Context API.

✅ **Deterministic random numbers**






    

```typescript title="Deterministic random generation"
function* processOrder(ctx: Context, orderId: string) {
  const confirmationCode = yield* ctx.math.random(); // ✅ Same value on replay
  // ...
}
```

  

    

```python title="Deterministic random generation"
@resonate.register
def process_order(ctx: Context, order_id: str):
    confirmation_code = yield ctx.random.random()  # ✅ Same value on replay
    # ...
```

  



✅ **Deterministic time**



    

```typescript title="Deterministic timestamps"
function* scheduleReminder(ctx: Context, userId: string) {
  const now = yield* ctx.date.now(); // ✅ Same value on replay
  // ...
}
```

  

    

```python title="Deterministic timestamps"
@resonate.register
def schedule_reminder(ctx: Context, user_id: str):
    now = yield ctx.time.time()  # ✅ Same value on replay
    # ...
```

  



✅ **Deterministic external calls**



    

```typescript title="Wrap external calls with ctx.run"
function* getUserData(ctx: Context, userId: string) {
  const userData = yield* ctx.run(async () => {
    const response = await fetch(`https://api.example.com/users/${userId}`);
    return response.json();
  }); // ✅ Result recorded, replays use recorded value
  // ...
}
```

  

    

```python title="Wrap external calls with ctx.run"
@resonate.register
def get_user_data(ctx: Context, user_id: str):
    def fetch_user(ctx):
        response = requests.get(f"https://api.example.com/users/{user_id}")
        return response.json()
    
    user_data = yield ctx.run(fetch_user)  # ✅ Result recorded, replays use recorded value
    # ...
```

  




If an operation might return different results when called again (time, random, I/O, external APIs), wrap it with a Context method. Resonate records the result the first time and uses the recorded value during replays.


**See also:**
- [TypeScript Context APIs](/develop/typescript#context-apis)
- [Python Context APIs](/develop/python#context-apis)

---

## Functions must be idempotent

### What does idempotent mean?

A function is **idempotent** if executing it multiple times with the same inputs has the same effect as executing it once.

Resonate automatically retries failed function executions. If your function has side effects that aren't safe to repeat (like charging a credit card or sending an email), retries could cause duplicate charges or duplicate messages.

### Examples of non-idempotent operations

These operations are **not** safe to retry:

❌ **Incrementing a counter**

```typescript
function* recordView(ctx: Context, postId: string) {
  await db.query("UPDATE posts SET views = views + 1 WHERE id = ?", [postId]); 
  // ⚠️ Retry = double counting!
}
```

❌ **Appending to a list**

```typescript
function* addToCart(ctx: Context, userId: string, item: string) {
  await db.query("INSERT INTO cart_items (user_id, item) VALUES (?, ?)", [userId, item]);
  // ⚠️ Retry = duplicate cart items!
}
```

❌ **Sending notifications without deduplication**

```typescript
function* sendWelcomeEmail(ctx: Context, userId: string) {
  await emailService.send({
    to: userId,
    subject: "Welcome!",
    body: "..."
  }); // ⚠️ Retry = duplicate emails!
}
```

### The solution: Design for retries

Make your operations safe to retry:

✅ **Use upsert instead of insert**

```typescript title="Idempotent database operations"
function* recordView(ctx: Context, postId: string, sessionId: string) {
  yield* ctx.run(async () => {
    // Use session ID to make it idempotent
    await db.query(
      "INSERT INTO view_log (post_id, session_id, timestamp) VALUES (?, ?, ?) ON CONFLICT DO NOTHING",
      [postId, sessionId, Date.now()]
    );
  });
}
```

✅ **Include idempotency keys**

```typescript title="Idempotent API calls with keys"
function* chargeCustomer(ctx: Context, orderId: string, amount: number) {
  yield* ctx.run(async () => {
    await stripe.charges.create({
      amount: amount,
      currency: "usd",
      idempotency_key: orderId, // ✅ Stripe deduplicates by key
    });
  });
}
```

✅ **Let promise IDs handle deduplication**

```typescript title="Idempotent because promise ID is deterministic"
function* sendWelcomeEmail(ctx: Context, userId: string) {
  // ctx.run automatically creates a deterministic promise ID
  // based on the function and arguments
  yield* ctx.run(async () => {
    await emailService.send({ 
      to: userId, 
      subject: "Welcome!",
      idempotency_key: `welcome-${userId}` // Email service deduplicates
    });
  });
  // If this retries, same promise ID = same result returned from storage
  // Email service never gets called again
}
```

When you use `ctx.run()` or `ctx.rpc()`, Resonate automatically generates a deterministic promise ID based on your function name and arguments. On retry, the same inputs produce the same promise ID, so Resonate returns the stored result instead of re-executing the work.

This means if you use Resonate's APIs correctly, **you don't have to manually check for duplicates** - the framework handles it for you.


When you call operations through `ctx.run()` or `ctx.rpc()`, Resonate generates promise IDs that are the same across retries. This gives you automatic idempotency without manual deduplication logic.


### What `ctx.run` retries by default

When you call `ctx.run(fn)` without supplying a `retryPolicy`, the SDK applies:

- **TypeScript** — `Exponential()` for regular `async` functions, `Never()` for generator functions. `Exponential()` defaults: `delay = 1000 ms`, `factor = 2`, `maxDelay = 30 000 ms`, `maxRetries = Number.MAX_SAFE_INTEGER`.
- **Python** — `Exponential()` for regular functions, `Never()` for generator functions. `Exponential()` defaults: `delay = 1 s`, `factor = 2`, `max_delay = 30 s`, `max_retries = sys.maxsize`.
- **Rust** — no per-invocation retry policy yet; retries are governed by the server's `--tasks-retry-timeout` flag.

This means a `ctx.run(fn)` call that keeps failing will keep retrying with exponential backoff, capped at 30 seconds between attempts, effectively forever — until the surrounding invocation's `timeout` fires.

See the [Defaults reference](/reference/defaults) for the full per-SDK table.

---

## Activations cannot outlive the process

### What does this mean?

An **activation** is a single execution attempt of your function. If your process crashes or restarts, the current activation ends immediately. Your function cannot keep running in the background after the process exits.

Resonate is not a job queue or background task runner. It coordinates work across processes, but each individual function execution lives inside a process. When that process ends (crashes, deploy, scale-down), the execution stops.

### What happens on process restart?

When your process restarts, Resonate will:

1. **Detect the activation ended** (heartbeat timeout)
2. **Start a new activation** (automatic retry)
3. **Replay from the beginning** using recorded results (determinism)

This is how Resonate achieves **fault tolerance** - your work survives crashes, but individual activations do not.

### Long-running work

If you need work to span hours, days, or weeks, use Resonate primitives instead of blocking:

❌ **Blocking sleep (wrong)**

```typescript
function* longRunningJob(ctx: Context) {
  await new Promise(resolve => setTimeout(resolve, 3600000)); // ⚠️ 1 hour - process will likely crash!
  // ...
}
```

✅ **Durable sleep (correct)**



    

```typescript title="Sleep that survives process restarts"
function* longRunningJob(ctx: Context) {
  yield* ctx.sleep(3600000); // ✅ 1 hour - process can restart safely
  // ...
}
```

  

    

```python title="Sleep that survives process restarts"
@resonate.register
def long_running_job(ctx: Context):
    yield ctx.sleep(3600)  # ✅ 1 hour - process can restart safely
    # ...
```

  



**How it works:**

`ctx.sleep()` doesn't block your process. Instead:
1. Resonate records a "wake up at time X" checkpoint
2. Your function yields control (process can do other work)
3. At time X, Resonate resumes your function
4. If the process crashed in between, Resonate restarts and resumes after the sleep

✅ **Human-in-the-loop (wait for external input)**



    

```typescript title="Wait indefinitely for human approval"
function* approvalWorkflow(ctx: Context, requestId: string) {
  const approvalPromise = yield* ctx.promise();
  
  // Send approval request email with promise ID
  yield* ctx.run(sendApprovalEmail, approvalPromise.id);
  
  // Wait for human to resolve the promise (could be hours/days)
  const approved = yield* approvalPromise; // ✅ Survives process restarts
  
  if (approved) {
    // continue workflow
  }
}
```

  

    

```python title="Wait indefinitely for human approval"
@resonate.register
def approval_workflow(ctx: Context, request_id: str):
    approval_promise = yield ctx.promise()
    
    # Send approval request email with promise ID
    yield ctx.run(send_approval_email, approval_promise.id)
    
    # Wait for human to resolve the promise (could be hours/days)
    approved = yield approval_promise  # ✅ Survives process restarts
    
    if approved:
        # continue workflow
```

  




For work that takes hours, days, or weeks, use `ctx.sleep()` or Durable Promises instead of blocking. This lets your process restart safely without losing progress.


**See also:**
- [Durable sleep example](/get-started/examples/durable-sleep)
- [Human-in-the-loop example](/get-started/examples/human-in-the-loop)

---

## Bound the promise count of a single execution

### What does this mean?

Replay duration grows with the count of executed promises in a single root invocation. On cold-start, every prior step is replayed before the next can proceed.

Each `ctx.run()`, `ctx.rpc()`, `ctx.sleep()`, or other Context call inside a root invocation adds one promise to that root's history. When the worker restarts (deploy, scale-down, crash, task reassignment), Resonate replays the function from the beginning, walking every recorded promise to reconstruct state. The more promises accumulated under a single root, the longer replay takes.

### When this becomes a problem

Workflows that loop indefinitely or accumulate many child promises within a single root.

On serverless platforms with fixed acquired-task leases (e.g., `@resonatehq/gcp` default `ttl` = 5 min), replay duration eventually exceeds the lease, the server reassigns the task mid-execution (error code `1199 — Task is not acquired`), and cadence collapses.

❌ **Single root accumulates children forever**

```typescript
function* playGame(ctx: Context, n: number) {
  while (true) {                                  // ⚠️ one durable invocation forever
    // ...play one game (ctx.run, ctx.sleep, etc.)...
    // every yield adds a child promise to this root's history;
    // after thousands of iterations, replay > task lease
  }
}
```

### The solution: Recursive tail call with `ctx.detached`

Have the per-iteration function play exactly *one* iteration, and as its **last yield**, spawn the next iteration as a brand-new root via `ctx.detached`. The current invocation returns; the next invocation starts with a fresh origin id and an empty history.

✅ **Each invocation = one iteration, replay scope bounded**

```typescript
function* playGame(ctx: Context, n: number) {
  // ...play exactly one game (ctx.run, ctx.sleep, etc.)...
  yield* ctx.detached(playGame, n + 1); // ✅ last yield, fresh root, bounded replay
}
```


A parent loop that calls `ctx.detached` repeatedly — `for (;;) yield* ctx.detached(work, n)` — still records each call in the parent's history, reproducing the same accumulation problem on the parent. The recursive-tail shape (per-iteration function spawns its own successor as the last yield, then returns) is what bounds replay scope.


The same pattern applies to any forever-running workflow: poll loops, monitoring agents, recurring jobs, demo loops. The per-iteration function plays one iteration, then `yield* ctx.detached(self, next)` as its final yield.


If a workflow loops indefinitely or accumulates many child promises, split iterations with `ctx.detached()`. Each iteration gets a fresh root and a bounded replay scope, regardless of how long the overall workflow runs.


**See also:**
- [Serverless-specific constraints](/deploy/serverless-workers#serverless-specific-constraints)

---

## Summary

| Constraint | Why it exists | Solution |
|------------|---------------|----------|
| **Deterministic** | Functions are replayed on restart - must produce same results | Use `ctx.math.random()`, `ctx.date.now()`, `ctx.run()` |
| **Idempotent** | Functions are retried on failure - must be safe to repeat | Use idempotency keys, upserts, deduplication checks |
| **Process lifetime** | Activations end when process ends - can't outlive it | Use `ctx.sleep()`, Durable Promises for long-running work |
| **Bounded promise count** | Replay walks all prior promises - cost scales linearly | Use `ctx.detached()` for forever-loop iterations |

Following these rules ensures your distributed application survives process crashes and restarts, retries safely without duplicating work, and handles long-running workflows spanning hours or days.

To see these patterns in action, check out the [TypeScript SDK guide](/develop/typescript), [Python SDK guide](/develop/python), or browse the [example applications](/get-started/examples).

---

---
url: https://docs.resonatehq.io/develop/go
title: Go SDK skills
---

[0.1.0](https://github.com/resonatehq/resonate-sdk-go/releases/tag/0.1.0) is the Go SDK's first tagged release, and the SDK is in active development — APIs may still change between releases. Check the [open issues](https://github.com/resonatehq/resonate-sdk-go/issues) for known gaps. The internal protocol is stable; the Go API surface is still settling.


Whether you are a human or an AI agent, this skill guide will help you develop applications using the Resonate Go SDK.

This skill sheet assumes that you already know Resonate is a good fit for your use case.
If you are unsure, please refer to [Why Resonate](/evaluate/why-resonate#the-three-pillars).

It's important to think about the potential architecture of your application as it ties to your use case.
This can determine which APIs and options you will use for function activations.
If you have a use case in mind, but haven't built with Resonate before, we recommend reviewing some of the common patterns in our [example applications](/get-started/examples) — the Go examples (`example-hello-world-go`, `example-fan-out-fan-in-go`, `example-human-in-the-loop-go`, and more) live in the [`resonatehq-examples`](https://github.com/resonatehq-examples) org.

## Installation

**How to install the Resonate Go SDK into your project.**

The Go SDK is a standard Go module. Add it with `go get`:

```shell
go get github.com/resonatehq/resonate-sdk-go@latest
```

The current git tag is `0.1.0` (no `v` prefix), which Go's module resolver does not recognize as a module version — so `@v0.1.0` does not resolve, and `@latest` resolves to a Go module pseudo-version (a generated string like `v0.0.0-<timestamp>-<commit>`) pinned to the latest `main` commit. Pin to a specific commit if you need a reproducible build:

```shell
go get github.com/resonatehq/resonate-sdk-go@<commit-sha>
```

Once added, import the package (the canonical import alias is `resonate`):

```go
import resonate "github.com/resonatehq/resonate-sdk-go"
```

The in-process transport used for local development lives in a leaf subpackage:

```go
import "github.com/resonatehq/resonate-sdk-go/localnet"
```

## Initialization

**How to initialize a Resonate instance.**

Initializing a Resonate instance gives you the APIs needed to register, activate, and await durable functions.

```go title="main.go"
import resonate "github.com/resonatehq/resonate-sdk-go"

r, err := resonate.New(resonate.Config{URL: "http://localhost:8001"})
if err != nil {
    log.Fatalf("resonate.New: %v", err)
}
defer func() { _ = r.Stop() }()
```

- A Resonate instance can connect to either an in-process local network (best for development) or a remote Resonate Server (best for production).
- A Resonate instance is used in the Ephemeral World to register and activate functions — it cannot be used inside Durable Functions. Use the [Context APIs](#context-apis) for function activations inside Durable Functions.

`resonate.New` selects its network using the following precedence:

1. `Config.URL` — when set, the SDK builds a default HTTP transport pointing at this address.
2. `Config.Network` — an explicitly constructed transport (used when `URL` is empty).
3. `RESONATE_URL` environment variable — consulted when both `URL` and `Network` are empty.

If none of the three is set, `New` returns `resonate.ErrNetworkRequired`.

The full set of `Config` fields:

| Field | Type | Default | Purpose |
|---|---|---|---|
| `URL` | `string` | _unset_ | Builds a default HTTP transport at this address. Takes precedence over `Network` and `RESONATE_URL`. |
| `Network` | `Network` | _nil_ | An explicitly constructed transport (e.g. `localnet.NewLocal(...)` or `httpnet.NewHTTP(...)`). Used when `URL` is empty. |
| `Heartbeat` | `Heartbeat` | `AsyncHeartbeat` at `TTL/2` | Keeps an acquired task's lease alive. Pass `resonate.NoopHeartbeat{}` for local mode. |
| `Encryptor` | `Encryptor` | `NoopEncryptor` | Controls codec encryption at the durability boundary. |
| `TTL` | `time.Duration` | `60s` | Per-task lease duration. |
| `Prefix` | `string` | _empty_ | Prepended (with `:`) to every promise/task ID created by `Run`, `RPC`, or `Get`. |
| `Token` | `string` | _unset_ | Sent as Bearer auth on every protocol request. |


There is no `Group` field on `Config`. To run under a named routing group, construct the transport explicitly and pass it as `Config.Network`:

```go
import "github.com/resonatehq/resonate-sdk-go/httpnet"

r, err := resonate.New(resonate.Config{
    Network: httpnet.NewHTTP("http://localhost:8001", httpnet.HTTPOptions{
        Group: "worker-group-a",
    }),
})
```

`Config.URL` is shorthand for an `httpnet.NewHTTP(url, httpnet.HTTPOptions{})` transport, which uses the default group (`"default"`).


### Zero-dependency development

Unlike other Durable Execution offerings, apart from installing the SDK itself, Resonate enables you to get started without any additional dependencies.
This is because Resonate can run in a local development mode (`localnet`) that runs the server state machine in-process, using in-memory storage for promises and tasks.

```go title="main.go"
import (
    resonate "github.com/resonatehq/resonate-sdk-go"
    "github.com/resonatehq/resonate-sdk-go/localnet"
)

pid := "dev-worker"
r, err := resonate.New(resonate.Config{
    Network:   localnet.NewLocal("default", &pid),
    Heartbeat: resonate.NoopHeartbeat{}, // localnet has no lease endpoint to heartbeat against
})
```


The default `AsyncHeartbeat` issues HTTP keep-alive requests to keep a task lease alive. `localnet` has no such endpoint, so you must set `Heartbeat: resonate.NoopHeartbeat{}` when using it — otherwise the heartbeat loop errors against a transport that can't serve it.


Local development mode can be suitable for a while.
However, when you want to run multiple worker processes, persist state across restarts, or share work between machines, you will need to connect to a Resonate Server.
See the [Quickstart guide](/get-started/quickstart) or [How to run a Resonate Server](/deploy/run-server) for guidance on getting a server up and running.

### Authentication

The Go SDK supports token-based authentication (JWT) when connecting to a secured Resonate Server. Set `Config.Token`:

```go title="main.go"
r, err := resonate.New(resonate.Config{
    URL:   "https://localhost:8001",
    Token: os.Getenv("RESONATE_TOKEN"),
})
```





### Environment variables

The Go SDK's constructor inspects a single environment variable:

#### `RESONATE_URL`

- Provides the full base URL (scheme, host, and port) for connecting to a remote Resonate server. Used only when neither `Config.URL` nor `Config.Network` is set.
- Default is _unset_ (no network — `New` returns `ErrNetworkRequired`).
- Example:

  ```bash
  export RESONATE_URL="http://localhost:8001"
  ```

  ```go
  r, err := resonate.New(resonate.Config{}) // picks up RESONATE_URL
  ```


Unlike some sibling SDKs, the Go SDK does not consult `RESONATE_HOST` / `RESONATE_PORT` / `RESONATE_SCHEME` / `RESONATE_TOKEN` / `RESONATE_PREFIX`. Token, prefix, and group are set explicitly on `Config` or the transport. The single env hook is `RESONATE_URL`.


## Defining durable functions

**How to write a function that Resonate can run durably.**

A durable function in Go is an ordinary Go function — there is no attribute or wrapper macro. Every durable function must return exactly two values, `(T, error)`, where `T` is any JSON-serializable type. There are two ways a function enters the system, and they have different signature rules.

**Registered functions** — anything you pass to [`resonate.Register`](#resonateregister) (so it can be invoked by name via `RPC`, the CLI, or as a top-level `Run` entrypoint) must have the canonical signature:

```go
func(*resonate.Context, A) (R, error)
```

`Register` is generic over `A` (the args type) and `R` (the result type), so both parameters are required. Use `struct{}` for `A` when the function takes no input, and for `R` when it produces no meaningful result.

```go
import resonate "github.com/resonatehq/resonate-sdk-go"

type GreetArgs struct {
    Name string `json:"name"`
}

// Registered workflow — orchestrates sub-tasks via the Context.
func greetWorkflow(ctx *resonate.Context, args GreetArgs) (string, error) {
    var msg string
    f, err := ctx.Run(formatGreeting, args.Name)
    if err != nil {
        return "", err
    }
    if err := f.Await(&msg); err != nil {
        return "", err
    }
    return msg, nil
}

// A registered workflow with no input and no result.
func cleanup(ctx *resonate.Context, _ struct{}) (struct{}, error) {
    // ...
    return struct{}{}, nil
}
```

**Leaf functions invoked via `ctx.Run`** — a function you only ever hand to [`ctx.Run`](#ctxrun) (never register by name) may use a leaner shape. `ctx.Run` resolves the signature by reflection and accepts any of:

| Signature | Kind |
|---|---|
| `func(*resonate.Context, A) (R, error)` | Takes the Context and args |
| `func(*resonate.Context) (R, error)` | Takes the Context, no args |
| `func(A) (R, error)` | Stateless leaf with args |
| `func() (R, error)` | Stateless leaf, no args |

```go
// Leaf — stateless computation, no Context needed. Valid as a ctx.Run target.
func formatGreeting(name string) (string, error) {
    return fmt.Sprintf("hello, %s!", name), nil
}
```


The args value is encoded into the durable promise's payload so the workflow can resume on any worker that has the function registered. Use exported struct fields with `json` tags for anything you want carried across a crash or a remote dispatch.


## Client APIs

The following Client APIs are used in the Ephemeral World — they cannot be used inside Durable Functions.

### `resonate.Register`

Register a durable function to expose it to the Resonate system.
A registered function can then be activated by the Resonate Client, the Resonate CLI, or from inside another Durable Function via the Context APIs.

`Register` is a package-level generic function (Go has no method-level generics): it takes the Resonate instance, a name, and the function, and returns a typed handle whose `Run` method carries the function's result type.

```go
greetFn, err := resonate.Register(r, "greet", greetWorkflow)
if err != nil {
    log.Fatalf("Register: %v", err)
}
```

### `RegisteredFunc.Run`

`Run` invokes a registered function in the **same process** and returns a typed handle.
You can think of it as a "run right here" invocation.
After invocation, the function is durable and will recover in another process if required.

```go
// greetFn is the *RegisteredFunc returned by resonate.Register
h, err := greetFn.Run(ctx, "greet-1", GreetArgs{Name: "world"})
if err != nil {
    log.Fatalf("Run: %v", err)
}

result, err := h.Result(ctx) // typed: returns (string, error)
```

`Run` accepts an optional `resonate.RunOptions`:

```go
h, err := greetFn.Run(ctx, "greet-1", GreetArgs{Name: "world"}, resonate.RunOptions{
    Timeout:     60 * time.Second,
    Target:      "poll://any@workers",
    Tags:        map[string]string{"team": "checkout"},
    RetryPolicy: resonate.ConstantRetry{MaxAttempts: 3, Delay: time.Second},
})
```

| `RunOptions` field | Purpose |
|---|---|
| `Timeout` | Caps the root promise deadline. Zero uses `DefaultTopLevelTimeout` (24 h). |
| `Target` | Logical routing address (the `resonate:target` tag). Empty falls back to the configured group. |
| `Tags` | Merged into the root promise's tag set. |
| `RetryPolicy` | Re-execution policy when the function returns an error. Nil applies `DefaultRetryPolicy`. Only takes effect when this worker wins the create-and-acquire race and runs the function locally; a task picked up by another worker via server push always uses `DefaultRetryPolicy`. See [Retries](#retries). |
| `Version` | Reserved for future use — declared but not yet consumed ([issue #5](https://github.com/resonatehq/resonate-sdk-go/issues/5)). |

### `Resonate.RPC`

`RPC` (Remote Procedure Call) invokes a function in a **remote process** by registered name and returns an untyped handle.
You can think of it as a "run somewhere else" invocation.
The target function does not need to be registered locally.

```go
h, err := r.RPC(ctx, "greet-1", "greet", GreetArgs{Name: "world"})
if err != nil {
    log.Fatalf("RPC: %v", err)
}

var result string
if err := h.Result(ctx, &result); err != nil {
    log.Fatalf("Result: %v", err)
}
```

`RPC` accepts an optional `resonate.RPCOptions` (`Timeout`, `Target`, `Tags`, `Version`).

### `Resonate.Get`

Get a handle to an existing execution by its promise ID. Returns a `*resonate.ServerError` with `Code: 404` when the promise does not exist.

```go
h, err := r.Get(ctx, "greet-1")
if err != nil {
    log.Fatalf("Get: %v", err)
}

var result string
if err := h.Result(ctx, &result); err != nil {
    log.Fatalf("Result: %v", err)
}
```

### Reading a handle's result

A handle blocks until its underlying promise settles (or the passed `context.Context` is cancelled), then decodes the value.

- **Typed:** `RegisteredFunc.Run` returns a `*TypedHandle[R]` whose `Result(ctx)` returns `(R, error)` directly.
- **Untyped:** `RPC` and `Get` return a `*Handle` whose `Result(ctx, out any)` decodes into the pointer you pass.

```go
// Untyped handle into a typed value, via the generic helper:
result, err := resonate.ResultOf[string](ctx, h)
```

A rejected promise returns the application error embedded in the rejection payload (as a `*resonate.ApplicationError`, or the deserialized concrete error where available).

### `Resonate.Stop`

Gracefully shuts down a Resonate instance. Closes the network connection, stops the heartbeat loop, and cancels the background subscription-refresh goroutine. Idempotent.

```go
defer func() { _ = r.Stop() }()
```

**When to call it.** Call `Stop` from any process that should exit after its work finishes — demo binaries, one-shot jobs, examples, CI tasks. Without it, the background goroutines keep the process alive after `main` would otherwise return.


Calling `Stop` on a worker (an RPC service, a queue consumer, an MCP server, or any other long-lived process) tears down the channels the worker uses to receive and hold work:

- The connection to the Resonate Server closes — the worker stops receiving dispatched tasks.
- The heartbeat loop stops — the server-side TTL on in-flight tasks expires, and the server reassigns them.
- The subscription-refresh goroutine is cancelled — listeners on awaited promises are no longer re-registered.

The worker keeps running but silently stops processing work. Workers should stay up; let process termination (SIGINT / SIGTERM) end the lifecycle.


### `Resonate.Promises`

`r.Promises()` is the direct promise API — `Get` / `Create` / `Resolve` / `Reject` / `Cancel` — for creating or settling a durable promise from outside a workflow (human-in-the-loop and external-coordination patterns).

### `Resonate.Schedules`

`r.Schedules()` is the direct schedule API: `Get`, `Create`, and `Delete`. A schedule creates a fresh promise on every cron firing, from a promise-ID template.

There is no high-level `Schedule()` that binds a registered function yet, so the caller supplies everything the fired promises need — including the `resonate:target` routing tag, which the server **requires** (creates without it are rejected). Encode the payload your workers expect, and tag the promises with the group that should execute them:

```go
_, err := r.Schedules().Create(context.TODO(),
    "nightly-report",          // schedule ID
    "0 2 * * *",               // cron — evaluated in UTC
    "report-{{.timestamp}}",   // promise-ID template
    time.Hour,                 // timeout of each fired promise
    resonate.ScheduleCreateOptions{
        PromiseParam: payload,
        PromiseTags:  map[string]string{"resonate:target": "poll://any@report-workers"},
    },
)
```

Cron expressions are evaluated in **UTC**, with Quartz day-of-week numbering (`1` = Sunday) — prefer day names like `MON-FRI`. See the [Schedules & cron reference](/reference/schedules) for the expression format, template variables, and the tags the server injects on fired promises.

## Context APIs

**How to use the Resonate Context inside Durable Functions.**

Resonate's Context enables you to invoke sub-tasks from inside a workflow.
This is how you extend the Call Graph and create a world of Durable Functions.

Each Context method returns a `*resonate.Future` immediately (the durable promise is created synchronously); you call `Future.Await(&out)` to read the result. If the awaited promise is still pending, `Await` suspends the workflow and re-enters it when the promise settles. Because of this, **fan-out is "dispatch all, then await all"**: call `ctx.Run` / `ctx.RPC` for every branch first to create the promises, then `Await` each future.

### `ctx.Run`

Invoke a function in the **same process**.
By default, calling `Await` immediately after executes sequentially — the workflow blocks until the invoked function returns.

```go
func myWorkflow(ctx *resonate.Context, input string) (string, error) {
    f, err := ctx.Run(myLeaf, input)
    if err != nil {
        return "", err
    }
    var result string
    if err := f.Await(&result); err != nil {
        return "", err
    }
    return result, nil
}
```

To run in parallel, dispatch every child first, then await each future:

```go
func myWorkflow(ctx *resonate.Context, inputs []string) ([]string, error) {
    fa, err := ctx.Run(process, inputs[0])
    if err != nil {
        return nil, err
    }
    fb, err := ctx.Run(process, inputs[1])
    if err != nil {
        return nil, err
    }

    var a, b string
    if err := fa.Await(&a); err != nil {
        return nil, err
    }
    if err := fb.Await(&b); err != nil {
        return nil, err
    }
    return []string{a, b}, nil
}
```


The workflow runtime joins every `ctx.Run`-spawned goroutine before it can suspend or fulfill the parent task. A function that blocks indefinitely holds the task lease open until it expires. Long-running or external-blocking work belongs in `ctx.RPC` (remote dispatch) or `ctx.Promise` (latent durable promise), not `ctx.Run`.


### `ctx.RPC`

Invoke a function in a **remote process** by registered name.
Await on the returned future suspends the workflow until the remote function returns.

```go
func myWorkflow(ctx *resonate.Context, input string) (string, error) {
    f, err := ctx.RPC("remote-func", input)
    if err != nil {
        return "", err
    }
    var result string
    if err := f.Await(&result); err != nil {
        return "", err
    }
    return result, nil
}
```

`ctx.RPC` accepts an optional `resonate.RPCOpts{Timeout, Target}`. The fan-out-then-await pattern shown for `ctx.Run` applies equally to `ctx.RPC` — see [`example-fan-out-fan-in-go`](https://github.com/resonatehq-examples/example-fan-out-fan-in-go).

### `ctx.Sleep`

Durable sleep. There is no limit to how long the function can sleep — hours, days, or weeks.
The sleep survives process restarts.

```go
func reminder(ctx *resonate.Context, userID string) (struct{}, error) {
    f, err := ctx.Sleep(1 * time.Hour)
    if err != nil {
        return struct{}{}, err
    }
    if err := f.Await(nil); err != nil { // no value to decode
        return struct{}{}, err
    }
    // ... send the reminder
    return struct{}{}, nil
}
```


Whenever a workflow suspends and resumes (after a `Sleep`, a remote `RPC`, or a pending `Promise`), the entire workflow body runs again from the top. Durable child promises short-circuit work that already settled, but any side effect that runs *before* reaching that boundary executes again. Wrap observable side effects (DB writes, payments, emails) in their own `ctx.Run` / `ctx.RPC` so the durable promise records the result.


### `ctx.Promise`

Create a latent durable promise resolved by an external system (a webhook, a human, another process). Hand the promise's ID to the external resolver; `Await` suspends until it settles. This is the building block for [human-in-the-loop](https://github.com/resonatehq-examples/example-human-in-the-loop-go) and [webhook](https://github.com/resonatehq-examples/example-webhook-handler-go) workflows.

```go
func approval(ctx *resonate.Context, _ struct{}) (string, error) {
    f, err := ctx.Promise(resonate.PromiseOpts{Timeout: 24 * time.Hour})
    if err != nil {
        return "", err
    }
    // f.ID() is the promise ID — hand it to whoever resolves it
    // (e.g. resonate promise resolve <id> --data '"approved"')

    var decision string
    if err := f.Await(&decision); err != nil {
        return "", err
    }
    return decision, nil
}
```

### `ctx.Detached`

Dispatch a remote function fire-and-forget. Unlike `ctx.RPC`, the parent workflow does **not** suspend on it — `Detached` returns only the new promise's ID, and the detached execution's lifecycle is independent of the parent.

```go
func placeOrder(ctx *resonate.Context, orderID string) (struct{}, error) {
    // Fire-and-forget: send the receipt without blocking the order workflow.
    id, err := ctx.Detached("send-receipt", ReceiptArgs{Order: orderID})
    if err != nil {
        return struct{}{}, err
    }
    _ = id // references the detached execution; the parent does not await it
    return struct{}{}, nil
}
```


The Go SDK derives `Detached` IDs with FNV-1a; the Rust SDK uses a different hash. Do not rely on running the same workflow body on two different SDKs producing the same `Detached` IDs.


### Context accessors

Inside a workflow, the Context provides read-only metadata:

```go
func myWorkflow(ctx *resonate.Context, _ struct{}) (struct{}, error) {
    _ = ctx.ID()        // this execution's promise ID
    _ = ctx.ParentID()  // parent promise ID (empty for root)
    _ = ctx.OriginID()  // root workflow ID — stable across the whole tree
    _ = ctx.FuncName()  // registered function name
    _ = ctx.TimeoutAt() // promise deadline, epoch milliseconds
    return struct{}{}, nil
}
```

### Builder options

Context entrypoints take options as a trailing struct argument (Go uses option structs rather than chained builders):

| Method | Options struct | Fields |
|---|---|---|
| `ctx.Run` | `resonate.RunOpts` | `Timeout`, `RetryPolicy` |
| `ctx.RPC` | `resonate.RPCOpts` | `Timeout`, `Target` |
| `ctx.Promise` | `resonate.PromiseOpts` | `Timeout`, `Data` |
| `ctx.Detached` | `resonate.DetachedOpts` | `Timeout`, `Target` |

```go
f, err := ctx.Run(myLeaf, "input", resonate.RunOpts{
    Timeout:     30 * time.Second,
    RetryPolicy: resonate.LinearRetry{MaxAttempts: 5, Base: time.Second},
})
```

## Retries

When a function passed to `ctx.Run` (or a top-level `Run`) returns an error, Resonate re-executes it according to a retry policy. Nil applies `DefaultRetryPolicy` (exponential backoff, 3 attempts). The SDK ships three policies plus a no-retry sentinel, all implementing the `resonate.RetryPolicy` interface:

| Policy | Behavior |
|---|---|
| `resonate.ConstantRetry{MaxAttempts, Delay}` | Fixed delay between attempts. |
| `resonate.LinearRetry{MaxAttempts, Base}` | Attempt N waits `Base * N`. |
| `resonate.ExponentialRetry{MaxAttempts, Base, Max, Jitter}` | Doubling delay (`Base`, `2·Base`, …) capped at `Max`, with optional jitter. |
| `resonate.NoRetry` | A single attempt (no retries). |

```go
f, err := ctx.Run(chargeCard, args, resonate.RunOpts{
    RetryPolicy: resonate.ExponentialRetry{
        MaxAttempts: 5,
        Base:        100 * time.Millisecond,
        Max:         30 * time.Second,
        Jitter:      true,
    },
})
```

### Non-retryable errors

To mark a specific error as terminal so the retry loop stops immediately — regardless of the policy — wrap it with `resonate.NewNonRetryable`. The wrapped error remains reachable through `errors.Is` / `errors.As` / `errors.Unwrap`.

```go
func validate(input string) (string, error) {
    if input == "" {
        // No amount of retrying fixes bad input — fail fast.
        return "", resonate.NewNonRetryable(errors.New("input is required"))
    }
    return input, nil
}
```

## Defaults

The Go SDK ships with these key defaults:

- **`resonate.New(resonate.Config{})`** — `TTL = 60s`; `AsyncHeartbeat` at `TTL/2`; `NoopEncryptor`; no prefix. Network is resolved from `URL` → `Network` → `RESONATE_URL`, else `ErrNetworkRequired`.
- **Top-level `Run` / `RPC` timeout** — `DefaultTopLevelTimeout = 24h` when `Options.Timeout` is zero.
- **Child `ctx.Run` / `ctx.RPC` / `ctx.Promise` / `ctx.Sleep` timeout** — `DefaultChildTimeout = 24h` when the call's `Timeout` is zero (capped at the parent's remaining deadline).
- **`DefaultRetryPolicy`** — `ExponentialRetry{MaxAttempts: 3, Base: 100ms, Max: 30s, Jitter: true}`, applied when `RetryPolicy` is nil.

The values above are the Go defaults. For server defaults and the TypeScript/Python/Rust comparison with source citations, see the [Defaults reference](/reference/defaults).

---

---
url: https://docs.resonatehq.io/develop
title: Develop with Resonate
---

<img src="/images/banner-develop-dark.png" alt="Develop with Resonate section" className="hidden dark:block" />
<img src="/images/banner-develop-light.png" alt="Develop with Resonate section" className="block dark:hidden" />

## Problems you no longer solve

Distributed systems have a whole class of problems that used to require weeks of engineering, careful design, and ongoing maintenance:

- **Retries and backoff** - What happens when an API call fails? Do you retry immediately? Exponentially back off? Track attempt counts?
- **Idempotency** - How do you prevent duplicate charges, double emails, or repeated side effects when retrying failed operations?
- **State management** - Where do you store workflow state? How do you ensure it survives crashes? How do you clean it up?
- **Process coordination** - How do you distribute work across multiple workers? What happens when a worker dies mid-task?
- **Long-running workflows** - How do you pause a process for hours or days without blocking threads or keeping connections open?
- **Failure recovery** - When your service crashes mid-workflow, how do you resume from where you left off instead of starting over?
- **Ordering and consistency** - How do you guarantee operations happen in the right order across distributed processes?

**With Resonate, you don't build these anymore.** You write your business logic as straightforward code, and Resonate handles the hard distributed systems problems underneath.

---

## What Resonate gives you

### Durable execution by default

Every function you run through Resonate survives process crashes and restarts. If your service dies mid-execution, Resonate automatically:
- Detects the failure
- Restarts your function on another process
- Resumes from the last successful checkpoint
- Returns the same result as if nothing happened

You don't write retry logic. You don't manage state. You just write normal code.

### Automatic idempotency

When Resonate retries your function, it doesn't re-execute operations that already succeeded. It replays your function using recorded results from previous attempts.

This means:
- External API calls happen once (even across retries)
- Database writes don't duplicate
- Payments don't charge twice
- Emails don't send multiple times

You get automatic idempotency without writing deduplication logic.

### Distributed coordination primitives

Resonate provides simple primitives that solve complex coordination problems:

**`ctx.run()`** - Execute any function durably. The result is recorded and reused on retry.

**`ctx.sleep()`** - Pause your workflow for hours, days, or weeks without blocking your process.

**`ctx.rpc()`** - Call functions on other processes as if they're local. Resonate routes the work and returns the result.

**Durable Promises** - Coordinate between processes, humans, and systems. Wait for external input (like approval) that might take days.

These primitives compose together, letting you build complex workflows from simple pieces.

### Zero dependency development

Start building immediately. Resonate's local mode lets you develop and test without running a server, database, or any infrastructure.

When you're ready for production, connect to a Resonate Server and your local workflows become distributed, fault-tolerant systems - without changing your code.

---

## How it works

Resonate uses a technique called **deterministic replay**. When your process crashes, Resonate replays your function from the beginning, but instead of re-executing expensive operations (API calls, database writes), it uses recorded results from the previous attempt.

This means your function must follow a few simple rules:
- Use `ctx.run()` for any operation that might return different results (API calls, random numbers, timestamps)
- Design functions to be safe to retry (idempotent)
- Use `ctx.sleep()` for long waits instead of blocking

These constraints ensure your functions replay correctly and survive failures. See [Constraints](/develop/constraints) for a detailed explanation.

---

## Getting started

Choose your language and dive in:





Or jump straight into an [example application](/get-started/examples) to see real patterns in action.

---

## What you'll find in the SDK guides

The SDK-specific pages cover everything you need to build with Resonate:

**Installation** - How to add Resonate to your project

**Initialization** - Setting up local mode vs production mode

**Registering functions** - Making your functions durable and invocable

**Client APIs** - Creating promises, invoking functions, managing workflows

**Context APIs** - Using `ctx.run()`, `ctx.sleep()`, `ctx.rpc()`, and other primitives

**Code examples** - Real patterns for common scenarios

Each SDK page is self-contained with complete examples and API references. Pick your language and start building:
- [TypeScript SDK guide](/develop/typescript)
- [Python SDK guide](/develop/python)
- [Rust SDK guide](/develop/rust)
- [Go SDK guide](/develop/go)

---

---
url: https://docs.resonatehq.io/develop/java
title: Java SDK skills
---

The Java SDK is at `v0.1.1` — the first version published to Maven Central — and is in active development. APIs may change before the API surface settles. Check the [open issues](https://github.com/resonatehq/resonate-sdk-java/issues) for known gaps. The internal protocol is stable; the Java API surface is still settling.


Whether you are a human or an AI agent, this skill guide will help you develop applications using the Resonate Java SDK.

This skill sheet assumes that you already know Resonate is a good fit for your use case.
If you are unsure, please refer to [Why Resonate](/evaluate/why-resonate#the-three-pillars).

It's important to think about the potential architecture of your application as it ties to your use case.
This can determine which APIs and options you will use for function activations.
If you have a use case in mind, but haven't built with Resonate before, we recommend reviewing some of the common patterns in our [example applications](/get-started/examples). The Java SDK also ships a set of runnable example programs (hello-world, fan-out/fan-in pipeline, saga, human-in-the-loop, retries, and more) under [`src/examples`](https://github.com/resonatehq/resonate-sdk-java/tree/main/src/examples) in the SDK repo.

## Installation

**How to install the Resonate Java SDK into your project.**

The Resonate Java SDK requires **Java 21 or newer**. It uses [virtual threads](https://openjdk.org/jeps/444) (a generally-available feature as of Java 21) to drive durable executions, so Java 8/11/17 are not supported.

The SDK is published to Maven Central as `io.resonatehq:resonate-sdk-java`. Add it with your build tool of choice:



    

```kotlin title="build.gradle.kts"
dependencies {
    implementation("io.resonatehq:resonate-sdk-java:0.1.1")
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}
```

    

    

```groovy title="build.gradle"
dependencies {
    implementation 'io.resonatehq:resonate-sdk-java:0.1.1'
}

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}
```

    

    

```xml title="pom.xml"
<dependency>
    <groupId>io.resonatehq</groupId>
    <artifactId>resonate-sdk-java</artifactId>
    <version>0.1.1</version>
</dependency>
```

    



The SDK pulls in Jackson (`com.fasterxml.jackson.core:jackson-databind`) transitively for the JSON durability boundary — no extra dependency to declare.

Once added, the SDK lives under a single package; import the types you need:

```java
import io.resonatehq.resonate.Resonate;
import io.resonatehq.resonate.Context;
```

## Initialization

**How to initialize a Resonate instance.**

Initializing a Resonate instance gives you the APIs needed to register, activate, and await durable functions. The instance is built with a fluent builder:

```java title="Main.java"
import io.resonatehq.resonate.Resonate;

Resonate r = Resonate.builder()
        .url("http://localhost:8001")
        .build();
try {
    // register functions, run / rpc invocations ...
} finally {
    r.stop();
}
```

- A Resonate instance can connect to either an in-process local network (best for development) or a remote Resonate Server (best for production).
- A Resonate instance is used in the Ephemeral World to register and activate functions — it cannot be used inside Durable Functions. Use the [Context APIs](#context-apis) for function activations inside Durable Functions.

The builder selects its network using the following precedence:

1. `url(...)` — when set, the SDK builds a default HTTP transport pointing at this address.
2. `network(...)` — an explicitly constructed transport (used when no `url` is set).
3. `RESONATE_URL` (or the `RESONATE_HOST` / `RESONATE_PORT` / `RESONATE_SCHEME` trio) environment variable — consulted when neither `url` nor `network` is set.
4. Otherwise — an in-process `LocalNetwork` (zero-dependency local mode).

The full set of builder options:

| Builder method | Type | Default | Purpose |
|---|---|---|---|
| `url(String)` | `String` | _unset_ | Builds a default HTTP transport at this address. Takes precedence over `network` and `RESONATE_URL`. |
| `network(Network)` | `Network` | _auto_ | An explicitly constructed transport. Used when `url` is empty. |
| `group(String)` | `String` | `"default"` | The routing group this instance subscribes to (the anycast target other workers dispatch to). |
| `token(String)` | `String` | `RESONATE_TOKEN` | Sent as Bearer auth on every protocol request. |
| `ttl(Duration)` | `Duration` | `60s` | Per-task lease duration. |
| `prefix(String)` | `String` | `RESONATE_PREFIX` | Prepended (with `:`) to every promise/task ID created by `run`, `rpc`, or `get`. |
| `pid(String)` | `String` | _auto_ | Worker process ID used for the task lease/heartbeat endpoint. Auto-generated when unset. |
| `heartbeat(Hb)` | `Hb` | _auto_ | Keeps an acquired task's lease alive. Defaults to an async heartbeat at `TTL/2` for remote mode, and a no-op for local mode. |
| `encryptor(Encryptor)` | `Encryptor` | `NoopEncryptor` | Controls codec encryption at the durability boundary. |
| `maxConcurrentTasks(Integer)` | `Integer` | `64` | Ceiling on tasks executing (holding a lease) at once in this process. |
| `retryPolicy(RetryPolicy)` | `RetryPolicy` | `Exponential` | The SDK-wide default retry policy for leaf functions. See [Retries](#retries). |


Unlike some sibling SDKs that set the group on a separately-constructed transport, the Java SDK exposes `group(...)` directly on the builder:

```java
Resonate r = Resonate.builder()
        .url("http://localhost:8001")
        .group("worker-group-a")
        .build();
```

When omitted, the instance joins the default group (`"default"`).


### Zero-dependency development

Unlike other Durable Execution offerings, apart from installing the SDK itself, Resonate enables you to get started without any additional dependencies.
This is because Resonate can run in a local development mode that runs the server state machine in-process, using in-memory storage for promises and tasks.

When you construct a Resonate instance with no `url`, no `network`, and no `RESONATE_URL` in the environment, the SDK uses an in-process `LocalNetwork`:

```java title="Main.java"
import io.resonatehq.resonate.Resonate;

Resonate r = new Resonate(); // in-process local mode, no server required
```

In local mode the SDK automatically uses a no-op heartbeat (there is no server lease endpoint to keep alive), so there is nothing extra to configure.

Local development mode can be suitable for a while.
However, when you want to run multiple worker processes, persist state across restarts, or share work between machines, you will need to connect to a Resonate Server.
See the [Quickstart guide](/get-started/quickstart) or [How to run a Resonate Server](/deploy/run-server) for guidance on getting a server up and running.

### Authentication

The Java SDK supports token-based authentication (JWT) when connecting to a secured Resonate Server. Set `token(...)` on the builder:

```java title="Main.java"
Resonate r = Resonate.builder()
        .url("https://localhost:8001")
        .token(System.getenv("RESONATE_TOKEN"))
        .build();
```

When omitted, `token` falls back to the `RESONATE_TOKEN` environment variable.





### Environment variables

When neither `url(...)` nor `network(...)` is set, the builder reads the connection from the environment:

#### `RESONATE_URL`

- Provides the full base URL (scheme, host, and port) for connecting to a remote Resonate server.
- Example:

  ```bash
  export RESONATE_URL="http://localhost:8001"
  ```

  ```java
  Resonate r = new Resonate(); // picks up RESONATE_URL
  ```

#### `RESONATE_HOST` / `RESONATE_PORT` / `RESONATE_SCHEME`

- A fallback used when `RESONATE_URL` is not set. `RESONATE_HOST` is required to trigger the fallback; `RESONATE_SCHEME` defaults to `http` and `RESONATE_PORT` defaults to `8001`.

#### `RESONATE_TOKEN` / `RESONATE_PREFIX`

- `RESONATE_TOKEN` supplies the Bearer auth token when `token(...)` is not set; `RESONATE_PREFIX` supplies the ID prefix when `prefix(...)` is not set.

## Defining durable functions

**How to write a function that Resonate can run durably.**

A durable function in Java is an ordinary `static` method whose **first parameter is a `Context`**, followed by up to five application arguments:

```java
import io.resonatehq.resonate.Context;

public final class Greeter {
    // A leaf function: no durable op, just computes a value.
    public static String formatGreeting(Context ctx, String name) {
        return "hello, " + name + "!";
    }

    // A workflow: orchestrates sub-tasks via the Context.
    public static String greetWorkflow(Context ctx, String name) {
        return ctx.run(Greeter::formatGreeting, name).await();
    }
}
```

Functions are always supplied as **method references** (`Owner::fn`), never as a `String` name or a reflected `Method` — the SDK recovers the method behind the reference for you. The reference's functional-interface arity (`Fn.F0` through `Fn.F5`) is what bounds a durable function to **at most five arguments** beyond the `Context`. The argument types and the return type must be JSON-serializable, because they cross the durability boundary.

There are two ways a function enters the system, with different registration rules:

- **Registered functions** — anything you pass to [`register`](#resonate-register) so it can be invoked by name (via `rpc`, the CLI, or as a top-level `run` entrypoint). Registration is required for these entry points.
- **`ctx.run` targets** — a function you only ever hand to [`ctx.run`](#ctx-run) as a method reference does **not** need to be registered; the SDK runs the referenced method directly. (Invoking by name — `ctx.run("name", ...)` — does require a local registration, since there is no reference to resolve.)


A function's arguments and return value are encoded into the durable promise's payload so the workflow can resume on any worker that has the function registered. Use plain data types (records, collections, primitives, strings) for anything you want carried across a crash or a remote dispatch.


## Client APIs

The following Client APIs are used in the Ephemeral World — they cannot be used inside Durable Functions.

### `Resonate.register`

Register a durable function to expose it to the Resonate system.
A registered function can then be activated by the Resonate Client, the Resonate CLI, or from inside another Durable Function via the Context APIs.

`register` takes a method reference and returns it unchanged (so the call site can keep a reference if it wants one):

```java
r.register(Greeter::greetWorkflow);
```

By default a function registers under its own method name at version `1`. Override the name, version, and (optionally) a per-function retry policy with the longer overloads:

```java
import io.resonatehq.resonate.Retry.Constant;

r.register(Greeter::greetWorkflow, "greet", 1);
r.register(Greeter::greetWorkflow, "greet", 2, new Constant(3, 1)); // per-function retry policy
```

The same name may be registered at several versions.

### `Resonate.run`

`run` starts a durable invocation of a function in the **same process** and returns a typed handle.
You can think of it as a "run right here" invocation.
After invocation, the function is durable and will recover in another process if required.

```java
import io.resonatehq.resonate.Handle.ResonateHandle;

ResonateHandle<String> handle = r.run("greet-1", Greeter::greetWorkflow, "world");
String result = handle.result(); // typed: String
```

Passing the function as a method reference makes the handle typed (`ResonateHandle<String>` here). There is also a by-name form that returns an untyped handle (`ResonateHandle<Object>`), useful when the function is registered elsewhere:

```java
ResonateHandle<Object> handle = r.run("greet-1", "greet", "world");
Object result = handle.result();
```

Per-call options (timeout, target, version, retry policy) come from a fresh options handle — see [Per-call options](#per-call-options).

### `Resonate.rpc`

`rpc` (Remote Procedure Call) invokes a function in a **remote process** by registered name and returns a handle.
You can think of it as a "run somewhere else" invocation.
The target function does not need to be registered locally.

```java
import io.resonatehq.resonate.Context.Opts;
import io.resonatehq.resonate.Handle.ResonateHandle;

ResonateHandle<Object> handle = r.options(new Opts().withTarget("backend"))
        .rpc("greet-1", "greet", "world");
Object result = handle.result();
```

`withTarget(...)` routes the call to a named group's anycast address; the server hands the execute message to a worker subscribed there. Like `run`, `rpc` also accepts a method reference for a typed handle.

### `Resonate.get`

Get a handle to an existing execution by its promise ID. The handle is untyped (`ResonateHandle<Object>`).

```java
import io.resonatehq.resonate.Handle.ResonateHandle;

ResonateHandle<Object> handle = r.get("greet-1");
Object result = handle.result();
```

### Reading a handle's result

A handle blocks until its underlying promise settles, then decodes the value.

- **Typed:** `run` / `rpc` given a method reference return a `ResonateHandle<R>` whose `result()` returns `R`.
- **Untyped:** the by-name `run` / `rpc` forms and `get` return a `ResonateHandle<Object>` whose `result()` returns `Object`.

```java
String value = handle.result();   // blocks until settled, returns the decoded value
String id = handle.id().join();   // the durable promise id, once creation is confirmed
boolean done = handle.done();     // non-blocking: has the promise settled?
```

A rejected promise re-throws the application error embedded in the rejection payload — where the original exception type can be reconstructed across the durability boundary you catch it by its real type, otherwise an `ApplicationError` carrying the message is the fallback.

### The `promises` sub-client

`r.promises` is a sub-client for direct durable-promise manipulation — the building block for human-in-the-loop and external-coordination patterns, where an external party settles a promise created from inside a workflow with [`ctx.promise`](#ctx-promise).

```java
import io.resonatehq.resonate.Types.Value;

// Resolve a durable promise by id (e.g. an approval a workflow is awaiting):
r.promises.resolve("approval-1", new Value(null, "approved")).join();
```

`promises` also exposes `reject`, `cancel`, `get`, `create`, and `search`. Each returns a `CompletableFuture`, so call `.join()` (or compose with `thenApply`) to wait for it.

### The `schedules` sub-client

`r.schedule(...)` creates a schedule that periodically invokes a registered function on a cron expression:

```java
import java.util.List;
import java.util.Map;

Resonate.ResonateSchedule daily = r.schedule(
        "daily-report",      // schedule id
        "0 0 * * *",         // cron expression
        "generateReport",    // registered function name
        List.of(),           // positional args
        Map.of(),            // keyword args
        null,                // promise timeout (null = default)
        1);                  // function version

daily.delete(); // remove the schedule when no longer needed
```

The lower-level `r.schedules` sub-client (`create` / `get` / `delete` / `search`) is available for direct schedule manipulation.

Every promise a schedule fires needs a `resonate:target` tag, or no worker group receives it — the server release after v0.9.8 rejects a create without it. Cron expressions are evaluated in **UTC** with Quartz day-of-week numbering (`1` = Sunday); prefer day names like `MON-FRI`. See the [Schedules & cron reference](/reference/schedules) for the expression format, promise-ID templates, and the tags the server injects on fired promises.


`r.schedule(...)` and `r.schedules.create(...)` send empty `promiseTags`, so the server rejects the create with `400 promiseTags must include a resonate:target tag` (and on older servers the schedule fires but its promises are never dispatched). Tracked in [resonatehq/resonate-sdk-java#6](https://github.com/resonatehq/resonate-sdk-java/issues/6); this page will show the working target-routing form once the fix lands.


### `Resonate.stop`

Gracefully shuts down a Resonate instance. Stops the network connection, joins outstanding background jobs, cancels the subscription-refresh loop, and shuts down the heartbeat. Idempotent.

```java
r.stop();
```

**When to call it.** Call `stop` from any process that should exit after its work finishes — demo binaries, one-shot jobs, examples, CI tasks. Without it, the background virtual threads keep the process from exiting after `main` would otherwise return.


Calling `stop` on a worker (an RPC service, a queue consumer, or any other long-lived process) tears down the channels the worker uses to receive and hold work:

- The connection to the Resonate Server closes — the worker stops receiving dispatched tasks.
- The heartbeat loop stops — the server-side TTL on in-flight tasks expires, and the server reassigns them.
- The subscription-refresh loop is cancelled — listeners on awaited promises are no longer re-registered.

Workers should stay up; let process termination (SIGINT / SIGTERM) end the lifecycle.


## Context APIs

**How to use the Resonate Context inside Durable Functions.**

Resonate's Context enables you to invoke sub-tasks from inside a workflow.
This is how you extend the Call Graph and create a world of Durable Functions.

Each Context method returns a `ResonateFuture` immediately (the durable promise is created synchronously); you call `future.await()` to read the result. If the awaited promise is still pending, `await` suspends the workflow and re-enters it when the promise settles. Because of this, **fan-out is "dispatch all, then await all"**: call `ctx.run` / `ctx.rpc` for every branch first to create the promises, then `await` each future.

### `ctx.run`

Invoke a function in the **same process**.
By default, calling `await` immediately after executes sequentially — the workflow blocks until the invoked function returns.

```java
public static String myWorkflow(Context ctx, String input) {
    return ctx.run(Greeter::formatGreeting, input).await();
}
```

To run in parallel, dispatch every child first, then await each future:

```java
import io.resonatehq.resonate.Context.ResonateFuture;

public static String myWorkflow(Context ctx, String a, String b) {
    ResonateFuture<String> fa = ctx.run(Greeter::formatGreeting, a);
    ResonateFuture<String> fb = ctx.run(Greeter::formatGreeting, b);
    return fa.await() + " | " + fb.await();
}
```


The workflow runtime drains every `ctx.run`-spawned child future before it can suspend or settle the parent task. A function that blocks indefinitely holds the task lease open until it expires. Long-running or external-blocking work belongs in `ctx.rpc` (remote dispatch) or `ctx.promise` (latent durable promise), not `ctx.run`.


### `ctx.rpc`

Invoke a function in a **remote process**, either by method reference or by registered name.
Await on the returned future suspends the workflow until the remote function returns.

```java
public static String myWorkflow(Context ctx, String input) {
    return (String) ctx.rpc("remote-func", input).await();
}
```

The by-name form returns a `ResonateFuture<Object>` (hence the cast); pass a method reference instead for a typed future. The by-name form does **not** require the target to be registered locally — it dispatches to a function registered on the executing (remote) group. The method-reference form, by contrast, requires a **local** registration, because it recovers the target's name and version from the registry. `ctx.rpc` takes per-call options (e.g. `target`) the same way `ctx.run` does — see [Per-call options](#per-call-options). The fan-out-then-await pattern shown for `ctx.run` applies equally to `ctx.rpc`.

### `ctx.sleep`

Durable sleep. There is no limit to how long the function can sleep — hours, days, or weeks.
The sleep survives process restarts.

```java
import java.time.Duration;

public static void reminder(Context ctx) {
    ctx.sleep(Duration.ofHours(1)).await(); // no value to decode
    // ... send the reminder
}
```


Whenever a workflow suspends and resumes (after a `sleep`, a remote `rpc`, or a pending `promise`), the entire workflow body runs again from the top. Durable child promises short-circuit work that already settled, but any side effect that runs *before* reaching that boundary executes again. Wrap observable side effects (DB writes, payments, emails) in their own `ctx.run` / `ctx.rpc` so the durable promise records the result.


### `ctx.promise`

Create a latent durable promise resolved by an external system (a webhook, a human, another process). Hand the promise's ID to the external resolver; `await` suspends until it settles. This is the building block for human-in-the-loop and webhook workflows.

```java
import io.resonatehq.resonate.Context.ResonateFuture;

public static String approval(Context ctx) {
    ResonateFuture<Object> promise = ctx.promise(); // 1-day default timeout, capped at the workflow deadline
    String approvalId = promise.id();
    // hand approvalId to whoever resolves it
    // (e.g. resonate promise resolve <id> --data '"approved"', or r.promises.resolve(id, ...))

    Object decision = promise.await(); // suspends until the promise is settled externally
    return decision.toString();
}
```

`ctx.promise(Duration)` sets an explicit timeout; `ctx.promise()` uses a 1-day default, capped at the parent's remaining deadline.

### `ctx.detached`

Dispatch a remote function fire-and-forget. Unlike `ctx.rpc`, the parent workflow does **not** suspend on it — `detached` returns only the new promise's ID, and the detached execution's lifecycle is independent of the parent.

```java
public static void placeOrder(Context ctx, String orderId) {
    // Fire-and-forget: dispatch the audit workflow without blocking the order.
    String auditId = ctx.detached("writeAuditLog", orderId).id();
    // auditId references the detached execution; the parent does not await it
}
```


Unlike `ctx.run` and `ctx.rpc`, which accept either a method reference or a `String` name, `ctx.detached` takes the target function's **registered name as a `String`** — there is no method-reference overload. The detached target must be registered on whichever group executes it.


### Context accessors

Inside a workflow, `ctx.info()` exposes read-only metadata about the current execution:

```java
import io.resonatehq.resonate.Types.Info;

public static void inspect(Context ctx) {
    Info info = ctx.info();
    String id = info.id();             // this execution's promise ID
    String parent = info.parentId();   // parent promise ID
    String origin = info.originId();   // root workflow ID — stable across the whole tree
    String fn = info.funcName();       // registered function name
    long deadline = info.timeoutAt();  // promise deadline, epoch milliseconds
    // info.branchId() and info.tags() are also available
}
```

### Dependency injection

Application dependencies (database handles, HTTP clients, gateways) are registered on the instance with `withDependency` and fetched inside a function by type with `ctx.getDependency`:

```java
r.withDependency(new PaymentGateway());

public static String charge(Context ctx, int amount) {
    PaymentGateway gateway = ctx.getDependency(PaymentGateway.class);
    return gateway.submit(amount);
}
```

Dependencies are keyed by their concrete class — register at most one instance per type, before processing starts.

### Per-call options

`run` / `rpc` (both on the instance and on the Context) take their options from a fresh handle minted by `options(...)`, carrying a `Context.Opts` value. `Opts` is an immutable record with builder-style `with*` methods, so you override one field and inherit the rest:

```java
import io.resonatehq.resonate.Context.Opts;
import io.resonatehq.resonate.Retry.Constant;

public static String checkout(Context ctx) {
    return ctx.options(new Opts().withRetryPolicy(new Constant(5, 0)))
            .run(Greeter::formatGreeting, "world")
            .await();
}
```

| `Opts` field | Method | Purpose |
|---|---|---|
| `timeout` | `withTimeout(Duration)` | Caps the promise deadline (bounded by the parent's remaining deadline). |
| `target` | `withTarget(String)` | Logical routing address for `rpc`. Empty falls back to the configured group. |
| `version` | `withVersion(int)` | Selects the registered version for by-name dispatch. |
| `retryPolicy` | `withRetryPolicy(RetryPolicy)` | Per-call retry policy for a `ctx.run` leaf. See [Retries](#retries). |

The options handle is a fresh instance — the originating `Resonate` / `Context` is untouched, so held handles never interfere.

## Retries

When a function passed to `ctx.run` (or a top-level `run`) returns by throwing, Resonate re-executes it according to a retry policy. Retries apply only to **leaf** functions — a function that itself performs a durable op (`ctx.run` / `ctx.rpc` / `ctx.sleep` / `ctx.promise`) is a workflow, recovered by replay, and is never retried.

The SDK ships four policies, all implementing the `Retry.RetryPolicy` interface (delays are in **seconds**):

| Policy | Behavior |
|---|---|
| `new Retry.Exponential(delay, maxRetries, factor, maxDelay)` | Delay `delay * factor^attempt`, capped at `maxDelay`, for `maxRetries` retries. |
| `new Retry.Linear(maxRetries, delay)` | Attempt N waits `delay * N`. |
| `new Retry.Constant(maxRetries, delay)` | Fixed `delay` between attempts. |
| `new Retry.Never()` | A single attempt (no retries). |

```java
import io.resonatehq.resonate.Context.Opts;
import io.resonatehq.resonate.Retry.Exponential;

public static String chargeStep(Context ctx, int amount) {
    return ctx.options(new Opts().withRetryPolicy(
                    new Exponential(1, 5, 2, 30))) // 1s base, doubling, capped at 30s, 5 retries
            .run(Greeter::formatGreeting, "card")
            .await();
}
```

A retry policy can be set three ways, in increasing specificity:

1. **SDK-wide** — `Resonate.builder().retryPolicy(...)`, the default for every leaf.
2. **Per-function** — `register(ref, name, version, retryPolicy)`, read by the worker that executes the function.
3. **Per-call** — `ctx.options(new Opts().withRetryPolicy(...)).run(...)`, overriding the above for a single `ctx.run`.

## Defaults

The Java SDK ships with these key defaults:

- **`new Resonate()`** — in-process `LocalNetwork` (no server); `TTL = 60s`; no-op heartbeat in local mode (async at `TTL/2` in remote mode); `NoopEncryptor`; group `"default"`; `maxConcurrentTasks = 64`.
- **Top-level `run` / `rpc` timeout** — `1 day` when no per-call `timeout` is set.
- **Child `ctx.run` / `ctx.rpc` / `ctx.promise` / `ctx.sleep` timeout** — `1 day` when the call sets no `timeout`, capped at the parent's remaining deadline.
- **Default retry policy** — `Exponential(delay=1s, maxRetries=30, factor=2, maxDelay≈unbounded)` — 1-second base, doubling, 30 retries — applied to leaf functions when no more specific policy is set.

For server defaults and the TypeScript/Python/Rust comparison with source citations, see the [Defaults reference](/reference/defaults).

---

---
url: https://docs.resonatehq.io/develop/python
title: Python SDK skills
---

This page reflects `resonate-sdk` v0.7.4 (current on PyPI). Python ≥3.12 required. The remote-mode examples below need a running server (`resonate dev`, Rust server v0.9.x+); `Resonate()` without a `url` runs entirely in-process and needs no server.


Welcome to the Resonate Python SDK guide!
This SDK makes it possible to write Distributed Async Await applications with Python.
This guide covers installation and features that the SDK offers.


Looking for the API reference?

The Resonate Python SDK API reference is available [here](https://resonatehq.github.io/resonate-sdk-py/).


## Installation

**How to install the Resonate Python SDK into your project.**

The Resonate Python SDK requires **Python ≥3.12**.

To install the Resonate Python SDK, you can use any of your favorite package managers.






    

```shell
uv add resonate-sdk
```

    

    

```shell
pip install resonate-sdk
```

    

    

```shell
poetry add resonate-sdk
```

    



## Initialization

**How to initialize a Resonate Client.**

There are two ways to initialize Resonate: local (in-process, no server) and remote (connected to a Resonate server).

**Local initialization = zero-dependency development**

Local initialization means that Resonate uses local memory for promise storage.

This is ideal for getting started quickly or for integrating Resonate into an existing application without relying on external dependencies.

```py
from resonate.resonate import Resonate

resonate = Resonate()
```


Temporal, Restate, and DBOS require a server or database to get started.

Resonate enables you to get started with a local worker that stores promises in memory, no server or database required.
This makes it easy to incrementally adopt Resonate into your existing Python application.


**Remote initialization**

Remote initialization connects to a running Resonate server, enabling durable promise storage and cross-process RPC.
Start a server locally with `resonate dev`, then connect:

```py
from resonate.resonate import Resonate

resonate = Resonate(url="http://localhost:8001")
```

The `url` parameter takes precedence over the `RESONATE_URL` environment variable, which in turn takes precedence over the `RESONATE_HOST`/`RESONATE_PORT` fallback. If none of these are set, the client runs in local (in-process) mode.

To pass an auth token:

```py
from resonate.resonate import Resonate

resonate = Resonate(url="http://localhost:8001", token="your-token")
```

The `token` kwarg falls back to the `RESONATE_TOKEN` environment variable when omitted.

### Concurrency

A single Python worker process executes multiple functions concurrently inside a single asyncio event loop. The v0.7 SDK line is fully async; every durable function is an `async def` coroutine and effects are `await`ed.

See [Scaling — Worker concurrency](/deploy/scaling#worker-concurrency) for more on concurrency strategies.

## Client APIs

Registration

**How to register a function with Resonate in the Python SDK.**

There are two ways to register a function with Resonate: using the `register()` method or using the `@resonate.register` decorator.

### `@resonate.register`

**Decorator**

```py
@resonate.register
async def foo(ctx, arg):
    # ...
    return result
```

### `.register()`

**Method**

```py
async def foo(ctx, arg):
    # ...
    return result

resonate.register(foo)
```

### `.with_dependency()`

Resonate's `.with_dependency()` method allows you to store a typed dependency on the client.
You can then access the dependency in any durable function using the [`.get_dependency()`](#get_dependency) method.

Dependencies can only be added in the ephemeral world, before the system starts processing tasks.

```py
resonate.with_dependency(dependency)
```

The dependency is keyed by its concrete type and is accessible from any function in the call graph on that Application Node.
This is useful for things like database connections or other resources that you want to share across functions.

**How to invoke a function in the ephemeral world with the Resonate Class.**

To move from the ephemeral world to the durable world you use the Resonate Class to invoke functions.

There are two methods that you can use: `.run()` and `.rpc()`.

### `.run()`

Resonate's `.run()` method invokes a function in the same process and returns a handle synchronously.
You can think of it as a "run right here" invocation.
After invocation, the function is considered durable and will recover in another process if required.

```py
import asyncio
from resonate.resonate import Resonate

async def main():
    resonate = Resonate(url="http://localhost:8001")
    resonate.register(foo)
    handle = resonate.run("invocation-id", foo, arg)
    result = await handle.result()
    await resonate.stop()

asyncio.run(main())
```

### `.rpc()`

Resonate's `.rpc()` method (Remote Procedure Call) invokes a function in a remote process and returns a handle synchronously.
You can think of it as a "run somewhere else" invocation (Asynchronous Remote Procedure Call).
After invocation, the function is considered durable and will recover in another process if required.

```py
import asyncio
from resonate.resonate import Resonate

async def main():
    resonate = Resonate(url="http://localhost:8001")
    handle = resonate.rpc("invocation-id", "foo", arg)
    result = await handle.result()

    # optionally target a specific group
    handle2 = resonate.options(target="workers").rpc("invocation-id-2", "foo", arg)
    result2 = await handle2.result()
    await resonate.stop()

asyncio.run(main())
```

### `.schedule()`

Resonate's `.schedule()` method allows you to schedule a function to be invoked on a specified cron schedule.
The scheduled function will be invoked until the schedule is deleted.
`.schedule()` is async.

```py
schedule = await resonate.schedule(
    "scheduled-foo",  # schedule ID
    "0 * * * *",      # every hour, on the hour, UTC
    "foo",            # the function's registered name
    args=(1,),
    kwargs={"greeting": "hello"},
)
```

The function is addressed by its registered **name** (a string), not the function object — the worker that receives each invocation resolves the name in its own registry.
`args` and `kwargs` are the arguments every fired invocation is called with, and `promise_timeout` (a `timedelta`, default 1 day) bounds each fired execution.
All parameters can also be passed as keywords (`id=`, `cron=`, `func_name=`, ...).

Cron expressions are evaluated in **UTC**, and the day-of-week field uses Quartz numbering (`1` = Sunday) — prefer day names like `MON-FRI`. See the [Schedules & cron reference](/reference/schedules) for the expression format, promise-ID templates, and the tags the server injects on fired promises.

**Target routing.** Each promise the schedule fires carries a `resonate:target` tag that routes it to a worker group — a schedule without it is rejected by the SDK's in-process network and by newer servers, and on servers up to v0.9.8 its fired promises are silently never dispatched (see the [Schedules & cron reference](/reference/schedules#the-resonatetarget-requirement)). `.schedule()` injects the tag for you from the `target` option, falling back to the client's configured group (`default` unless set):

```py
await resonate.options(target="report-workers").schedule(
    "nightly-report",
    "0 2 * * *",
    "generate_report",
)
```

**Delete and inspect.** The returned handle deletes the schedule; the `resonate.schedules` sub-client gives you direct `create` / `get` / `delete` / `search` access:

```py
await schedule.delete()  # stop future ticks (already-fired promises are unaffected)

record = await resonate.schedules.get("nightly-report")
print(record.cron, record.promise_id)
```


On a client connected to a server (`Resonate(url=...)` or `RESONATE_URL` set), if the first awaited call your process makes is `.schedule()` — or any `.schedules.*` / `.promises.*` call — it fails with `http error: network has been stopped`: the SDK starts its network as a background task, and a script that calls straight in reaches the network before that task has run. Local mode (`Resonate()` with no URL) is unaffected. Until [resonatehq/resonate-sdk-py#443](https://github.com/resonatehq/resonate-sdk-py/issues/443) is fixed, yield to the event loop once first: `await asyncio.sleep(0)`.


### `.options()`

Options can be used preceding `.run()`, `.rpc()`, and `.schedule()` on the client.

```py
from datetime import timedelta
from resonate.retry import Exponential, Constant, Linear, Never

resonate.options(
    timeout=timedelta(seconds=60),
    target="workers",
    version=1,
).run("invocation-id", foo, arg)
```

### `.get()`

Resonate's `.get()` method allows you to subscribe to a function invocation by its promise ID.
If the invocation does not exist, an error will be thrown.
`.get()` is async.

```py
handle = await resonate.get("invocation-id")
result = await handle.result()
```

### `.promises.get()`

Resonate's `.promises.get()` method allows you to get a promise by ID.

```py
await resonate.promises.get("promise-id")
```

### `.promises.create()`

Resonate's `.promises.create()` method allows you to create a promise.

```py
import time
from resonate.types import Value

await resonate.promises.create(
    id="promise-id",
    timeout_at=int(time.time() * 1000) + 30000,  # 30s in the future, in milliseconds
    param=Value(data=None),
    tags={},
)
```

### `.promises.resolve()`

Resonate's `.promises.resolve()` method allows you to resolve a promise by ID.

This is useful for HITL use cases where you want to unblock a durable function waiting on a human action.
It works well in conjunction with the [`.promise()`](#promise) method.

```py
from resonate.types import Value

await resonate.promises.resolve(
    id="promise-id",
    value=Value(data={"approved": True}),
)
```

### `.promises.reject()`

Resonate's `.promises.reject()` method allows you to reject a promise by ID.

```py
from resonate.types import Value

await resonate.promises.reject(
    id="promise-id",
    value=Value(data={"reason": "policy violation"}),
)
```

### `.stop()`

`.stop()` performs a graceful async shutdown — it tears down the transport, heartbeat, and runtime tasks.
Call it from any process that should exit cleanly after its work finishes.

```py title="main.py"
import asyncio
from resonate.resonate import Resonate

async def main():
    resonate = Resonate(url="http://localhost:8001")
    resonate.register(greet)

    handle = resonate.run("greet-1", greet, "world")
    result = await handle.result()
    print(result)

    await resonate.stop()

asyncio.run(main())
```


Calling `.stop()` on a worker (an RPC service, a Kafka consumer, an MCP server, or any other long-lived process) tears down the channels the worker uses to receive and hold work:

- The transport connection stops — the worker stops receiving dispatched tasks.
- The heartbeat stops — the server-side TTL on in-flight tasks expires, and the server reassigns them.

The process keeps running but silently stops processing work. Workers should stay up; let process termination (SIGINT / SIGTERM) end the lifecycle.


After calling `.stop()`, the client should not be used for further operations — construct a new `Resonate` instance instead.

## Context APIs

**How to use the Resonate Context object in the Python SDK.**

Resonate's Context object enables you to invoke functions from inside a Durable Function.
This is how you extend the Call Graph and create a world of Durable Functions.
Inside a Durable Function you use the `await` keyword to interact with the Context object.

### `.get_dependency()`

Context's `.get_dependency()` method allows you to get a typed dependency that was registered in the ephemeral world using [`.with_dependency()`](#with_dependency) and use it in the Durable World.

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    dependency = ctx.get_dependency(MyDependencyType)
    # do something with the dependency
```

### `.run()`

Context's `.run()` method invokes a function in the **same process**.

Await it immediately to block until the child resolves:

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    result = await ctx.run(bar, arg)
    # do more stuff


async def bar(ctx: Context, arg):
    return
```

Invoke without awaiting to dispatch multiple children concurrently, then await them later:

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    f1 = ctx.run(bar, arg)
    f2 = ctx.run(bar, arg)
    result1 = await f1
    result2 = await f2


async def bar(ctx: Context, arg):
    return
```

### `.rpc()`

The RPC API is how you durably communicate between processes.
It is how you invoke functions in other processes and extend the Call Graph across process boundaries.

Await it immediately (synchronous-style):

```py
from resonate.context import Context

# process x
@resonate.register
async def foo(ctx: Context, arg: str) -> str:
    result = await ctx.rpc("bar", arg)
    # do more stuff


# process y
@resonate.register
async def bar(ctx: Context, arg: str) -> str:
    return
```

Invoke without awaiting to dispatch multiple RPCs concurrently, then await them later:

```py
from resonate.context import Context

# process a
@resonate.register
async def foo(ctx: Context, arg):
    f1 = ctx.rpc("bar", arg)
    f2 = ctx.rpc("bar", arg)
    result1 = await f1
    result2 = await f2

# process b
@resonate.register
async def bar(ctx: Context, arg):
    return
```

### `.detached()`

Context's `.detached()` method invokes a function in a **remote process** in a fire-and-forget manner.
Unlike holding an RPC future, the detached child's lifetime is fully decoupled from the parent —
the parent never implicitly awaits it, and the child survives the parent completing.

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    audit_future = ctx.detached("bar", arg)
    audit_id = await audit_future.id()
    # foo completes; bar keeps running independently
```

### `.options()`

Many of Context's methods support per-call options. Call `.options(...)` on the context before `.run()`, `.rpc()`, or `.detached()`.

Both local calls (`.run()`) and remote calls (`.rpc()` / `.detached()`) accept `timeout`, `target`, `version`, and `retry_policy`.

```py
from datetime import timedelta
from resonate.retry import Exponential, Constant, Linear, Never
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    result = await ctx.options(
        retry_policy=Exponential(delay=1, factor=2, max_delay=30, max_retries=10),
        timeout=timedelta(seconds=30),
    ).run(bar, arg)
```

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    result = await ctx.options(
        target="workers",
        version=1,
    ).rpc("bar", arg)
```

### `.promise()`

Context's `.promise()` method creates a durable promise that can be awaited by the calling function and resolved externally.

This is very useful for HITL (Human-In-The-Loop) use cases where you want to block progress until a human has taken an action or provided data.
It works well in conjunction with the [`.promises.resolve()`](#promisesresolve) method.

```py
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    approval = ctx.promise()          # returns a future; inherits workflow timeout
    approval_id = await approval.id() # get the externally-addressable promise ID
    # publish approval_id to a reviewer (email, Slack, dashboard, etc.)
    decision = await approval         # suspend until the external party resolves it
```

### `.sleep()`

Context's `.sleep()` method suspends the function durably for the given duration.
There is no limit to how long you can sleep.
The method accepts a `timedelta` from the standard library.

```py
from datetime import timedelta
from resonate.context import Context

@resonate.register
async def foo(ctx: Context, arg):
    await ctx.sleep(timedelta(seconds=5))  # sleep for 5 seconds
    # do more stuff
```

### Deterministic time and random values

`ctx.time` and `ctx.random` from v0.6.x have been removed. There is no replacement helper.

The v0.7 SDK line's idiom for nondeterministic values that must be stable across replay is to call the nondeterministic operation inside a **leaf function** invoked via `await ctx.run(leaf, ...)`. The leaf's return value is durably checkpointed, so replay yields the same value without re-running the leaf.

```py
import time
import random
from resonate.context import Context

async def get_timestamp(ctx: Context) -> float:
    return time.time()

async def get_random(ctx: Context) -> float:
    return random.random()

@resonate.register
async def foo(ctx: Context, arg):
    ts = await ctx.run(get_timestamp)   # checkpointed; same value on replay
    rand = await ctx.run(get_random)    # checkpointed; same value on replay
    # use ts and rand safely
```

## Defaults

The Python SDK ships with these key defaults.

- **`Resonate()`** — `group = "default"`, `log_level = logging.INFO`. URL falls back to `RESONATE_URL`, then `RESONATE_HOST`/`RESONATE_PORT`; otherwise local mode.
- **`ctx.run` / `Options`** — `timeout = timedelta(days=1)`, `target = "default"`, `version = 1`.
- **`.schedule()`** — `promise_timeout = timedelta(days=1)` per fired execution; the `resonate:target` tag falls back to the client's configured group.
- **`retry_policy`** for `ctx.run` — resolves to `Exponential(delay=1, factor=2, max_delay=2**63 - 1, max_retries=30)`.
- **`Exponential()` required fields** — `delay`, `factor`, `max_delay`, `max_retries` (all times in seconds).
- **`Constant()` / `Linear()` required fields** — `delay`, `max_retries`.


The Python SDK uses seconds for `timeout` and retry-policy delays. The TypeScript SDK uses milliseconds. The numbers do not transfer directly between the two.


For the full table, per-SDK comparison, and source citations, see the [Defaults reference](/reference/defaults).

---

---
url: https://docs.resonatehq.io/develop/rust
title: Rust SDK skills
---

The Rust SDK is at 0.6.0 and in active development. APIs may change between releases.


Whether you are a human or an AI agent, this skill guide will help you develop applications using the Resonate Rust SDK.

This skill sheet assumes that you already know Resonate is a good fit for your use case.
If you are unsure, please refer to [Why Resonate](/evaluate/why-resonate#the-three-pillars).

It's important to think about the potential architecture of your application as it ties to your use case.
This can determine which APIs and options you will use for function activations.
If you have a use case in mind, but haven't built with Resonate before, we recommend reviewing some of the common patterns in our [example applications](/get-started/examples).

## Installation

**How to install the Resonate Rust SDK into your project.**

The Rust SDK is published on crates.io as `resonate-sdk`. Add it to your `Cargo.toml`:

```toml title="Cargo.toml"
[dependencies]
resonate = { package = "resonate-sdk", version = "0.6" }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
```

To track the latest unreleased changes instead, depend on the `main` branch directly:

```toml
resonate = { package = "resonate-sdk", git = "https://github.com/resonatehq/resonate-sdk-rs", branch = "main" }
```

Once added, you can import the Resonate prelude and start using the SDK:

```rust
use resonate::prelude::*;
```

## Initialization

**How to initialize a Resonate Client.**

Initializing a Resonate instance gives you the APIs needed to register, activate, and await durable functions.

```rust title="main.rs"
use resonate::prelude::*;

let resonate = Resonate::new(ResonateConfig::default());
```

- A Resonate instance can connect to either an in-memory local store (best for development) or a remote Resonate Server (best for production).
- A Resonate instance can only be used in the Ephemeral World to register and activate functions — it cannot be used inside Durable Functions. Use the Context APIs for function activations inside Durable Functions.

Upon initialization, the Resonate instance will look for [environment variables](#environment-variables) and/or use the options passed via `ResonateConfig`.

```rust title="main.rs"
use resonate::prelude::*;

let resonate = Resonate::new(ResonateConfig {
    url: Some("http://localhost:8001".into()),
    group: Some("worker-group-a".into()),
    ..Default::default()
});
```

### Zero-dependency development

Unlike other Durable Execution offerings, apart from installing the SDK itself, Resonate enables you to get started without any additional dependencies.
This is because Resonate can run in a local development mode that uses in-memory storage for promises and tasks.

```rust title="main.rs"
use resonate::prelude::*;

let resonate = Resonate::local();
```

Local development mode can be suitable for awhile.
However, when you want to run multiple worker processes, persist state across restarts, or share work between machines, you will need to connect to a Resonate Server.
See the [Quickstart guide](/get-started/quickstart) or [How to run a Resonate Server](/deploy/run-server) for guidance on getting a server up and running.

### Postgres-backed durable execution

Alongside the in-memory local network and a remote Resonate Server, the Rust SDK can run durable execution directly on **Postgres** — with no separate Resonate Server process. The Resonate protocol runs as stored procedures in a `resonate` schema in your database (see [resonate-pg](https://github.com/resonatehq/resonate-pg)), and your workers talk to Postgres directly.

Add the Postgres network crate alongside the SDK:

```toml title="Cargo.toml"
[dependencies]
resonate = { package = "resonate-sdk", version = "0.6" }
resonate-postgres = { package = "resonate-sdk-postgres", version = "0.6" }
```

Apply the `resonate.sql` schema (from [resonate-pg](https://github.com/resonatehq/resonate-pg)) to a Postgres 16+ database, then wire a `PostgresNetwork` into the Resonate instance:

```rust title="main.rs"
use std::sync::Arc;
use resonate::prelude::*;
use resonate_postgres::PostgresNetwork;

// Pass your Postgres connection string (for example, from the DATABASE_URL environment variable).
let network = PostgresNetwork::builder("postgres://localhost:5432/mydb")
    .group("workers")
    .build();

let resonate = Resonate::new(ResonateConfig {
    network: Some(Arc::new(network)),
    ..Default::default()
});
```

Workers receive dispatched work over Postgres `LISTEN`/`NOTIFY` (with a periodic fallback poll), and due timers advance whenever a worker is running. Because there is no standalone server process, **durable sleeps and timeouts advance only while at least one worker is connected** — with every worker down, they are suspended until a worker reconnects (a standalone Resonate Server advances timers on its own). This keeps the durable-execution stack on infrastructure you already run, with Postgres handling promise state and routing — a good fit for serverless and Postgres-centric deployments.

Like the SDK itself, `resonate-sdk-postgres` is pre-1.0 and in active development; its API may change between releases.

### Authentication

The Rust SDK supports token-based authentication (JWT) when connecting to a secured Resonate Server.

```rust title="main.rs"
use resonate::prelude::*;

let resonate = Resonate::new(ResonateConfig {
    url: Some("https://localhost:8001".into()),
    token: std::env::var("RESONATE_TOKEN").ok(),
    ..Default::default()
});
```





### Environment variables

The Resonate constructor automatically inspects a handful of environment variables when instantiating the SDK.

**Resolution order**

When a Resonate instance is created, explicit `ResonateConfig` fields always win.
If a field is not provided, the SDK looks for related environment variables before falling back to built-in defaults.

The following order is used when determining the remote endpoint:

1. `url` field supplied to `ResonateConfig`.
2. `RESONATE_URL` environment variable.
3. `RESONATE_HOST` and `RESONATE_PORT` environment variables.
4. Built-in local development mode (no remote network).


If neither a config field nor environment variable produces a URL, the SDK falls back to a local in-memory network.
This is convenient for unit tests or quick experiments that do not require a Resonate server.


#### `RESONATE_URL`

- Provides the full base URL (scheme, host, and port) for connecting to a remote Resonate server.
- Default is _unset_
- Example:

  ```bash
  export RESONATE_URL="http://localhost:8001"
  ```

  ```rust
  let resonate = Resonate::new(ResonateConfig::default()); // picks up RESONATE_URL
  ```

#### `RESONATE_HOST`

- Hostname or IP address of the remote Resonate server.
- Default is _unset_.

#### `RESONATE_PORT`

- Port number of the Resonate server.
  Ignored if `RESONATE_URL` is provided.
- Default is `8001`.

#### `RESONATE_TOKEN`

- JWT token for authenticated requests.
- Default is _unset_ (anonymous requests).

#### `RESONATE_SCHEME`

- URL scheme used when constructing the server URL from `RESONATE_HOST` and `RESONATE_PORT`.
- Default is `http`.

#### `RESONATE_PREFIX`

- Prefix prepended to all promise and task IDs.
  Useful for namespacing in multi-tenant environments.
- Default is _empty_.

## Defining durable functions

**How to annotate functions with `#[resonate::function]`.**

The `#[resonate::function]` attribute macro transforms a regular async function into a durable function.
The SDK detects the function kind from the first parameter:

| First parameter | Kind | What it means |
|---|---|---|
| `&Context` | **Workflow** | Can orchestrate sub-tasks via `ctx.run()`, `ctx.rpc()`, `ctx.sleep()` |
| `&Info` | **Leaf with metadata** | Read-only access to execution metadata (ID, parent, tags) |
| *(anything else)* | **Pure leaf** | Stateless computation — no special environment |

All durable functions must return `Result<T>` (where `Result` is `resonate::error::Result`).

```rust
use resonate::prelude::*;

// Workflow — orchestrates sub-tasks
#[resonate::function]
async fn my_workflow(ctx: &Context, input: String) -> Result<String> {
    let result = ctx.run(my_leaf, input).await?;
    Ok(result)
}

// Pure leaf — stateless computation
#[resonate::function]
async fn my_leaf(input: String) -> Result<String> {
    Ok(format!("Processed: {input}"))
}

// Leaf with metadata — access to execution info
#[resonate::function]
async fn my_info_leaf(info: &Info, input: String) -> Result<String> {
    Ok(format!("ID: {}, Input: {input}", info.id()))
}
```

You can also override the registered name:

```rust
#[resonate::function(name = "custom-name")]
async fn my_func() -> Result<()> {
    Ok(())
}
```

## Client APIs

The following Client APIs can only be used in the Ephemeral World — they cannot be used inside Durable Functions.

### `.register()`

Register a durable function to expose it to the Resonate system.
A registered function can then be activated by the Resonate Client, the Resonate CLI, or from inside another Durable Function using the Context APIs.

```rust
resonate.register(my_workflow).unwrap();
resonate.register(my_leaf).unwrap();
```

### `.run()`

Resonate's `.run()` method invokes a function in the same process and returns the result.
You can think of it as a "run right here" invocation.
After invocation, the function is considered durable and will recover in another process if required.

```rust
let result: String = resonate.run("invocation-id", my_workflow, "input".into()).await?;
```

The builder supports options before awaiting:

```rust
use std::time::Duration;

let result: String = resonate
    .run("invocation-id", my_workflow, "input".into())
    .timeout(Duration::from_secs(60))
    .await?;
```

### `.rpc()`

Resonate's `.rpc()` method (Remote Procedure Call) invokes a function in a remote process and returns the result.
You can think of it as a "run somewhere else" invocation.

```rust
let result: String = resonate.rpc("invocation-id", "my_workflow", "input").await?;
```

The builder supports `.timeout()`, `.version()`, `.tags()`, and `.target()`:

```rust
let result: String = resonate
    .rpc("invocation-id", "my_workflow", "input")
    .target("poll://any@workers")
    .await?;
```

### `.schedule()`

Schedule a function to be invoked on a cron schedule.

```rust
let schedule = resonate
    .schedule("my-schedule", "0 * * * *", "my_workflow", "input")
    .await?;

// Later, delete the schedule
schedule.delete().await?;
```

### `.get()`

Get a handle to an existing execution by its promise ID.

```rust
let handle = resonate.get::<String>("invocation-id").await?;
let result = handle.result().await?;
```

### `.promises`

The `.promises` sub-client lets you work directly with durable promises — useful for human-in-the-loop workflows, external coordination, and any pattern where you need to create a promise now and settle it later from a different process.

```rust
use resonate::types::Value;
use serde_json::json;
use std::collections::HashMap;

// Create a promise with a timeout, initial parameter, and tags
// timeout_at is i64 milliseconds since the Unix epoch
// param is a Value; tags are a HashMap<String, String>
resonate.promises.create("promise-id", timeout_at, Value::from_serializable(json!({}))?, HashMap::new()).await?;

// Get a promise by ID
let promise = resonate.promises.get("promise-id").await?;

// Resolve a promise (value is serialized into the promise record)
resonate.promises.resolve("promise-id", Value::from_serializable(json!("approved"))?).await?;

// Reject a promise
resonate.promises.reject("promise-id", Value::from_serializable(json!("denied"))?).await?;

// Cancel a promise (settles as "rejected_canceled")
resonate.promises.cancel("promise-id", Value::from_serializable(json!(null))?).await?;
```

### `.stop()`

Gracefully shuts down a Resonate Client. Closes the connection to the Resonate Server, stops the heartbeat loop, and aborts the subscription refresh task.

```rust
resonate.stop().await?;
```

**When to call it.** Call `.stop()` from any process that should exit after its work finishes — demo binaries, one-shot jobs, examples, CI tasks. Without it, the background tasks keep the Tokio runtime alive and the process hangs after `main` returns.

```rust title="src/main.rs"
#[tokio::main]
async fn main() {
    let resonate = Resonate::local();
    resonate.register(greet).unwrap();

    let result: String = resonate.run("greet-1", greet, "world".into()).await.unwrap();
    println!("{result}");

    // Required for the process to exit.
    resonate.stop().await.unwrap();
}
```


Calling `.stop()` on a worker (an RPC service, a Kafka consumer, an MCP server, or any other long-lived process) tears down the channels the worker uses to receive and hold work:

- The connection to the Resonate Server closes — the worker stops receiving dispatched tasks.
- The heartbeat loop stops — the server-side TTL on in-flight tasks expires, and the server reassigns them.
- The subscription refresh task is aborted — listeners on awaited promises are no longer re-registered.

The worker keeps running but silently stops processing work. Workers should stay up; let process termination (SIGINT / SIGTERM) end the lifecycle.


**Between debug runs, stop the previous client.** If you keep starting fresh workers in the same process group without stopping the previous one, the old workers keep heartbeating and still hold task leases — they will pick up new dispatches and produce surprising routing. Call `.stop()` in a shutdown hook so leases release cleanly.

After calling `.stop()`, the client should not be used for further operations — construct a new `Resonate` instance instead.

## Context APIs

**How to use the Resonate Context inside Durable Functions.**

Resonate's Context enables you to invoke sub-tasks from inside a workflow.
This is how you extend the Call Graph and create a world of Durable Functions.

### `ctx.run()`

Invoke a function in the **same process**.
By default, `.await` executes sequentially — the calling function blocks until the invoked function returns.

```rust
#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<String> {
    let result = ctx.run(my_leaf, "input".into()).await?;
    Ok(result)
}
```

Use `.spawn()` to run in parallel and get a `DurableFuture` handle:

```rust
#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<(String, String)> {
    let future_a = ctx.run(process, "a".into()).spawn()?;
    let future_b = ctx.run(process, "b".into()).spawn()?;

    let result_a = future_a.await?;
    let result_b = future_b.await?;

    Ok((result_a, result_b))
}
```

### `ctx.rpc()`

Invoke a function in a **remote process** (by registered name).
The calling function blocks until the remote function returns.

```rust
#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<String> {
    let result = ctx.rpc::<String>("remote-func", "input").await?;
    Ok(result)
}
```

Use `.spawn()` for parallel remote invocations:

```rust
#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<()> {
    let f1 = ctx.rpc::<String>("worker-a", "data").spawn()?;
    let f2 = ctx.rpc::<String>("worker-b", "data").spawn()?;

    f1.await?;
    f2.await?;

    Ok(())
}
```

### `ctx.sleep()`

Durable sleep. There is no limit to how long the function can sleep — hours, days, or weeks.
The sleep survives process restarts.

```rust
use std::time::Duration;

#[resonate::function]
async fn reminder(ctx: &Context, user_id: String) -> Result<()> {
    // Sleep for one hour without blocking the worker
    ctx.sleep(Duration::from_secs(3600)).await?;

    ctx.rpc::<()>("send-notification", user_id).await?;
    Ok(())
}
```

### Builder options

All Context execution methods support builder options before `.await` or `.spawn()`:

```rust
use std::time::Duration;

#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<String> {
    let result = ctx.run(my_leaf, "input".into())
        .timeout(Duration::from_secs(30))
        .await?;
    Ok(result)
}
```

| Method | Description |
|---|---|
| `.timeout(Duration)` | Execution timeout |
| `.target(&str)` | Target worker group — only valid on `ctx.rpc()` builders |





### Context accessors

Inside a workflow, the Context provides read-only metadata:

```rust
#[resonate::function]
async fn my_workflow(ctx: &Context) -> Result<()> {
    println!("Execution ID: {}", ctx.id());
    println!("Parent ID: {}", ctx.parent_id());
    println!("Origin ID: {}", ctx.origin_id());
    println!("Function name: {}", ctx.func_name());
    println!("Timeout at: {}", ctx.timeout_at());
    Ok(())
}
```

## Defaults

The Rust SDK ships with these key defaults:

- **`Resonate::local()`** — `pid = "default"`, `group = "default"`, `ttl = u64::MAX` (no expiry, local mode).
- **`Resonate::new(ResonateConfig::default())`** — `ttl = 60_000 ms` (remote mode). URL falls back to `RESONATE_URL`, then `RESONATE_HOST` + `RESONATE_SCHEME` ("http") + `RESONATE_PORT` ("8001").
- **`Options::default()`** — `target = "default"`, `timeout = Duration::from_secs(86_400)` (24 h), `version = 0`, `tags = HashMap::new()`.


The Rust `Options` struct does **not** carry a `retry_policy` field. Retry behaviour for Rust workers is governed server-side by the `--tasks-retry-timeout` flag (default `30_000 ms`). This is a known asymmetry with the TypeScript and Python SDKs, both of which support per-`ctx.run` retry policies.


For the full table, per-SDK comparison, and source citations, see the [Defaults reference](/reference/defaults).

---

---
url: https://docs.resonatehq.io/develop/typescript
title: TypeScript SDK skills
---

This page reflects `@resonatehq/sdk` v0.11.4 (current on npm). APIs are subject to change in future releases.



Since v0.11.0, the SDK ships two interchangeable engines: the **generator engine** (`function*` with `yield* ctx.run(fn)`, documented throughout this page) and an **async/await engine** where workflows are ordinary `async` functions and durable steps are `await ctx.run(myFn, ...args)`. The async engine is imported from `@resonatehq/sdk/async`. See [Async/await engine](#asyncawait-engine) at the end of this page for a full walkthrough and migration guide.


**Requires Node.js 22 or later and npm 10 or later.**

Whether you are a human or an AI agent, this skill guide will help you develop applications using the Resonate TypeScript SDK.
Though this _is_ a skill guide, and not a detailed API reference and you will still likely need to refer to the detailed [Resonate TypeScript SDK API reference](https://resonatehq.github.io/resonate-sdk-ts/) for type definitions, defaults, and other technical details.

This skill sheet assumes that you already know Resonate is a good fit for your use case.
If you are unsure, please refer to [Why Resonate](/evaluate/why-resonate#the-three-pillars).

It's important to think about the potential architecture of your application as it ties to your use case.
This can determine which APIs and options you will use for function activations.
If you have a use case in mind, but haven't built with Resonate before, we recommend reviewing some of the common patterns in our [example applications](/get-started/examples).

## Installation

**How to install the Resonate Typescript SDK into your project.**

To install the Resonate Typescript SDK, you can use any of your favorite package managers.






    

```shell
bun add @resonatehq/sdk
```

    

    

```shell
npm install @resonatehq/sdk
```

    

    

```shell
yarn add @resonatehq/sdk
```

    



Once installed, you can import the Resonate SDK into your TypeScript files, and start using the Resonate Client.

## Initialization

**How to initialize a Resonate Client.**

Initializing a Resonate Client gives you the APIs needed to register, activate, and await on functions.

```ts title="index.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();
```

- A Resonate Client can connect to either an in-memory local store and message source (best for development), or a remote store and message sources (best for moving out of development).
- You can only have one Resonate Client per process.
- A Resonate Client can only be used in the Ephemeral World to register and activate functions, it cannot be used inside Durable Functions.
  Use the Context APIs for function activations inside Durable Functions.

Upon initialization, the Resonate Client will look for [environment variables](#environment-variables) and/or use the options passed to it.
For example, to specify a Resonate Server and process group, pass the url and group in the options.

```ts title="index.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  // ...
  url: "https://localhost:8001", // Resonate Server URL
  group: "worker-group-a", // Process group name
  // ...
});
```

For a comprehensive list of Resonate Client defaults, see [https://resonatehq.github.io/resonate-sdk-ts/classes/Resonate.html#constructor](https://resonatehq.github.io/resonate-sdk-ts/classes/Resonate.html#constructor).

### Zero-dependency development

Unlike other Durable Execution offerings, apart from installing the SDK itself, Resonate enables you to get started without any additional dependencies.
This is because Resonate can run in a local development mode that uses in-memory storage for promises and tasks.

This is ideal for getting started quickly or for integrating Resonate into an existing application without relying on dependencies.

Resonate will automatically operate in "local development mode" when no URL is provided via constructor options or [environment variables](#environment-variables).

```ts title="index.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();
```

Local development mode can be suitable for awhile.
However, when you want to run multiple worker processes, persist state across restarts, or share work between machines, you will need to connect to a Resonate Server.
See the [Quickstart guide](/get-started/quickstart) or [How to run a Resonate Server](/deploy/run-server) for guidance on getting a server up and running.

### Postgres-backed durable execution

Alongside the in-memory local network and a remote Resonate Server, the TypeScript SDK can run durable execution directly on **Postgres** — with no separate Resonate Server process.
The Resonate protocol runs as stored procedures in a `resonate` schema in your database (see [resonate-pg](https://github.com/resonatehq/resonate-pg)), and your workers talk to Postgres directly.

The Postgres network ships as a separate package export and connects through [`pg`](https://www.npmjs.com/package/pg), which is a peer dependency — install it alongside the SDK:

```shell
npm install @resonatehq/sdk pg
```

Apply the `resonate.sql` schema (from [resonate-pg](https://github.com/resonatehq/resonate-pg)) to a Postgres 16+ database, then wire a `PostgresNetwork` into the Resonate Client:

```ts title="index.ts"
import { Resonate } from "@resonatehq/sdk";
import { PostgresNetwork } from "@resonatehq/sdk/postgres";

// Pass your Postgres connection string (for example, from the DATABASE_URL environment variable).
const network = new PostgresNetwork({
  connectionString: process.env.DATABASE_URL ?? "postgres://localhost:5432/mydb",
  group: "workers", // a task targets the group (anycast); defaults to "default"
});

const resonate = new Resonate({ network });
```

`PostgresNetwork` also accepts `pid` (this process's id, which callbacks and listeners target directly; defaults to a random id), `tickMs` (the fallback poll interval, in milliseconds), and `logger`.

Both execution engines work over the Postgres network — pass the same `network` option to the `Resonate` class from [`@resonatehq/sdk/async`](#asyncawait-engine).

Workers receive dispatched work over Postgres `LISTEN`/`NOTIFY` (with a periodic fallback poll, so a missed notification still gets picked up), and due timers advance whenever a worker is running.
Because there is no standalone server process, **durable sleeps and timeouts advance only while at least one worker is connected** — with every worker down, they are suspended until a worker reconnects (a standalone Resonate Server advances timers on its own).
This keeps the durable-execution stack on infrastructure you already run, with Postgres handling promise state and routing — a good fit for serverless and Postgres-centric deployments.

Like the SDK itself, the Postgres network is pre-1.0 and in active development; its API may change between releases.

### Authentication

The TypeScript SDK authenticates to a secured Resonate Server with a **token**.

#### Token-based authentication

Use JWT bearer tokens for production deployments:

```ts title="index.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "https://localhost:8001",
  token: process.env.RESONATE_TOKEN, // Load from environment
});
```






Earlier releases accepted `auth: { username, password }` and read `RESONATE_USERNAME` / `RESONATE_PASSWORD`, sending an `Authorization: Basic` header.
That was removed in **v0.10.0** along with the rest of the networking rewrite, and the constructor now ignores unknown options rather than rejecting them.
An `auth` block carried forward from v0.9.x therefore raises no error — the client simply sends unauthenticated requests. Replace it with `token`.


### Concurrency

A single TypeScript worker handles multiple tasks concurrently on the Node.js event loop.
When the server dispatches tasks to a worker, each one starts executing immediately — tasks do not queue behind each other.
There is no concurrency limit configuration; all tasks run concurrently via `async/await`.

This is efficient for I/O-bound work but means CPU-intensive tasks will block the event loop and starve other in-flight tasks.
If your worker holds in-process state that cannot be shared across tasks, consider running multiple single-purpose worker processes instead.

See [Scaling — Worker concurrency](/deploy/scaling#worker-concurrency) for concurrency strategies and patterns for stateful workers.

### Message sources

A Resonate Client receives messages by making HTTP Long Polling requests to a Resonate Server.
The messages tell the client/sdk what to work on next.

You can customize the transport by which the client receives messages using a transport plugin.
See [Message transports](/deploy/message-transports) for the transports the current server ships.

### Consuming Kafka with Resonate

**Example: Kafka worker.** Kafka is the most common message-broker integration ask, so we ship a complete reference implementation. The pattern below works for any message broker — substitute your client library, keep the `resonate.beginRun(messageId, "workflow", ...)` shape.

There is no native Kafka transport in the current server. The supported pattern is a normal Kafka consumer that dispatches a Resonate workflow per message — a stable per-message identifier becomes the durable promise ID, so duplicate deliveries reconnect to the in-flight execution rather than starting over.

```ts title="src/consumer.ts"
import { Kafka } from "kafkajs";
import { resonate } from "./workflow";

const kafka = new Kafka({ brokers: ["localhost:9092"] });
const consumer = kafka.consumer({ groupId: "workers" });

await consumer.connect();
await consumer.subscribe({ topic: "records_to_process", fromBeginning: true });

await consumer.run({
  eachMessage: async ({ topic, partition, message }) => {
    // topic-partition-offset uniquely identifies the message even when no key is set
    const messageId = `${topic}-${partition}-${message.offset}`;
    // messageId is the durable promise id — duplicate invocations dedupe.
    await resonate.beginRun(messageId, "workflow", messageId, message.offset);
  },
});
```

If your producer sets a stable message key (or your payload carries a domain ID), that's an equally valid promise ID — pick whichever uniquely identifies the logical message.

The full example, with the workflow definition and a runnable Redpanda compose file, lives at [resonatehq-examples/example-kafka-worker-ts](https://github.com/resonatehq-examples/example-kafka-worker-ts) — see also the [Kafka worker example page](/get-started/examples/kafka-worker) for a side-by-side TypeScript / Python / Rust walkthrough.

→ Full guide: [Kafka integration](/deploy/kafka)


Native `kafka://` transport is specified in the [Message Passing Protocol](https://distributed-async-await.io/spec/execution-model/message-passing#address-schemes) and on the roadmap. This page will gain a transport-plugin section once it ships.


### Environment Variables

The Resonate client constructor automatically inspects a handful of environment variables when instantiating the SDK.

**Resolution order**

When a Resonate Client is instantiated, explicit constructor arguments always win.
If an argument is not provided, the client looks for related environment variables before falling back to built-in defaults.

The following order is used when determining the remote endpoint:

1. `url` argument supplied to the constructor.
2. `RESONATE_URL` environment variable.
3. `RESONATE_SCHEME`, `RESONATE_HOST`, and `RESONATE_PORT` environment variables.
4. Built-in local development mode (no remote network).


If neither an argument nor environment variable produces a URL, the client falls back to a local in-memory network.
This is convenient for unit tests or quick experiments that do not require a Resonate server.


#### `RESONATE_URL`

- Provides the full base URL (scheme, host, and port) for connecting to a remote Resonate server.
  Takes precedence over the individual scheme/host/port variables.
- Default is _unset_
- Example, compose from a single URL:

  ```bash
  export RESONATE_URL="https://resonate.example.com"
  ```

  ```ts
  import { Resonate } from "@resonatehq/sdk";

  const resonate = new Resonate(); // picks up RESONATE_URL automatically
  ```

- Example, compose a URL from components:

  ```bash
  export RESONATE_SCHEME=https
  export RESONATE_HOST=resonate.example
  export RESONATE_PORT=8443
  ```

  ```ts
  const resonate = new Resonate();
  // resolves to https://resonate.example:8443
  ```

#### `RESONATE_SCHEME`

- Scheme to use when `RESONATE_URL` is unset and a host is supplied.
  Combine with `RESONATE_HOST` (required) and `RESONATE_PORT` (optional) to build the full URL.
- Default is _http_.

#### `RESONATE_HOST`

- Hostname or IP address of the remote Resonate server.
  Must be present to use the scheme/host/port fallback path.
- Default is _unset_.

#### `RESONATE_PORT`

- Port number to use when building the URL from scheme/host/port.
  Ignored if `RESONATE_URL` is provided.
- Default is `8001`.

**Troubleshooting tips**

- Prefer passing constructor arguments when bootstrapping in application code that owns configuration loading.
  Environment variables are ideal for CLI usage, tests, or infrastructure-managed settings.
- Always set `RESONATE_HOST` if you intend to rely on the scheme/host/port combination.
  Without a host the client will treat the configuration as missing and default to local mode.

## Client APIs

The following client APIs can only be used in the Ephemeral World, they can not be used inside Durable Functions.

### `.register()`

Register a function to expose it to the Resonate system.
A registered function can then be activated using by the Resonate Client, Resonate CLI, or from inside another Durable Function using the Context APIs.

```ts
function foo(ctx: Context, ...args: any[]) {
  // ...
  return result;
}

resonate.register(foo);

// or alternatively
resonate.register("foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});
```

You can specify a name for the function that is different from the function name by passing it as the first argument.

```ts
resonate.register("custom-foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});
```

Registration does provide a stub that can be used to activate the function locally, ranther than using the run or rpc methods on the Resonate Client.

```ts
const fooStub = resonate.register("foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});

fooStub.run(promiseId, args);
```

### `.setDependency()`

Resonate's `.setDependency()` method enables you to set a dependency for other functions in the local call graph to use.

```ts
resonate.setDependency("dependency-name", dependency);
```

- Setting a dependency can only be done in the Ephemeral World.
- It is useful for sharing resources like database connections across functions.
- You can then access the dependency inside a Durable Function using Context's [`.getDependency()`](#getdependency) method.

### `.run()`

Resonate's `.run()` method invokes a function in the same process and returns the result.
You can think of it as a "run right here" invocation.
After invocation, the function is considered durable and will recover in another process if required.

```ts
const result = await resonate.run("invocation-id", foo, ...args);
```

### `.beginRun()`

Similar to `.run()` but instead of returning the result, returns a handle so the result can be awaited later.

```ts
const handle = await resonate.beginRun("invocation-id", foo, ...args);
const result = await handle.result();
```

### `.rpc()`

Resonate's `.rpc()` method (Remote Procedure Call) invokes a function in a remote process and returns the result.
You can think of it as a "run somewhere else" invocation (Asynchronous Remote Procedure Call).
After invocation, the function is considered durable and will recover in another process if required.

```ts
// worker.ts
resonate.register("foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});
```

```ts
// client.ts
const result = await resonate.rpc(
  "invocation-id",
  "foo",
  ...args,
  resonate.options({
    target: "poll://any@workers",
  })
);
```

### `.beginRpc()`

Similar to `.rpc()` but instead of returning the result, returns a handle so the result can be awaited later.

```ts
const handle = await resonate.beginRpc(
  "invocation-id",
  "foo",
  ...args,
  resonate.options({
    target: "poll://any@workers",
  })
);
const result = await handle.result();
```

### `.schedule()`

Resonate's `.schedule()` method allows you to schedule a function to be invoked on a specified cron schedule.
The scheduled function will be invoked until the schedule is deleted.

```ts
const schedule = await resonate.schedule(
  "scheduled-foo",
  "0 * * * *", // every hour, on the hour, UTC
  foo,
  ...args
);
```

Cron expressions are evaluated in **UTC**, and the day-of-week field uses Quartz numbering (`1` = Sunday) — prefer day names like `MON-FRI`. See the [Schedules & cron reference](/reference/schedules) for the expression format, promise-ID templates, and the tags the server injects on fired promises.

**Target routing.** Each promise the schedule fires carries a `resonate:target` tag that routes it to a worker group — without it, fired promises are never dispatched to any worker (and the server release after v0.9.8 rejects the call outright; see [Schedules & cron reference](/reference/schedules)). `.schedule()` injects the tag for you from the `target` option (as the final argument, same as `.run()`/`.rpc()`), defaulting to the `default` group:

```ts
await resonate.schedule(
  "nightly-report",
  "0 2 * * *",
  generateReport,
  resonate.options({ target: "poll://any@report-workers" })
);
```

**Delete and inspect.** The returned handle deletes the schedule; the `resonate.schedules` sub-client gives you direct `get` / `create` / `delete` access:

```ts
await schedule.delete(); // stop future ticks (already-fired promises are unaffected)

const record = await resonate.schedules.get("nightly-report");
console.log(record.nextRunAt);
```

### `.options()`

Options can be used with `.run()`, `.beginRun()`, `.rpc()`, `.beginRpc()`, and `.schedule()` as the final argument.

```ts
await resonate.run(
  "invocation-id",
  foo,
  ...args,
  resonate.options({
    timeout: 60_000, // 1 minute in ms
    target: "poll://any@workers",
    tags: { key: "value" },
  })
);
```

Local calls (`.run()` / `.beginRun()`) also accept `nonRetryableErrors`, an array of error class constructors that should not be retried by Resonate's retry policy.
When the invoked function throws an instance of any listed class (or a subclass), Resonate skips the retry policy and rejects the call with the thrown error.

```ts
class ValidationError extends Error {}

await resonate.run(
  "invocation-id",
  foo,
  ...args,
  resonate.options({
    nonRetryableErrors: [ValidationError],
  })
);
```

### `.get()`

Resonate's `.get()` method allows you to subscribe to a function invocation.
If the function invocation does not exist, an error will be thrown.

```ts
const handle = await resonate.get("invocation-id");
const result = await handle.result();
```

### `.promises.get()`

Resonate's `.promises.get()` method allows you to get a promise by ID.

```ts
const p = await resonate.promises.get("promise-id");
```

### `.promises.create()`

Resonate's `.promises.create()` method allows you to create a promise.

```ts
await resonate.promises.create(
  "promise-id",
  Date.now() + 30000 // 30 seconds in the future
);
```

### `.promises.resolve()`

Resonate's `.promises.resolve()` method settles a promise by ID into the `resolved` terminal state.

This is useful for HITL use cases where you want to wait for a human to approve a function execution.
It works well in conjunction with the [`.promise()`](#promise) method.

```ts
await resonate.promises.resolve(
  id: string,
  options?: { data?: string; headers?: Record<string, string> }
);
```

Examples:

```ts
// Resolve a promise (optionally with data)
await resonate.promises.resolve("promise-id");
await resonate.promises.resolve("promise-id", {
  data: JSON.stringify({ approved: true }),
});
```

### `.promises.reject()`

Resonate's `.promises.reject()` method settles a promise by ID into the `rejected` terminal state.

```ts
await resonate.promises.reject(
  id: string,
  options?: { data?: string; headers?: Record<string, string> }
);
```

Examples:

```ts
// Reject a promise (optionally with data describing the failure)
await resonate.promises.reject("promise-id");
await resonate.promises.reject("promise-id", {
  data: JSON.stringify({ reason: "denied" }),
});
```

### `.promises.cancel()`

Resonate's `.promises.cancel()` method settles a promise by ID into the `rejected_canceled` terminal state.

```ts
await resonate.promises.cancel(
  id: string,
  options?: { data?: string; headers?: Record<string, string> }
);
```

Example:

```ts
// Cancel a promise
await resonate.promises.cancel("promise-id");
```

### `.stop()`

Gracefully shuts down a Resonate Client. Closes the long-polling connection to the Resonate Server, stops the heartbeat loop, and clears the subscription refresh interval.

```ts
await resonate.stop();
```

`.stop()` returns a `Promise<void>` and **must be awaited**.

**When to call it.** Call `.stop()` from any process that should exit after its work finishes — demo scripts, one-shot jobs, examples, CI tasks. Without it, the client keeps the Node.js event loop alive via the long-poll connection and the subscription refresh interval, and the process hangs after `main()` returns.

```ts title="src/index.ts"
import { Resonate } from "@resonatehq/sdk";

async function main() {
  const resonate = new Resonate();
  resonate.register("greet", (ctx, name) => `Hello, ${name}!`);

  const result = await resonate.run("greet-1", "greet", "world");
  console.log(result);

  // Required for the process to exit.
  await resonate.stop();
}

main();
```


Calling `.stop()` on a worker (an RPC service, a Kafka consumer, an MCP server, or any other long-lived process) tears down the very channels the worker uses to receive and hold work:

- The long-polling connection to the Resonate Server closes — the worker stops receiving dispatched tasks.
- The heartbeat loop stops — the server-side TTL on in-flight tasks expires, and the server reassigns them.
- The subscription refresh interval stops — listeners on awaited promises are no longer re-registered.

The worker keeps running but silently stops processing work. Workers should stay up; let process termination (SIGINT / SIGTERM) end the lifecycle.


**Common pitfalls.**

- **Don't reuse the client after `.stop()`.** The transport is closed and the refresh interval is gone. Subsequent calls do not throw, but they will not behave correctly. Construct a new `Resonate` instance instead.
- **Always `await` the call.** The unawaited form (`resonate.stop();`) starts the shutdown and discards the returned promise. Node drains the microtasks before exit, so a script that has nothing after the stop call still exits, but any code that follows — another `await`, a second `resonate.run()`, a `process.exit(0)` — runs against an in-flight teardown. Tests in the SDK uniformly use `await resonate.stop()`; match that.
- **Between debug runs, stop the previous client.** If you keep starting fresh workers in the same process group without stopping the previous one, the old workers still hold task leases and will pick up new work, producing surprising routing.

## Context APIs

**How to use the Resonate Context object in the TypeScript SDK.**

Resonate's Context object enables you to invoke functions from inside a Durable Function.
This is how you extend the Call Graph and create a world of Durable Functions.
Inside a Durable Function you use the `yield*` keyword to interact with the Context object.

### `.getDependency()`

Context's `.getDependency()` method allows you to get a dependency that was set in the ephemeral world using the [`.setDependency()`](#setdependency) method and use it the Durable World.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const dependency = ctx.getDependency("dependency-name");
  // do something with the dependency
  // ...
});
```

### `.run()`

Context's `.run()` method invokes a function in the **same process** in a **synchronous manner**.
That is — the calling function blocks until the invoked function returns.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const result = yield* ctx.run(bar, ...args);
  // do more stuff
  // ...
});

function bar(ctx: Context, ...args: any[]) {
  // ...
  return;
}
```

### `.beginRun()`

Context's `.beginRun()` method invokes a function in the **same process** in an **asynchronous manner**.
That is — the invocation returns a promise which can be awaited later.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.beginRun(bar, ...args);
  // do more stuff
  const result = yield* promise;
  // ...
});

function bar(ctx: Context, ...args: any[]) {
  // ...
  return;
}
```

### `.rpc()`

Context's `.rpc()` method invokes a function in a **remote process** in a **synchronous manner**.
That is — the calling function blocks until the invoked function returns.

```ts
// process a
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const result = yield* ctx.rpc(
    "bar",
    ...args,
    ctx.options({ target: "poll://any@workers" })
  );
  // do more stuff
  // ...
});

// process b
resonate.register("bar", function (ctx: Context, ...args: any[]) {
  // ...
  return;
});
```

### `.beginRpc()`

Context's `.beginRpc()` method invokes a function in a **remote process** in an **asynchronous manner**.
That is — the invocation returns a promise which can be awaited on later.

```ts
// process a
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.beginRpc(
    "bar",
    ...args,
    ctx.options({ target: "poll://any@workers" })
  );
  // do more stuff
  const result = yield* promise;
  // ...
});

// process b
resonate.register("bar", function (ctx: Context, ...args: any[]) {
  // ...
  return;
});
```

### `.detached()`

Context's `.detached()` method invokes a function in a **remote process** in an **asynchronous manner**
but unlike `.beginRpc()`, the promise is not implictly awaited.
Use `.detached()` when you want to fire-and-forget a function invocation.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  yield* ctx.detached("bar", ...args);
  // do more stuff
});
```

### `.options()`

Options can be used with `.run()`, `.beginRun()`, `.rpc()`, `.beginRpc()`, and `.detached()` as the final argument.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  yield* ctx.run(
    bar,
    ...args,
    ctx.options({
      timeout: 60_000, // 1 minute in ms
      target: "poll://any@workers",
      tags: { key: "value" },
    })
  );
});
```

Local calls (`.run()` / `.beginRun()`) also accept `nonRetryableErrors`, an array of error class constructors that should not be retried by Resonate's retry policy.
When the invoked function throws an instance of any listed class (or a subclass), Resonate skips the retry policy and rejects the call with the thrown error.
This pairs well with `retryPolicy`: errors that match `nonRetryableErrors` short-circuit retries, while all other errors still follow the configured policy.

```ts
class ValidationError extends Error {}

resonate.register("foo", function* (ctx: Context, input: unknown) {
  yield* ctx.run(
    validate,
    input,
    ctx.options({
      nonRetryableErrors: [ValidationError],
    })
  );
});

function validate(ctx: Context, input: unknown) {
  if (!isValid(input)) {
    throw new ValidationError("input failed validation");
  }
}
```

### `.promise()`

Context's `.promise()` method allows you to get or create a promise that can be awaited on.

A new promise is created and its ID is generated automatically.

This is very useful for HITL (Human-In-The-Loop) use cases where you want to block progress until a human has taken an action or provided data.
It works well in conjunction with the [`.promises.resolve()`](#promisesresolve), [`.promises.reject()`](#promisesreject), and [`.promises.cancel()`](#promisescancel) methods.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.promise();
  // do more stuff
  const result = yield* promise;
  // ...
});
```

You can also pass custom data into the promise.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.promise({ data: { key: "value" } });
  // do more stuff
  const result = yield* promise;
  // ...
});
```

### `.sleep()`

There is no limit to how long the function can sleep.

This API accepts either a millisecond duration or an options object.
The options object can specify a duration with the `for` property or an absolute wake-up time with the `until` property.

```ts
yield* ctx.sleep(5_000); // wait 5 seconds
yield* ctx.sleep({ for: 5_000 }); // identical to passing the number
yield* ctx.sleep({ until: new Date() });
```

Passing a number or `for` value always measures the delay in milliseconds from "now".
`until` expects a JavaScript `Date` instance representing the exact time when the workflow should resume.

The options object is useful when you want to build the wake-up time conditionally before calling `sleep`.

**Sleep for a fixed duration.**

```ts
import { Context, Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

resonate.register("send-reminder", function* (ctx: Context, userId: string) {
  // Pause for five seconds without blocking the worker
  yield* ctx.sleep(5_000);

  yield* ctx.rpc("notify-user", userId);
});
```

**Sleep until a calendar time.**

```ts
import { Context, Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

resonate.register("schedule-digest", function* (ctx: Context, userId: string) {
  const nextEightAm = new Date();
  nextEightAm.setHours(8, 0, 0, 0);

  // If it is already past 8am today, schedule for tomorrow
  if (nextEightAm.getTime() <= Date.now()) {
    nextEightAm.setDate(nextEightAm.getDate() + 1);
  }

  // Resume exactly at 8am
  yield* ctx.sleep({ until: nextEightAm });

  yield* ctx.rpc("send-digest", userId);
});
```

### `.date.now()`

Context's `.date.now()` method allows you to deterministically get the time in milliseconds since the epoch.
If your function execution is recovered after the time has been retrieved, the same time will be returned.
This is helpful for ensuring the same code path is taken in the event of a recovery.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const time = yield* ctx.date.now();
  // do something with time
  // ...
});
```

### `.math.random()`

Context's `.math.random()` method allows you to generate a deterministic random number.
If your function execution is recovered after the random number has been generated, the same number will be returned.
This is helpful for ensuring the same code path is taken in the event of a recovery.

```ts
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const rand = yield* ctx.math.random();
  // do something with rand
  // ...
});
```

### `.panic()` and `.assert()`

Context's `.panic()` and `.assert()` aborts the top level durable execution based on a condition.
`.panic()` will abort if the condition is true. `.assert()` will abort if the condition is false.
These methods are intended to be used for invariant violations, for normal operation errors it is recommended
to throw an Exception.

```ts
resonate.register("foo", function* (ctx: Context) {
  // ...
  yield* ctx.panic(true, "Invariant violation");
  // Code after this call will not be executed
});
```

```ts
resonate.register("foo", function* (ctx: Context) {
  // ...
  yield* ctx.panic(false, "Invariant violation");
  // Code after this call will be executed as normal
});
```

```ts
resonate.register("foo", function* (ctx: Context) {
  // ...
  yield* ctx.assert(false, "Invariant violation");
  // Code after this call will not be executed
});
```

```ts
resonate.register("foo", function* (ctx: Context) {
  // ...
  yield* ctx.assert(true, "Invariant violation");
  // Code after this call will be executed as normal
});
```

## Defaults

The TypeScript SDK ships with these key defaults. All values are in **milliseconds** unless noted.

- **`new Resonate()`** — `group = "default"`, `ttl = 60_000 ms`, `logLevel = "warn"`. URL falls back to `RESONATE_URL`; when both are unset, a local in-memory network is used.
- **`HttpNetwork`** — request `timeout = 10_000 ms` (overridable via `RESONATE_TIMEOUT`), URL fallback `"http://localhost:8001"`.
- **`ctx.run` / `Options`** — `timeout = 86_400_000 ms (24 h)`, `target = "default"`, `version = 0`, `tags = {}`, `nonRetryableErrors = []`.
- **`retryPolicy` — generator engine** — `Exponential()` for regular `async` functions; `Never()` for generator functions (`function*`).
- **`retryPolicy` — async engine** — `Never()` for all function types; opt in per call with `ctx.options({ retryPolicy: new Exponential() })`.
- **`Exponential()` defaults** — `delay = 1_000 ms`, `factor = 2`, `maxDelay = 30_000 ms`, `maxRetries = Number.MAX_SAFE_INTEGER`.
- **`Constant()` / `Linear()` defaults** — `delay = 1_000 ms`, `maxRetries = Number.MAX_SAFE_INTEGER`.

For the full table, per-SDK comparison, and source citations, see the [Defaults reference](/reference/defaults).

---

## Async/await engine

Since v0.11.0, the TypeScript SDK ships a second execution engine alongside the generator engine. Both engines speak the same protocol to the same server and use the same durable-promise model — you can run them in the same application side by side and migrate one function at a time.

**When to use which engine:**

- **Generator engine** (`import { Resonate } from "@resonatehq/sdk"`, `function*` + `yield*`) — the original engine; sequential control flow made explicit at each step; good when you want durable checkpoints to be visible as you read the code.
- **Async/await engine** (`import { Resonate } from "@resonatehq/sdk/async"`, `async function` + `await`) — operations are eager, fan-out is ordinary `Promise.all`, workflows look like regular Node.js async code; closest to what Restate or DBOS users will already be writing; retries default to `Never` for all function types — opt in explicitly per call.

### Import

The async engine lives at a separate package export — both `Resonate` classes accept the same constructor options:

```ts
import { Resonate, type Context, Exponential, Linear, Constant, Never } from "@resonatehq/sdk/async";
```

### Register and run

Workflows are ordinary `async` functions. Register and invoke them the same way as in the generator engine:

```ts title="src/index.ts"
import { Resonate, type Context } from "@resonatehq/sdk/async";

async function greet(ctx: Context, name: string): Promise<string> {
  return `Hello, ${name}!`;
}

const resonate = new Resonate({ url: "http://localhost:8001" });
resonate.register(greet);

// resonate.run() returns a handle, not the result directly
const handle = await resonate.run("greet-1", greet, "world");
const result = await handle.result(); // Hello, world!

await resonate.stop();
```

Key difference from the generator engine: `resonate.run()` returns `Promise<Handle>`, not the result directly. Call `.result()` on the handle to get the value. There are **no `beginRun` or `beginRpc` variants** in the async engine — every `run` and `rpc` on the client already returns a handle, so `beginRun` would be redundant.

### Context APIs — eager operations and fan-out

Inside an async workflow, `ctx.run(fn)` starts the durable operation immediately and returns an awaitable `DurablePromise`. Because operations are eager, fan-out is plain `Promise.all`:

```ts title="src/workflow.ts"
import { type Context } from "@resonatehq/sdk/async";

async function processItems(ctx: Context, items: string[]) {
  // All durable steps start immediately and run concurrently
  const handles = items.map(item => ctx.run(processItem, item));
  const results = await Promise.all(handles);
  return results;
}

async function processItem(ctx: Context, item: string): Promise<string> {
  return `processed: ${item}`;
}
```

In the generator engine, `yield* ctx.run()` blocks until the step completes, and fan-out requires `yield* ctx.beginRun()`. In the async engine, `ctx.run()` always starts eagerly — `await ctx.run(fn)` is call-and-wait, while `ctx.run(fn)` without an immediate `await` is fire-and-collect-later.


A plain `await` on a timer, network I/O, or any non-durable promise is invisible to the engine. The workflow may resume after its execution pass has ended, making the plain-await continuation a zombie. Wrap all side effects in `ctx.run`, `ctx.rpc`, or `ctx.sleep` — the same rule as `yield* ctx.run(fn)` in the generator engine.


### Retries — opt in explicitly

**The async engine defaults to `Never` for all retry policies.** This differs from the generator engine, where a plain `async function` registered with `resonate.register` gets `Exponential` retries by default. The reason: an async workflow and a plain async helper are indistinguishable at the type level, so a blanket retry default would silently retry code you never intended to retry.

Opt in per call via `ctx.options({ retryPolicy })`:

```ts title="src/workflow.ts"
import { type Context, Exponential } from "@resonatehq/sdk/async";

async function checkout(ctx: Context) {
  // No retry by default; opt in explicitly per call
  const chargeResult = await ctx.run(
    chargeCard,
    ctx.options({ retryPolicy: new Exponential() })
  );
  return chargeResult;
}

async function chargeCard(ctx: Context) {
  // ... charge logic ...
}
```

`Exponential`, `Linear`, `Constant`, and `Never` are all exported from `@resonatehq/sdk/async`.

### Migrating from the generator engine

Both engines live in the same package and speak the same protocol, so you can migrate function by function. The mechanical changes:

| Generator engine | Async engine |
|---|---|
| `import { Resonate } from "@resonatehq/sdk"` | `import { Resonate } from "@resonatehq/sdk/async"` |
| `function* (ctx: Context, ...)` | `async function (ctx: Context, ...)` |
| `yield* ctx.run(fn, ...args)` | `await ctx.run(fn, ...args)` |
| `yield* ctx.beginRun(fn)`, later `yield* future` | `const p = ctx.run(fn)`, later `await p` — every op is eager; no `begin*` variants |
| `resonate.run(id, fn, ...args)` → returns result | `resonate.run(id, fn, ...args)` → returns handle; `await handle.result()` to get value |
| `resonate.beginRun(id, fn, ...args)` → returns handle | `beginRun` does not exist — `resonate.run` already returns a handle, making it equivalent |
| `ctx.run` retries: `Exponential()` for async fns by default | `ctx.run` retries: `Never()` by default — pass `ctx.options({ retryPolicy: new Exponential() })` |

For the full walkthrough, see the [SDK README migration guide](https://github.com/resonatehq/resonate-sdk-ts#migrating-from-generators).

---

---
url: https://docs.resonatehq.io/evaluate/coming-from/byode
title: BYODE
---

**Have you built your own queue system, workflow engine, or retry framework?**

If you've built custom infrastructure for handling distributed tasks, retries, sagas, or long-running processes, you've likely been building durable execution primitives - even if you didn't call it that.

This guide is for engineers who identified the problem, built a solution, and now maintain it.

## You identified the right problem

If you built systems that handle:
- **Reliable task execution** with retries and timeouts
- **Distributed sagas** or multi-step transactions
- **Scheduled or delayed processing** (cron jobs, deferred tasks)
- **At-least-once or exactly-once semantics** (leases, idempotency keys)
- **Long-running workflows** that survive crashes
- **Worker coordination** across multiple processes

**You were solving durable execution.** You saw the gap between what databases, queues, and frameworks provided, and you built what you needed.

Projects like:
- Custom queue systems with leases and visibility timeouts
- Homegrown workflow engines
- Retry frameworks with persistent state
- Task schedulers with recovery logic
- Event-driven systems with guaranteed delivery

These are all variations of durable execution infrastructure.

## The hidden cost

You know the pain of maintaining custom infrastructure:

**Operational burden:**
- Debugging obscure failure modes
- Handling edge cases (partial failures, timeouts, clock skew)
- Scaling bottlenecks you didn't anticipate
- Upgrading without breaking production workloads

**Evolution challenges:**
- Every new use case needs custom code
- Patterns don't transfer between projects
- New team members face a steep learning curve
- Testing distributed scenarios is hard

**Reliability questions:**
- Did we handle every failure mode?
- What happens if the process crashes mid-transaction?
- Can we prove correctness under concurrent load?
- Will this work when we add more nodes?

You've built something that works, but it's bespoke. Every company reinvents these primitives because there wasn't a better option.

## What makes Resonate different

### Built on formal foundations

Your system was built to solve a specific problem. **Resonate is built on a formal protocol** - Distributed Async Await - that has been through formal methods and verification.

This means:
- **Proven correctness** - The model has been validated against common failure scenarios ([how Resonate is tested](/evaluate/how-resonate-is-tested))
- **Clear semantics** - What happens on retry, crash, timeout, or split-brain is defined, not discovered
- **Interoperability** - The protocol is language-agnostic and implementation-independent

### Insanely simple programming model

Most custom systems require developers to:
- Understand queue semantics, leases, and visibility timeouts
- Manually track state across retries
- Implement idempotency at the application layer
- Wire up different systems (queues, databases, schedulers)

**Resonate uses distributed async/await** - the same syntax you already know:

```typescript title="Simple durable function"
function* processOrder(ctx: Context, order: Order) {
  const payment = yield* ctx.run(chargeCard, order);
  const inventory = yield* ctx.run(reserveItems, order);
  const shipment = yield* ctx.run(scheduleShipment, order);
  
  return { payment, inventory, shipment };
}
```

The code above is complete — ordinary functions, checkpointed at each step. There's no queue abstraction, lease management, or state-machine diagram to learn.

**If the process crashes**, Resonate resumes from the last completed step. **If chargeCard succeeds but reserveItems fails**, the retry doesn't re-charge the card.

The programming model is simple because the protocol handles complexity.

## Translating your patterns

### Pattern: Leased queue with retries

**What you built:**
```typescript title="Custom queue with leases"
// Custom queue with lease semantics
const task = await queue.dequeue({ lease: 30000 });
try {
  await processTask(task);
  await queue.complete(task.id);
} catch (error) {
  await queue.release(task.id, { retryAfter: 60000 });
}
```

**In Resonate:**
```typescript title="Resonate automatic retry"
function* processTask(ctx: Context, taskId: string) {
  // Resonate handles leasing, retries, and completion automatically
  const result = yield* ctx.run(doWork, taskId);
  return result;
}
```

No explicit lease management. Resonate's protocol ensures the function runs exactly once per invocation ID.

### Pattern: Distributed saga






    

```typescript title="Custom saga with compensations"
// Multi-step transaction with compensations
async function orderSaga(order) {
  const actions = [];
  
  try {
    const payment = await chargeCard(order);
    actions.push({ compensate: () => refundCard(payment) });
    
    const inventory = await reserveInventory(order);
    actions.push({ compensate: () => releaseInventory(inventory) });
    
    const shipment = await scheduleShipment(order);
    
    await markComplete(order.id);
  } catch (error) {
    // Run compensations in reverse
    for (const action of actions.reverse()) {
      await action.compensate();
    }
    throw error;
  }
}
```

    

    

```typescript title="Resonate saga"
function* orderSaga(ctx: Context, order: Order) {
  const payment = yield* ctx.run(chargeCard, order);
  
  try {
    const inventory = yield* ctx.run(reserveInventory, order);
    const shipment = yield* ctx.run(scheduleShipment, order);
    return { success: true };
  } catch (error) {
    yield* ctx.run(refundCard, payment);
    throw error;
  }
}
```

    



Same logic, no manual tracking. Resonate checkpoints after each step, so retries don't re-execute completed work.

### Pattern: Scheduled or deferred tasks



    

```typescript title="Custom scheduler"
// Custom scheduler with persistent state
await scheduler.schedule({
  runAt: Date.now() + 86400000, // 24 hours
  task: "sendReminderEmail",
  payload: { userId, orderId }
});
```

    

    

```typescript title="Resonate durable sleep"
function* sendReminder(ctx: Context, userId: string, orderId: string) {
  yield* ctx.sleep(24 * 60 * 60 * 1000); // 24 hours
  yield* ctx.run(sendEmail, userId, orderId);
}
```

    



Durable sleep is a first-class primitive. If the process crashes, the timer persists.

### Pattern: Idempotency with external systems



    

```typescript title="Manual idempotency keys"
// Manual idempotency key management
const idempotencyKey = `charge-${order.id}`;
const existing = await cache.get(idempotencyKey);
if (existing) return existing;

const result = await stripe.charge({ idempotencyKey, ...order });
await cache.set(idempotencyKey, result, { ttl: 86400 });
return result;
```

    

    

```typescript title="Built-in idempotency"
function* chargeOrder(ctx: Context, orderId: string) {
  // The invocation ID IS the idempotency key
  const result = yield* ctx.run(stripe.charge, order);
  return result;
}
```

    



Invocation IDs provide built-in idempotency. The same ID always returns the same result.

## Why move to Resonate

### Reduce maintenance burden

You built infrastructure. **Resonate is infrastructure.**

Instead of:
- Debugging custom queue semantics
- Tuning lease timeouts and visibility windows
- Handling database deadlocks in your state table
- Writing migration scripts for schema changes

You get:
- A protocol-level implementation of durable execution
- Formal verification of correctness properties
- Battle-tested at scale (Resonate's design is based on production systems handling billions of events)

### Standardize patterns across your organization

Your custom system solves one problem well. **Resonate provides a platform.**

- New projects use the same primitives (ctx.run, ctx.sleep, ctx.promise)
- Team members learn one model, not N custom systems
- Patterns from one project transfer to others
- Onboarding is faster ("It's just async/await")

### Zero-dependency development

Your system likely requires:
- A database for state
- A message queue or scheduler
- Service discovery or coordination
- Configuration and deployment

**Resonate has a zero-dependency mode:**

```typescript title="Local development"
const resonate = new Resonate(); // Runs locally, in-memory
```

Developers can test workflows on their laptop. When ready, connect to a server for distributed coordination. No infrastructure required until you need it.

### Built on a protocol, not a product

Your custom system is tied to your stack, your choices, your company.

**Resonate implements Distributed Async Await** - a protocol with:
- Formal semantics (executable Lean 4 specification, published open-source)
- Language-agnostic design (TypeScript, Python, and Rust SDKs today, with a Go SDK in active development)
- Open source implementation (server and SDKs)

If you outgrow Resonate or want to embed the protocol elsewhere, the model is portable.

## Migration path

If you're considering migrating from a custom system:

1. **Identify core patterns** - Map your queue/workflow patterns to Resonate primitives
2. **Start with new workloads** - Use Resonate for new features while legacy systems run in parallel
3. **Extract shared logic** - Move idempotency, retry, and coordination logic to Resonate
4. **Migrate incrementally** - One workflow at a time, not big-bang
5. **Decommission gradually** - As Resonate proves itself, reduce custom infrastructure surface area

You don't have to rewrite everything. Resonate can coexist with your existing systems and gradually replace them.

## When to stick with your custom system

Resonate isn't always the right answer. Stick with your custom solution if:

- **It's working great** - If your system is stable, well-understood, and maintainability isn't an issue, don't fix what isn't broken
- **Extremely specialized** - If your requirements are so unique that general-purpose infrastructure can't fit
- **Already scaled perfectly** - If you've solved all the hard problems and your team is expert in your system
- **Investment pays off** - If the cost of maintaining custom infrastructure is worth the control and specificity

But if you're here because you're **tired of maintaining custom infrastructure**, or you're **building yet another system** for a new project, Resonate is worth evaluating.

## Honest comparison

| Your Custom System | Resonate |
|--------------------|----------|
| Built for your specific use case | General-purpose durable execution |
| Queue semantics, leases, visibility | Distributed async/await (familiar syntax) |
| Custom state management | Protocol-level checkpointing |
| Maintenance is on you | Open source community + commercial support available |
| Bespoke, company-specific | Protocol-based, portable |
| Formal verification: maybe | Formal verification: yes (executable Lean 4 specification) |
| Learning curve: steep (new hires) | Learning curve: gentle (async/await) |

## Next steps

- Read [Why Resonate](/evaluate/why-resonate) to understand the formal foundations
- Try the [Quickstart](/get-started/quickstart) with zero-dependency mode
- Review [example applications](/get-started/examples) - many solve problems you've probably built custom solutions for
- Join [Discord](https://discord.gg/resonate) to discuss migration paths from custom systems

---

**Questions or feedback?** If you've built custom durable execution infrastructure and want to share your experience or ask questions about migrating to Resonate, we'd love to hear from you in Discord.

---

---
url: https://docs.resonatehq.io/evaluate/coming-from/dbos
title: DBOS vs Resonate
---

This page reflects `@resonatehq/sdk` v0.11.4 (TypeScript, current on npm), `resonate-sdk` v0.7.4 (Python), `resonate-sdk` v0.6.0 (Rust, on crates.io), and the Resonate Go SDK 0.1.0.



DBOS blocks below are excerpted from the official `dbos-inc/dbos-demo-apps` repo and the DBOS SDK repos (`dbos-transact-{py,ts,golang}`) — trimmed for focus, elisions marked, never rewritten. They reflect `dbos` v2.23.0 (Python), `@dbos-inc/dbos-sdk` v4.19.8 (TypeScript), and `dbos-transact-golang` v0.17.0 (Go). Resonate blocks come from the [examples library](https://github.com/resonatehq-examples), pinned to the latest released SDKs (the Rust examples track the SDK's `main` branch). DBOS ships SDKs for TypeScript, Python, Go, and Java; it has no Rust SDK, so the Rust tabs below show Resonate only. Some patterns don't have a Resonate example in every language yet; those gaps are noted inline.


**Are you coming from DBOS?**

If so, this guide is meant to help you understand the differences and similarities between Resonate and DBOS — concept by concept, with side-by-side migration code.

DBOS and Resonate have a lot in common, and DBOS is a genuinely good system: you add durability by annotating ordinary functions, the only required infrastructure is a database you already know, and you get built-in observability for free. This guide focuses on how the two map onto each other, and is honest about what each does that the other does not.

## Durability

A core value proposition of DBOS is its durable workflows.
A durable workflow or Durable Execution is one that can recover in another process after a hard failure and resume from where it left off.

Resonate also provides durable workflows (Durable Executions).

In Resonate, if your process crashes, your function can recover and resume from where it left off in another process.

## Programming model

If you have experience with DBOS, then you are familiar with thinking in terms of Workflows and Steps. You annotate a function with `@DBOS.workflow()` and the functions it calls with `@DBOS.step()` (or run them inline with `DBOS.runStep` / `DBOS.RunAsStep`). DBOS checkpoints each step to the database so a restarted workflow resumes from the last completed step.

Resonate does not have proprietary function types such as Workflows and Steps – you just write functions. A step is any function you pass to `ctx.run`, which makes its result durable. There is no decorator split, no task-queue wiring, and no mandatory per-step timeout policy.

Here is the most basic migration — a workflow that runs a few steps, and the equivalent Resonate function:





```python title="DBOS — dbos-demo-apps/python/dbos-app-starter/app/main.py"
@DBOS.step()
def step_one():
    time.sleep(5)
    DBOS.logger.info("Completed step 1!")

@DBOS.workflow()
def workflow():
    step_one()
    # ... step_two(), step_three() ...
```

```python title="Resonate — example-hello-world-py/main.py"
def bar(_: Context, greetee: str) -> str:
    return f"Hello {greetee} from bar!"

def baz(_: Context, greetee: str) -> str:
    return f"Hello {greetee} from baz!"

@resonate.register
async def foo(ctx: Context, greetee: str) -> str:
    foo_greeting = f"Hello {greetee} from foo!"
    bar_greeting = await ctx.run(bar, greetee=greetee)
    baz_greeting = await ctx.run(baz, greetee=greetee)
    greeting = f"{foo_greeting} {bar_greeting} {baz_greeting}"
    return greeting
```

See it in action: [example-hello-world-py](https://github.com/resonatehq-examples/example-hello-world-py)





```typescript title="DBOS — dbos-demo-apps/typescript/dbos-node-starter/src/main.ts"
async function stepOne() {
  await sleep(5000);
  console.log("Completed step 1!");
}

async function exampleWorkflow() {
  await DBOS.runStep(stepOne);
  // ... DBOS.runStep(stepTwo), DBOS.runStep(stepThree) ...
}

const registeredWorkflow = DBOS.registerWorkflow(exampleWorkflow);
```

```typescript title="Resonate — example-hello-world-ts/index.ts"
async function bar(_: Context, greetee: string): Promise<string> {
  return `Hello ${greetee} from bar!`;
}

async function baz(_: Context, greetee: string): Promise<string> {
  return `Hello ${greetee} from baz!`;
}

function* foo(ctx: Context, greetee: string): Generator<any, string, any> {
  const fooGreeting = `Hello ${greetee} from foo!`;
  const barGreeting = yield* ctx.run(bar, greetee);
  const bazGreeting = yield* ctx.run(baz, greetee);
  const greeting = `${fooGreeting} ${barGreeting} ${bazGreeting}`;
  return greeting;
}

const fooR = resonate.register("foo", foo);
```

See it in action: [example-hello-world-ts](https://github.com/resonatehq-examples/example-hello-world-ts)






DBOS ships SDKs for TypeScript, Python, Go, and Java. There is no DBOS Rust SDK, so there is no DBOS code to place beside Resonate here. The Resonate Rust equivalent:


```rust title="Resonate — example-hello-world-rs/src/main.rs"
#[resonate::function]
async fn greet(ctx: &Context, name: String) -> Result<String> {
    let greeting = ctx.run(format_greeting, name).await?;
    Ok(greeting)
}

#[resonate::function]
async fn format_greeting(name: String) -> Result<String> {
    Ok(format!("Hello, {name}!"))
}
```

See it in action: [example-hello-world-rs](https://github.com/resonatehq-examples/example-hello-world-rs)





```go title="DBOS — dbos-demo-apps/golang/dbos-go-starter/main.go"
func ExampleWorkflow(ctx dbos.DBOSContext, _ string) (string, error) {
    _, err := dbos.RunAsStep(ctx, func(stepCtx context.Context) (string, error) {
        return stepOne(stepCtx)
    })
    if err != nil {
        return "", err
    }
    // ... RunAsStep(stepTwo), RunAsStep(stepThree) ...
    return "Workflow completed", nil
}

func stepOne(ctx context.Context) (string, error) {
    time.Sleep(5 * time.Second)
    fmt.Println("Step one completed!")
    return "Step 1 completed", nil
}
```

In `main()`, register it with `dbos.RegisterWorkflow(dbosCtx, ExampleWorkflow)`.

```go title="Resonate — example-hello-world-go/main.go"
func greet(_ *resonate.Context, args GreetArgs) (string, error) {
    return fmt.Sprintf("hello, %s!", args.Name), nil
}

func main() {
    r, _ := resonate.New(resonate.Config{URL: "http://localhost:8001"})
    defer r.Stop()

    greetFn, _ := resonate.Register(r, "greet", greet)
    h, _ := greetFn.Run(ctx, id, GreetArgs{Name: "world"})
    out, _ := h.Result(ctx)
    fmt.Println(out)
}
```

See it in action: [example-hello-world-go](https://github.com/resonatehq-examples/example-hello-world-go)





`ctx.run` (and registering the function) replaces the `@DBOS.workflow()` / `@DBOS.step()` split. One thing to carry over from DBOS: a DBOS workflow function must be deterministic — non-deterministic work (network calls, the clock, random numbers) belongs inside steps. The same discipline applies in Resonate: do side-effecting work inside `ctx.run` so it is checkpointed and replayed from the durable record, not re-executed.

### Composing and recursing

In DBOS you compose by invoking one registered workflow from another — a child workflow — with `DBOS.start_workflow(fn, ...args)` (Python), `DBOS.startWorkflow(fn)(...args)` (TypeScript), or `dbos.RunWorkflow(ctx, fn, args)` (Go). For example, the widget-store checkout starts its dispatch workflow as a child:

```python
# dbos-demo-apps/python/widget-store/widget_store/main.py
DBOS.start_workflow(dispatch_order_workflow, order_id)
```

Resonate promotes a procedural programming model that lets you compose functions indefinitely and recursively — a function can simply call itself. Consider this factorial example.





```python
@resonate.register
async def factorial(ctx: Context, n: int) -> int:
    if n <= 1:
        return 1
    r = await ctx.options(target="factorial-worker").rpc("factorial", n - 1)
    return n * r


async def main():
    handle = resonate.run("factorial-5", factorial, n=5)
    result = await handle.result()
    print(result)
```

See it in action: [example-recursive-factorial-py](https://github.com/resonatehq-examples/example-recursive-factorial-py)





```typescript
function* factorial(ctx: Context, n: number): Generator<any, number, any> {
  if (n <= 1) {
    return 1;
  }
  const result = yield* ctx.rpc(
    "factorial",
    n - 1,
    ctx.options({ target: "poll://any@factorial-workers" }),
  );

  return n * result;
}

const factorialR = resonate.register("factorial", factorial);

async function main() {
  const result = await factorialR.run("factorial-5", 5);
  console.log(result);
}
```

See it in action: [example-recursive-factorial-ts](https://github.com/resonatehq-examples/example-recursive-factorial-ts)





```rust
#[resonate::function]
async fn factorial(ctx: &Context, n: u64) -> Result<u64> {
    if n <= 1 {
        return Ok(1);
    }
    let result: u64 = ctx
        .rpc("factorial", n - 1)
        .target("poll://any@factorial-workers")
        .await?;

    Ok(n * result)
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        group: Some("factorial-workers".into()),
        ..Default::default()
    });
    resonate.register(factorial).unwrap();

    let result: u64 = resonate.run("factorial-5", factorial, 5).await.unwrap();
    println!("{result}");

    resonate.stop().await.unwrap();
}
```

See it in action: [example-recursive-factorial-rs](https://github.com/resonatehq-examples/example-recursive-factorial-rs)





```go
type Args struct {
	N int `json:"n"`
}

func factorial(ctx *resonate.Context, args Args) (int, error) {
	if args.N <= 1 {
		return 1, nil
	}
	f, err := ctx.RPC("Factorial", Args{N: args.N - 1})
	if err != nil {
		return 0, err
	}
	var result int
	if err := f.Await(&result); err != nil {
		return 0, err
	}
	return args.N * result, nil
}

func main() {
	r, _ := resonate.New(resonate.Config{URL: "http://localhost:8001"})
	defer func() { _ = r.Stop() }()

	factorialFn, _ := resonate.Register(r, "Factorial", factorial)

	h, _ := factorialFn.Run(context.Background(), "factorial-5", Args{N: 5})
	result, _ := h.Result(context.Background())
	fmt.Println(result)
}
```

See it in action: [example-recursive-factorial-go](https://github.com/resonatehq-examples/example-recursive-factorial-go)





## Zero-dependency development

DBOS keeps workflow state in a database. The Python SDK makes this nearly invisible for local development: if you don't set a system database URL, it defaults to an on-disk SQLite file (`sqlite:///{app_name}.sqlite`), so a Python app runs with no Postgres to install. The TypeScript SDK requires Postgres — it ships `npx dbos postgres start` to bring one up in Docker — and the Go SDK uses Postgres by default (it can run on SQLite if you wire one in). In every case, there is a database holding workflow state.

Resonate offers a zero-dependency development experience: a Worker (single-node application) runs entirely in-memory, with no database and no Resonate Server, until you choose to connect one.





**DBOS** — Postgres optional; omit the URL and DBOS uses an embedded SQLite file (`dbos-demo-apps/python/dbos-app-starter/app/main.py` sets it from the environment):

```python
config: DBOSConfig = {
    "name": "dbos-app-starter",
    "system_database_url": os.environ.get("DBOS_SYSTEM_DATABASE_URL"),
    # ...
}
DBOS(config=config)
```

**Resonate** — no database, no server:

```python
from resonate.resonate import Resonate

resonate = Resonate()  # no url, no RESONATE_URL/RESONATE_HOST env -> in-memory, no server

# ...
```





**DBOS** — Postgres required (`dbos-demo-apps/typescript/dbos-node-starter/src/main.ts`):

```typescript
DBOS.setConfig({
  name: "dbos-node-starter",
  systemDatabaseUrl: process.env.DBOS_SYSTEM_DATABASE_URL,
  // ...
});
await DBOS.launch(/* { conductorKey } */);
```

**Resonate** — no database, no server:

```typescript
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

// ...
```






The Resonate Rust worker runs fully in-memory until you connect a server:


```rust
use resonate::prelude::*;

let resonate = Resonate::local();

// ...
```





**DBOS** — Postgres by default (`dbos-demo-apps/golang/dbos-go-starter/main.go`):

```go
dbosCtx, err = dbos.NewDBOSContext(context.Background(), dbos.Config{
	DatabaseURL: os.Getenv("DBOS_SYSTEM_DATABASE_URL"),
	AppName:     "dbos-toolbox",
	// ...
})
```

**Resonate** — no database, no server:

```go
import (
	resonate "github.com/resonatehq/resonate-sdk-go"
	"github.com/resonatehq/resonate-sdk-go/localnet"
)

// Local development mode runs the server state machine in-process,
// using in-memory storage for promises and tasks.
pid := "dev-worker"
r, _ := resonate.New(resonate.Config{
	Network:   localnet.NewLocal("default", &pid),
	Heartbeat: resonate.NoopHeartbeat{}, // localnet has no lease endpoint to heartbeat against
})

// ...
```





## Fan-out / fan-in

To run many units of work in parallel and then join the results, DBOS uses durable queues: you enqueue each task and collect each handle's result. Resonate starts each unit with a non-blocking invocation and then awaits each promise.


DBOS queues are a real strength worth calling out: beyond parallelism, they give you per-queue and per-process concurrency limits, rate limits, priorities, and debouncing — all backed by Postgres, with no separate broker. If you rely on those controls, plan how you'll reproduce them; Resonate's fan-out primitive is parallelism plus join, not a managed queue.






**DBOS** — DBOS docs, Python queue tutorial:

```python
DBOS.register_queue("example_queue")

@DBOS.workflow()
def process_tasks(tasks):
    task_handles = []
    # Enqueue each task so all tasks are processed concurrently.
    for task in tasks:
        handle = DBOS.enqueue_workflow("example_queue", process_task, task)
        task_handles.append(handle)
    # Wait for each task to complete and retrieve its result.
    return [handle.get_result() for handle in task_handles]
```

```python title="Resonate — example-fan-out-fan-in-py/workflow.py"
# fan-out: ctx.run returns a future immediately, without blocking
email_f = ctx.run(send_email, event)
sms_f = ctx.run(send_sms, event)
# fan-in: await each
email = await email_f
sms = await sms_f
```

See it in action: [example-fan-out-fan-in-py](https://github.com/resonatehq-examples/example-fan-out-fan-in-py)





**DBOS** — DBOS docs, TypeScript programming guide:

```typescript
async function queueFunction() {
  const handles = []
  for (let i = 0; i < 10; i++) {
    handles.push(await DBOS.startWorkflow(taskWorkflow, { queueName: "example_queue" })(i))
  }
  const results = []
  for (const h of handles) {
    results.push(await h.getResult())
  }
}
```

```typescript title="Resonate — example-fan-out-fan-in-ts/src/workflow.ts"
// fan-out: beginRun returns a future immediately
const emailFuture = yield* ctx.beginRun(sendEmail, event);
const smsFuture   = yield* ctx.beginRun(sendSms, event);
// fan-in: await each
const results = [yield* emailFuture, yield* smsFuture];
```

See it in action: [example-fan-out-fan-in-ts](https://github.com/resonatehq-examples/example-fan-out-fan-in-ts)






The Resonate Rust equivalent fans out with `.spawn()`:


```rust title="Resonate — example-fan-out-fan-in-rs/src/main.rs"
// fan-out: .spawn() returns a handle immediately
let h1 = ctx.run(process_item, items[0].clone()).spawn()?;
let h2 = ctx.run(process_item, items[1].clone()).spawn()?;
let h3 = ctx.run(process_item, items[2].clone()).spawn()?;
// fan-in: await each
let r1 = h1.await?;
let r2 = h2.await?;
let r3 = h3.await?;
```

See it in action: [example-fan-out-fan-in-rs](https://github.com/resonatehq-examples/example-fan-out-fan-in-rs)





**DBOS** — `dbos-transact-golang` README:

```go
queue := dbos.NewWorkflowQueue(ctx, "queue")
// ...
handles := make([]dbos.WorkflowHandle[int], 10)
for i := range 10 {                                      // fan-out
    handle, err := dbos.RunWorkflow(ctx, task, i, dbos.WithQueue(queue.Name))
    if err != nil {
        panic(fmt.Sprintf("failed to enqueue step %d: %v", i, err))
    }
    handles[i] = handle
}
results := make([]int, 10)
for i, handle := range handles {                         // fan-in
    result, err := handle.GetResult()
    if err != nil {
        panic(fmt.Sprintf("failed to get result for step %d: %v", i, err))
    }
    results[i] = result
}
```

```go title="Resonate — example-fan-out-fan-in-go/main.go"
futures := make([]*resonate.Future, 0, len(args.Channels))
for _, ch := range args.Channels {                       // fan-out
    f, err := ctx.RPC("send", SendArgs{Channel: ch, Message: args.Message})
    if err != nil {
        return FanoutResult{}, err
    }
    futures = append(futures, f)
}
for i, f := range futures {                              // fan-in
    var d Delivery
    if err := f.Await(&d); err != nil {
        out.Delivered = append(out.Delivered, Delivery{Channel: args.Channels[i], OK: false, Reason: err.Error()})
        continue
    }
    out.Delivered = append(out.Delivered, d)
}
```

See it in action: [example-fan-out-fan-in-go](https://github.com/resonatehq-examples/example-fan-out-fan-in-go)





## Durable sleep and scheduled work

DBOS workflows pause with `DBOS.sleep`, which records the wakeup time in the database so the sleep survives crashes and restarts. Resonate's equivalent is `ctx.sleep` — a single durable promise that survives crashes.


Both systems vary the unit by SDK. DBOS: TypeScript `DBOS.sleep` takes **milliseconds**, Python `DBOS.sleep` takes **seconds**, Go `dbos.Sleep` takes a `time.Duration`. Resonate: TypeScript **milliseconds**, Python a `timedelta` (`ctx.sleep(timedelta(seconds=...))`), Go and Rust a native `Duration`.






```python title="DBOS — dbos-demo-apps/python/widget-store/widget_store/main.py"
@DBOS.workflow()
def dispatch_order_workflow(order_id):
    for _ in range(10):
        DBOS.sleep(1)                          # seconds
        update_order_progress(order_id)
```

```python title="Resonate — durable sleep"
from datetime import timedelta


@resonate.register
async def sleeping_workflow(ctx: Context, wf_id: str, secs: float) -> str:
    print(f"Workflow {wf_id} starting, will sleep for {secs} seconds.")
    await ctx.sleep(timedelta(seconds=secs))    # timedelta, not a bare number
    return f"Workflow {wf_id} completed after sleeping for {secs} seconds."
```


`Context.sleep` is typed `sleep(self, duration: timedelta)` on `resonate-sdk` 0.7.4. `example-durable-sleep-py/worker.py` still calls `ctx.sleep(secs)` with a float — the sample above is the correct form, and the example repository needs the same fix.


See it in action: [example-durable-sleep-py](https://github.com/resonatehq-examples/example-durable-sleep-py)





```typescript title="DBOS — dbos-demo-apps/typescript/widget-store/src/shop.ts"
export const dispatchOrder = DBOS.registerWorkflow(
  async (order_id: number) => {
    for (let i = 0; i < 10; i++) {
      await DBOS.sleep(1000);                  // milliseconds
      // ...
    }
  },
  { name: 'dispatchOrder' },
);
```

```typescript title="Resonate — example-durable-sleep-ts/worker.ts"
function* sleepingWorkflow(ctx: Context, ms: number) {
  yield* ctx.run((ctx: Context) => console.log(`Sleeping for ${ms / 1000} seconds...`));
  yield* ctx.sleep(ms);                        // milliseconds
  return `Slept for ${ms / 1000} seconds`;
}
```

See it in action: [example-durable-sleep-ts](https://github.com/resonatehq-examples/example-durable-sleep-ts)






The Resonate Rust equivalent sleeps on a native `Duration`:


```rust title="Resonate — example-durable-sleep-rs/src/bin/worker.rs"
#[resonate::function]
async fn sleeping_workflow(ctx: &Context, secs: u64) -> Result<String> {
    ctx.sleep(Duration::from_secs(secs)).await?;   // std::time::Duration
    Ok(format!("Slept for {secs} seconds"))
}
```

See it in action: [example-durable-sleep-rs](https://github.com/resonatehq-examples/example-durable-sleep-rs)





```go title="DBOS — dbos-demo-apps/golang/widget-store/workflows.go"
func dispatchOrderWorkflow(ctx dbos.DBOSContext, orderID int) (string, error) {
    for range 10 {
        _, err := dbos.Sleep(ctx, time.Second)     // time.Duration
        if err != nil {
            return "", err
        }
        // ...
    }
    return "", nil
}
```

```go title="Resonate — example-durable-sleep-go/main.go"
func sleepingWorkflow(ctx *resonate.Context, args SleepArgs) (string, error) {
    d := time.Duration(args.Secs) * time.Second
    f, err := ctx.Sleep(d)                       // time.Duration
    if err != nil {
        return "", err
    }
    if err := f.Await(nil); err != nil {         // Await(nil) — no return value
        return "", err
    }
    return fmt.Sprintf("slept for %d second(s)", args.Secs), nil
}
```

See it in action: [example-durable-sleep-go](https://github.com/resonatehq-examples/example-durable-sleep-go)





For recurring work, DBOS schedules a workflow on a cron expression — either the `@DBOS.scheduled(cron)` decorator (the workflow receives the scheduled and actual fire times) or the database-backed `DBOS.create_schedule(...)` / `apply_schedules(...)` API. Resonate registers a schedule with `resonate.schedule(...)` (TypeScript, Python, and Rust), and the Resonate Server fires the promise on the cron.


DBOS uses a **6-field** cron with a leading seconds component — `* * * * * *` means *every second*. Resonate takes a **standard 5-field** cron — `* * * * *` means *every minute*. Drop the leading seconds field when migrating, or a `* * * * * *` copied across fires far more often than you intend.






```python title="DBOS — dbos-transact-py/tests/test_scheduler_decorator.py"
@DBOS.scheduled("* * * * * *")
@DBOS.workflow()
def test_workflow(scheduled: datetime, actual: datetime) -> None:
    # scheduled = the cron-planned fire time; actual = when DBOS fired it
    # ...
```

**Resonate** — registers a cron schedule with the server (`example-schedule-py`, `resonate-sdk` ≥0.7.4):

```python
await resonate.schedule(
    id="my-schedule",
    cron="* * * * *",
    func_name="my_function",   # registered name; args=(...) for arguments
)
```

See it in action: [example-schedule-py](https://github.com/resonatehq-examples/example-schedule-py)





```typescript title="DBOS — dbos-transact-ts/tests/scheduler_decorator.test.ts"
@DBOS.scheduled({ crontab: '* * * * * *', mode: SchedulerMode.ExactlyOncePerIntervalWhenActive })
@DBOS.workflow()
static async scheduledDefault(schedTime: Date, startTime: Date) {
  // ...
}
```

```typescript title="Resonate — example-schedule-ts/src/schedule.ts"
await resonate.schedule("my-schedule", "* * * * *", myFunction /* , ...args */);
```

See it in action: [example-schedule-ts](https://github.com/resonatehq-examples/example-schedule-ts)






The Resonate Rust equivalent registers the schedule with the server:


```rust title="Resonate — example-schedule-rs/src/bin/schedule.rs"
let result = resonate
    .schedule(
        "daily_report",    // schedule ID
        "* * * * *",       // cron: every minute
        "generate_report", // function name (matches #[resonate::function])
        123_u64,           // argument
    )
    .await;
```

See it in action: [example-schedule-rs](https://github.com/resonatehq-examples/example-schedule-rs)





**DBOS** — `dbos-transact-golang` README:

```go
dbos.RegisterWorkflow(dbosCtx, func(ctx dbos.DBOSContext, scheduledTime time.Time) (string, error) {
    return fmt.Sprintf("Workflow executed at %s", scheduledTime), nil
}, dbos.WithSchedule("* * * * * *")) // Every second
```


There is no `example-schedule-go` yet. The Go SDK's schedules API shipped in the tagged `0.1.0` release; until a worked example ships, treat the Go scheduling cell as a known gap rather than a verified sample.






## Human-in-the-loop

With DBOS, a workflow calls `DBOS.recv()` to block and await a message — for example, a human decision — while an outside caller delivers it with `DBOS.send()`. A companion pair, `DBOS.set_event()` / `DBOS.get_event()`, lets the workflow publish status that external callers read. All of it is persisted to the database.

With Resonate, you achieve the same effect by creating a Durable Promise that is not attached to any function execution, and then awaiting it. You can resolve it from anywhere, optionally sending data into the function while doing so.





```python title="DBOS — dbos-demo-apps/python/widget-store/widget_store/main.py"
@DBOS.workflow()
def checkout_workflow():
    # ...
    DBOS.set_event(PAYMENT_ID, DBOS.workflow_id)   # publish status to the caller
    payment_status = DBOS.recv(PAYMENT_STATUS)     # block until the webhook sends it
    # ...

# elsewhere, an HTTP handler delivers the decision:
DBOS.send(payment_id, payment_status, PAYMENT_STATUS)
```

```python title="Resonate — example-human-in-the-loop-py"
# worker.py
@resonate.register
async def foo(ctx: Context, workflow_id: str) -> str:
    blocking_promise = ctx.promise()
    promise_id = await blocking_promise.id()
    await ctx.run(send_email, promise_id)
    # ...
    # wait for the promise to be resolved
    data = await blocking_promise
    # ...
    return data
```

See it in action: [example-human-in-the-loop-py](https://github.com/resonatehq-examples/example-human-in-the-loop-py)

```python
# gateway.py — resolve from anywhere by promise id
from resonate.types import Value


async def approve(promise_id: str, data: str) -> None:
    await resonate.promises.resolve(promise_id, Value(data=data))
```





```typescript title="DBOS — dbos-demo-apps/typescript/widget-store/src/main.ts"
export const checkoutWorkflow = DBOS.registerWorkflow(
  async () => {
    // ...
    await DBOS.setEvent(PAYMENT_ID_EVENT, DBOS.workflowID);   // publish status
    const notification = await DBOS.recv<string>(PAYMENT_TOPIC, 120); // block, 120s timeout
    // ...
  },
  { name: 'checkoutWorkflow' },
);

// elsewhere, the payment webhook delivers it:
await DBOS.send(key, status, PAYMENT_TOPIC);
```

```typescript title="Resonate — example-human-in-the-loop-ts"
function* fooWorkflow(ctx: Context, workflowId: string) {
  const blockingPromise = yield* ctx.promise({});
  yield* ctx.run(sendEmail, blockingPromise.id);
  // ...
  // wait for the promise to be resolved
  const data = yield* blockingPromise;
  // ...
}
```

See it in action: [example-human-in-the-loop-ts](https://github.com/resonatehq-examples/example-human-in-the-loop-ts)

```typescript
// gateway.ts — resolve from anywhere; the data field is base64-encoded JSON
const data = Buffer.from(JSON.stringify(value), "utf8").toString("base64");
await resonate.promises.resolve(promiseId, { data });
```






The Resonate Rust equivalent awaits a latent durable promise and resolves it from anywhere:


```rust
// worker.rs
#[resonate::function]
async fn foo(ctx: &Context) -> Result<()> {
    // Latent durable promise — no function backing it. Resolved externally.
    let blocking_promise = ctx.promise::<bool>().create()?;
    let _promise_id = blocking_promise.id().await?;
    // ...
    // suspend until the promise is resolved (survives crashes)
    let _data = blocking_promise.await?;
    // ...
    Ok(())
}
```

See it in action: [example-human-in-the-loop-rs](https://github.com/resonatehq-examples/example-human-in-the-loop-rs)

```rust
use resonate::types::Value;

// resolve from anywhere
resonate
    .promises
    .resolve(&promise_id, Value::from_serializable(data)?)
    .await?;
```





```go title="DBOS — dbos-demo-apps/golang/widget-store/workflows.go"
func checkoutWorkflow(ctx dbos.DBOSContext, _ string) (string, error) {
    // ...
    err = dbos.SetEvent(ctx, PAYMENT_ID, workflowID)                       // publish status
    payment_status, err := dbos.Recv[string](ctx, PAYMENT_STATUS, 60*time.Second) // block
    // ...
}
```

```go title="Resonate — example-human-in-the-loop-go"
func foo(ctx *resonate.Context, _ struct{}) (string, error) {
	// Latent durable promise — no function backing it. Resolved externally.
	f, err := ctx.Promise()
	if err != nil {
		return "", err
	}
	promiseID := f.ID() // hand this ID to whoever resolves it
	_ = promiseID
	// ...
	// Await suspends the workflow until the promise settles (survives crashes).
	var data string
	if err := f.Await(&data); err != nil {
		return "", err
	}
	// ...
	return data, nil
}
```

See it in action: [example-human-in-the-loop-go](https://github.com/resonatehq-examples/example-human-in-the-loop-go)

```shell
# Resolve the latent promise from outside the running program — e.g. a human
# approving the request via the Resonate CLI or server API:
resonate promises resolve <promise-id> --value '{"headers": {}, "data": "\"approved\""}'
```





DBOS gives you a richer built-in messaging surface here — point-to-point `send`/`recv` plus key-value `setEvent`/`getEvent`, all addressed by workflow ID. Resonate collapses the same use case to one primitive: a latent Durable Promise the workflow awaits, resolvable from anywhere by its ID (HTTP-addressable through the Resonate Server).

## Saga / compensation

A saga runs a sequence of steps and, on failure, runs **compensations** to undo the completed ones. Neither DBOS nor Resonate ships a saga DSL — in both, you write the compensation in the failure branch and rely on durable execution to guarantee it runs to completion. DBOS checks each step's result and calls an explicit undo step on the failure path; Resonate writes the undo inline in a `try`/`catch`.





```python title="DBOS — dbos-demo-apps/python/widget-store/widget_store/main.py"
@DBOS.workflow()
def checkout_workflow():
    order_id = create_order()

    inventory_reserved = reserve_inventory()
    if not inventory_reserved:
        update_order_status(order_id=order_id, status=OrderStatus.CANCELLED.value)
        DBOS.set_event(PAYMENT_ID, None)
        return
    # ...
    if payment_status == "paid":
        update_order_status(order_id=order_id, status=OrderStatus.PAID.value)
        DBOS.start_workflow(dispatch_order_workflow, order_id)
    else:
        undo_reserve_inventory()                 # compensation
        update_order_status(order_id=order_id, status=OrderStatus.CANCELLED.value)
```

```python title="Resonate — example-money-transfer-py/main.py"
from resonate.retry import Never


async def transfer_money(ctx: Context, source, target, amount, *, simulate_credit_failure=False):
    transfer_id = ctx.info.id                    # the workflow id is the transfer id
    await ctx.run(apply_entry, f"{transfer_id}-debit", source, -amount, "debit")
    try:
        await ctx.options(retry_policy=Never()).run(
            credit_target, f"{transfer_id}-credit", target, amount,
            fail=simulate_credit_failure,
        )
    except Exception as err:
        # compensate inline
        await ctx.run(apply_entry, f"{transfer_id}-reversal", source, amount, "reversal")
        return {"transfer_id": transfer_id, "status": "compensated", "error": str(err)}
    return {"transfer_id": transfer_id, "status": "committed"}
```

See it in action: [example-money-transfer-py](https://github.com/resonatehq-examples/example-money-transfer-py)





```typescript title="DBOS — dbos-demo-apps/typescript/widget-store/src/main.ts"
export const checkoutWorkflow = DBOS.registerWorkflow(
  async () => {
    try {
      await subtractInventory();
    } catch (error) {
      await DBOS.setEvent(PAYMENT_ID_EVENT, null);
      return;
    }
    const orderID = await createOrder();
    // ...
    if (notification && notification === 'paid') {
      await markOrderPaid(orderID);
      await DBOS.startWorkflow(dispatchOrder)(orderID);
    } else {
      await errorOrder(orderID);
      await undoSubtractInventory();             // compensation
    }
  },
  { name: 'checkoutWorkflow' },
);
```

```typescript title="Resonate — example-saga-booking-ts/src/workflow.ts"
let flightId: string | undefined;
let hotelId: string | undefined;
try {
  flightId = yield* ctx.run(bookFlight, tripId);
  hotelId  = yield* ctx.run(bookHotel, tripId);
  const carId = yield* ctx.run(bookCarRental, tripId, shouldFail,
    ctx.options({ retryPolicy: noRetry }));
  return { status: "success", tripId, flightId, hotelId, carId };
} catch (error) {
  if (hotelId)  yield* ctx.run(cancelHotel, tripId, hotelId);
  if (flightId) yield* ctx.run(cancelFlight, tripId, flightId);
  return { status: "failed", tripId, error: (error as Error).message };
}
```

See it in action: [example-saga-booking-ts](https://github.com/resonatehq-examples/example-saga-booking-ts)






The Resonate Rust equivalent compensates inline in the error branch:


```rust title="Resonate — example-money-transfer-rs/src/main.rs"
#[resonate::function]
async fn transfer_money(ctx: &Context, args: TransferArgs) -> Result<TransferResult> {
    let debit_id = format!("{}-debit", args.transfer_id);
    let credit_id = format!("{}-credit", args.transfer_id);
    let reversal_id = format!("{}-reversal", args.transfer_id);

    // Step 1 — debit the source (durable checkpoint).
    ctx.run(apply_entry, EntryArgs {
        op_id: debit_id, account: args.source.clone(), amount: -args.amount, note: "debit".to_string(),
    }).await?;

    // Step 2 — credit the target; compensate on failure.
    let credit_outcome = ctx.run(credit_target, CreditArgs {
        op_id: credit_id, target: args.target.clone(), amount: args.amount, fail: args.simulate_credit_failure,
    }).await;

    if let Err(err) = credit_outcome {
        // compensating action — also durable + idempotent
        ctx.run(apply_entry, EntryArgs {
            op_id: reversal_id, account: args.source.clone(), amount: args.amount, note: "reversal".to_string(),
        }).await?;
        return Ok(TransferResult {
            transfer_id: args.transfer_id, status: "compensated".to_string(), error: Some(err.to_string()),
        });
    }
    Ok(TransferResult {
        transfer_id: args.transfer_id, status: "committed".to_string(), error: None,
    })
}
```

See it in action: [example-money-transfer-rs](https://github.com/resonatehq-examples/example-money-transfer-rs)





```go title="DBOS — dbos-demo-apps/golang/widget-store/workflows.go"
func checkoutWorkflow(ctx dbos.DBOSContext, _ string) (string, error) {
    // ... reserve inventory, await payment ...
    payment_status, err := dbos.Recv[string](ctx, PAYMENT_STATUS, 60*time.Second)
    if err != nil || payment_status != "paid" {
        dbos.RunAsStep(ctx, func(stepCtx context.Context) (string, error) {
            return undoReserveInventory(stepCtx)        // compensation
        })
        dbos.RunAsStep(ctx, func(stepCtx context.Context) (string, error) {
            return updateOrderStatus(stepCtx, UpdateOrderStatusInput{OrderID: orderID, OrderStatus: CANCELLED})
        })
    } else {
        // ... mark paid, dispatch ...
    }
    return "", nil
}
```


There is no `example-money-transfer-go` or `example-saga-booking-go` yet. The migration maps the same way as the other languages — `ctx.Run(...)` per step, compensation inline in the error branch — but until a Go example ships, treat this cell as a known gap rather than a worked sample.






## Distributed execution

With Resonate, you can run multiple Workers in a group, and Resonate will automatically load-balance invocations across them.
DBOS can also distribute work across multiple processes: you enqueue workflows onto durable queues that those processes poll, with the per-queue and per-process flow control described above.
The meaningful difference is in crash recovery, which we cover below.

Consider the following Resonate example.



    

```python
# worker.py
resonate = Resonate(
    url="http://localhost:8001",
    group="workers",
    # ...
)
```

See it in action: [example-load-balancing-py](https://github.com/resonatehq-examples/example-load-balancing-py)

```python
# client.py
resonate = Resonate(
    url="http://localhost:8001",
    group="client",
)

async def main():
    # ...
    handle = resonate.options(target="poll://any@workers").rpc(promise_id, "function_name", params)
    result = await handle.result()
```

    

    

```typescript
// worker.ts
const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "workers",
});
```

See it in action: [example-load-balancing-ts](https://github.com/resonatehq-examples/example-load-balancing-ts)

```typescript
//client.ts
const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "client",
});

async function main() {
  resonate.rpc(
    promiseId,
    "function_name",
    params,
    resonate.options({
      target: "poll://any@workers",
    })
  );
}
```

    

    

```rust
// worker.rs
let resonate = Resonate::new(ResonateConfig {
    url: Some("http://localhost:8001".into()),
    group: Some("workers".into()),
    ..Default::default()
});
```

See it in action: [example-load-balancing-rs](https://github.com/resonatehq-examples/example-load-balancing-rs)

```rust
// client.rs
let resonate = Resonate::new(ResonateConfig {
    url: Some("http://localhost:8001".into()),
    group: Some("client".into()),
    ..Default::default()
});

let result: u64 = resonate
    .rpc(&promise_id, "function_name", params)
    .target("poll://any@workers")
    .await?;
```

    

    

```go
// worker
r, _ := resonate.New(resonate.Config{
	Network: httpnet.NewHTTP("http://localhost:8001", httpnet.HTTPOptions{
		Group: "workers",
	}),
})
```

See it in action: [example-load-balancing-go](https://github.com/resonatehq-examples/example-load-balancing-go)

```go
// client
r, _ := resonate.New(resonate.Config{
	Network: httpnet.NewHTTP("http://localhost:8001", httpnet.HTTPOptions{
		Group: "client",
	}),
})

h, _ := r.RPC(context.Background(), promiseID, "function_name", params,
	resonate.RPCOptions{Target: "poll://any@workers"})
```

    



The meaningful difference is in crash recovery.
Resonate automatically recovers and resumes in-progress functions/workflows in another Worker, as part of its open-source core.

With DBOS, when a process restarts it recovers all the workflows that were executing on it before the restart. Recovering a workflow whose process has died onto a *different*, healthy process is the job of DBOS Conductor — a separate control-plane product that detects an unhealthy executor and signals another to take over its workflows. Without Conductor, each executor recovers only its own workflows on restart.

## Where DBOS and Resonate differ

Both systems value simplicity, add durability by wrapping ordinary functions, and run on infrastructure you already understand. Where they diverge:

**DBOS leans on what you already run.** Its strengths are real: durability from a couple of annotations; only Postgres in the loop (and an embedded SQLite file for Python local dev); durable queues with built-in concurrency limits, rate limits, priorities, and debouncing; a built-in observability dashboard and workflow-management APIs; exactly-once Kafka consumers; and SDKs in TypeScript, Python, Go, and Java.

**Resonate leans on a minimal core.** A Worker runs fully in-memory with no datastore until you connect one; the model is plain functions that compose and recurse without a workflow/step type split; automatic cross-process crash recovery ships in the open-source core; the server is a single binary; and you scale a decentralized topology by adding servers rather than sizing one service up front. Resonate also ships a Rust SDK, which DBOS does not.

Which fits depends on your constraints. If you want managed queues with rich flow control and a built-in dashboard on top of Postgres, DBOS gives you a lot out of the box. If you want a tiny core, an in-memory dev loop with no database, recursion as a first-class shape, and distributed recovery without a separate control plane, Resonate is built around those.

---

---
url: https://docs.resonatehq.io/evaluate/coming-from
title: Coming from
---



---

---
url: https://docs.resonatehq.io/evaluate/coming-from/restate
title: Restate vs Resonate
---

This page reflects `@resonatehq/sdk` v0.11.4 (current on npm) and `resonate-sdk` v0.7.4 for Python.



Since v0.11.0 the TypeScript SDK ships two interchangeable engines: the generator engine (`function*` with `yield* ctx.run(fn)`, shown in the examples on this page) and an async/await engine, where workflows are ordinary `async function`s and durable steps are `await ctx.run(() => ...)`. The async engine is imported from `@resonatehq/sdk/async`; its class is named `Resonate`. If you are coming from Restate, the async engine will look closest to what you already write.


**Are you coming from experience with Restate?**

This guide will help you understand the differences and similarities between Resonate and Restate, and how to translate Restate concepts to Resonate's programming model.

## Overview

Both Resonate and Restate provide durable execution for reliable distributed applications. However, they differ significantly in their approach:

| Aspect | Restate | Resonate |
|--------|---------|----------|
| **Core model** | Three service types (Basic Service, Virtual Object, Workflow) | Just functions - no proprietary types |
| **Server requirement** | Always requires Restate Server | Optional - zero-dependency local mode available |
| **Programming model** | ctx.run() wrappers, journaling/replay | Distributed async/await (native async syntax) |
| **Deployment** | Services → Endpoints → Registration with Restate Server | Deploy anywhere, connect when ready |
| **State management** | Built-in K/V store in Virtual Objects | Durable Promises (explicit, flexible) |
| **Learning curve** | Must understand 3 service types + deployment model | Familiar async/await patterns |

## Philosophy

**Restate's approach:** Define your application using three different service types depending on your needs (stateless handlers, stateful objects, or workflows), wrap non-deterministic operations in `ctx.run()`, and deploy behind endpoints that register with the Restate Server.

**Resonate's approach:** Write ordinary functions. A durable step is any call wrapped in `ctx.run()` — there is no service-type hierarchy to choose from, and no endpoint registration.

## Programming model

### Service types become just functions

Restate has three service types you must choose between:
- **Basic Service**: Stateless handlers
- **Virtual Object**: Stateful entity with a key
- **Workflow**: Once-per-ID execution with signals/queries

**In Resonate, there's no such distinction** — stateless handlers, stateful entities, and workflows are all written as ordinary functions.






    

```typescript title="Restate Basic Service"
import * as restate from "@restatedev/restate-sdk";

export const myService = restate.service({
  name: "MyService",
  handlers: {
    processOrder: async (ctx: restate.Context, order: Order) => {
      const payment = await ctx.run(() => processPayment(order));
      const shipment = await ctx.run(() => scheduleShipment(order));
      return { payment, shipment };
    },
  },
});

restate.serve({ services: [myService] });
```

    

    

```typescript title="Resonate - just a function"
import { Resonate, Context } from "@resonatehq/sdk";

const resonate = new Resonate();

function* processOrder(ctx: Context, order: Order) {
  const payment = yield* ctx.run(processPayment, order);
  const shipment = yield* ctx.run(scheduleShipment, order);
  return { payment, shipment };
}

resonate.register("processOrder", processOrder);
```

    



**Key difference:** No service wrapper, no handler object, no explicit serving. Just register the function.

### Durable steps

Both systems wrap non-deterministic operations to make them durable.



    

```typescript title="Restate durable step"
const result = await ctx.run<string>(async () => doDbRequest());
```

    

    

```typescript title="Resonate durable step"
const result = yield* ctx.run(doDbRequest);
```

    



Both achieve the same goal - making non-deterministic operations durable. Resonate's generator engine checkpoints the entire call stack automatically; the async/await engine (v0.11.0+) creates a durable promise eagerly at each `ctx.run()` call site.

### State management

**Restate:** Built-in K/V state in Virtual Objects and Workflows

```typescript title="Restate Virtual Object with state"
export const userAccount = restate.object({
  name: "UserAccount",
  handlers: {
    deposit: async (ctx: restate.ObjectContext, amount: number) => {
      const balance = (await ctx.get<number>("balance")) ?? 0;
      await ctx.set("balance", balance + amount);
      return balance + amount;
    },
  },
});
```

**Resonate:** Use Durable Promises for state or connect to external stores

```typescript title="Resonate with external state"
function* deposit(ctx: Context, userId: string, amount: number) {
  // Option 1: External database (your choice of DB)
  const balance = yield* ctx.run(getBalance, userId);
  const newBalance = balance + amount;
  yield* ctx.run(saveBalance, userId, newBalance);
  
  // Option 2: Durable Promise for workflow state
  const balancePromise = yield* ctx.promise();
  // ... resolve when ready
  
  return newBalance;
}
```

Resonate doesn't prescribe state storage - use what fits your architecture. Durable Promises provide coordination primitives when you need them.

### Workflows

Restate Workflows are a special service type for once-per-ID execution:

```typescript title="Restate Workflow"
export const orderWorkflow = restate.workflow({
  name: "OrderWorkflow",
  handlers: {
    run: async (ctx: restate.WorkflowContext, order: Order) => {
      // Main workflow logic
      const approved = await ctx.promise<boolean>("approval");
      if (approved) {
        await ctx.run(() => fulfillOrder(order));
      }
      return "complete";
    },
    
    approve: async (ctx: restate.WorkflowSharedContext) => {
      await ctx.promise("approval").resolve(true);
    },
  },
});
```

In Resonate, this is just a function with a Durable Promise:

```typescript title="Resonate workflow function"
function* orderWorkflow(ctx: Context, orderId: string, order: Order) {
  // ctx.promise() creates a child promise with ID `${ctx.id}.<seq>`.
  // Because the workflow was invoked with orderId as the execution ID,
  // the approval promise ID is deterministic: `${orderId}.0`.
  const approvalPromise = yield* ctx.promise<boolean>();
  const approved = yield* approvalPromise;

  if (approved) {
    yield* ctx.run(fulfillOrder, order);
  }

  return "complete";
}

// Approve from anywhere — the caller reconstructs the ID from orderId.
async function approveOrder(orderId: string) {
  await resonate.promises.resolve(`${orderId}.0`, { data: JSON.stringify(true) });
}
```

No special workflow service type, no separate handler methods - just functions and promises.


Each Durable Promise has a unique ID (like `approval-${orderId}`) that acts as the idempotency key. The same promise ID will always resolve to the same value, making workflows resumable and ensuring exactly-once semantics.


## Deployment and infrastructure

### Restate's model

1. Deploy services to your infrastructure (containers, Lambda, etc.)
2. Start Restate Server (single binary or cluster)
3. Register each service endpoint with the server:
   ```bash title="Register deployment with Restate"
   restate deployments register http://my-service:9080
   ```
4. Route requests through Restate Server

**Always requires Restate Server** as a proxy/coordinator in front of services.

### Resonate's model

**Development:** Zero-dependency mode - no server required

```typescript title="Local development mode"
const resonate = new Resonate(); // Runs locally, in-memory
```

**Production:** Connect to Resonate Server when ready

```typescript title="Production mode"
const resonate = new Resonate({
  url: "http://resonate-server:8001"
});
```


You can develop and test without any infrastructure. Add the server when you need distributed coordination, not before.


## Human-in-the-loop

Both systems support human-in-the-loop patterns.

**Restate:** Uses workflow promises or signals. The `ctx.promise()` API below is specific to Restate Workflows; Restate Services and Virtual Objects use awakeables instead (`ctx.awakeable<T>()`, which returns an ID and a promise).

```typescript title="Restate workflow promise"
// In workflow
const decision = await ctx.promise<string>("user-decision");

// From external handler
await ctx.promise("user-decision").resolve("approved");
```

**Resonate:** Uses Durable Promises

```typescript title="Resonate Durable Promise"
// In function — ctx.promise() creates `${ctx.id}.<seq>` deterministically.
const approvalPromise = yield* ctx.promise<string>();
const decision = yield* approvalPromise;

// From anywhere — use the caller's known execution ID (e.g. `order-123`)
// to reconstruct the approval promise ID as `${orderId}.<seq>`.
await resonate.promises.resolve(`${orderId}.0`, { data: JSON.stringify("approved") });
```

Same concept, similar API. Resonate's version works with any function, not just Workflows.

## Migration path

If you're moving from Restate to Resonate:

1. **Start simple:** Remove service type abstractions - your handlers become functions
2. **Adjust syntax:** The async engine (`@resonatehq/sdk/async`) is the closest match to Restate — `await ctx.run(() => fn())` carries over nearly unchanged. If you prefer the generator engine, the equivalent is `yield* ctx.run(fn)`.
3. **Rethink state:** If using Virtual Object state, decide whether to use external DB or Durable Promises
4. **Simplify deployment:** Remove endpoint registration step - just deploy and connect
5. **Test locally:** Take advantage of zero-dependency mode for faster iteration

## Why choose Resonate

Resonate offers:
- **Simpler primitives** - Just functions, not three service types
- **Zero-dependency local development** - Start building without infrastructure
- **Familiar async/await patterns** - Distributed async/await feels natural
- **Flexible state management** - Use your choice of database
- **No vendor lock-in** - Avoid proprietary abstractions
- **Gentler learning curve** - Less to learn, faster to ship

## Example: Order processing saga

Side-by-side comparison of the same workflow:



    

```typescript title="Restate order saga"
export const orderSaga = restate.service({
  name: "OrderSaga",
  handlers: {
    processOrder: async (ctx: restate.Context, order: Order) => {
      const payment = await ctx.run(() => chargePayment(order));
      
      try {
        const inventory = await ctx.run(() => reserveInventory(order));
        const shipment = await ctx.run(() => scheduleShipment(order, inventory));
        return { success: true, shipment };
      } catch (error) {
        await ctx.run(() => refundPayment(payment));
        throw error;
      }
    },
  },
});
```

    

    

```typescript title="Resonate order saga"
function* processOrder(ctx: Context, order: Order) {
  const payment = yield* ctx.run(chargePayment, order);
  
  try {
    const inventory = yield* ctx.run(reserveInventory, order);
    const shipment = yield* ctx.run(scheduleShipment, order, inventory);
    return { success: true, shipment };
  } catch (error) {
    yield* ctx.run(refundPayment, payment);
    throw error;
  }
}

resonate.register("processOrder", processOrder);
```

    



Same logic, fewer abstractions. The Resonate version is a plain function with generator syntax.

## Concepts mapping

| Restate Concept | Resonate Equivalent |
|----------------|---------------------|
| Basic Service | Registered function |
| Virtual Object | Function + external state or Durable Promise |
| Workflow | Function with Durable Promises |
| Handler | Function |
| ctx.run() | ctx.run() (generator or async engine) |
| ctx.promise() (workflow) | ctx.promise() (any function) |
| ctx.sleep() | ctx.sleep() |
| ctx.get/set (state) | External DB or Durable Promise |
| Service endpoint | Function registration |
| Deployment registration | Optional server connection |

## Next steps

- Try Resonate's [Quickstart](/get-started/quickstart) with zero-dependency mode
- Review [TypeScript SDK guide](/develop/typescript) for distributed async/await patterns
- Explore [example applications](/get-started/examples) for real-world patterns
- Join [Discord](https://discord.gg/resonate) to discuss migration questions

---

**Questions or feedback?** This comparison is a work in progress. If you're coming from Restate and have questions about concepts we haven't covered, let us know in Discord!

---

---
url: https://docs.resonatehq.io/evaluate/coming-from/temporal
title: Temporal vs Resonate
---

This page reflects `@resonatehq/sdk` v0.11.4 (TypeScript, current on npm), `resonate-sdk` v0.7.4 (Python), `resonate-sdk` v0.6.0 (Rust, on crates.io), and the Resonate Go SDK 0.1.0.


**Are you coming from Temporal?**

This guide is meant to help you understand the differences and similarities
between Temporal and Resonate — concept by concept, with side-by-side migration
code in every SDK.


Temporal blocks below are excerpted from the official
`temporalio/samples-{typescript,python,go}` repos and the Rust SDK's in-repo
examples (`temporalio/sdk-rust/crates/sdk/examples/`) — trimmed for focus,
elisions marked, never rewritten. Resonate blocks come from the [examples
library](https://github.com/resonatehq-examples), pinned to the latest released
SDKs. Some patterns don't have a Resonate example in every language yet; those
gaps are noted inline.


## Durability

One of Temporal’s core value propositions is Durable Execution.
Essentially, Durable Execution is the ability for a function to recover in another process after a hard failure and resume from where it left off.

Resonate also provides Durable Execution.

In Resonate, if your process crashes, your function can recover and resume from where it left off in another process.

## Programming model

If you have experience with Temporal, then you are familiar with thinking in terms of Workflows and Activities.

Resonate does not have proprietary function types such as Workflows and Activities; it just uses functions.

Here is the most basic migration — a Workflow that calls one Activity, and the equivalent Resonate function calling one step:





```python title="Temporal — samples-python/hello/hello_activity.py"
@activity.defn
def compose_greeting(input: ComposeGreetingInput) -> str:
    return f"{input.greeting}, {input.name}!"

@workflow.defn
class GreetingWorkflow:
    @workflow.run
    async def run(self, name: str) -> str:
        return await workflow.execute_activity(
            compose_greeting,
            ComposeGreetingInput("Hello", name),
            start_to_close_timeout=timedelta(seconds=10),
        )
```

```python title="Resonate — example-hello-world-py/main.py"
def bar(_: Context, greetee: str) -> str:
    return f"Hello {greetee} from bar!"

@resonate.register
async def foo(ctx: Context, greetee: str) -> str:
    bar_greeting = await ctx.run(bar, greetee=greetee)
    return bar_greeting
```

See it in action: [example-hello-world-py](https://github.com/resonatehq-examples/example-hello-world-py)





```typescript title="Temporal — samples-typescript/hello-world/src/workflows.ts + activities.ts"
// activities.ts
export async function greet(name: string): Promise<string> {
  return `Hello, ${name}!`;
}

// workflows.ts
const { greet } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

export async function example(name: string): Promise<string> {
  return await greet(name);
}
```

```typescript title="Resonate — example-hello-world-ts/index.ts"
async function bar(_: Context, greetee: string): Promise<string> {
  return `Hello ${greetee} from bar!`;
}

function* foo(ctx: Context, greetee: string): Generator<any, string, any> {
  const barGreeting = yield* ctx.run(bar, greetee);
  return barGreeting;
}

const fooR = resonate.register("foo", foo);
```

See it in action: [example-hello-world-ts](https://github.com/resonatehq-examples/example-hello-world-ts)





```rust title="Temporal — sdk-rust/crates/sdk/examples/hello_world/workflows.rs"
#[workflow]
pub struct HelloWorldWorkflow;

#[workflow_methods]
impl HelloWorldWorkflow {
    #[run]
    pub async fn run(ctx: &mut WorkflowContext<Self>, name: String) -> WorkflowResult<String> {
        ctx.start_activity(
            GreetingActivities::greet, name,
            ActivityOptions::start_to_close_timeout(Duration::from_secs(10)),
        ).await
    }
}

#[activities]
impl GreetingActivities {
    #[activity]
    pub async fn greet(_ctx: ActivityContext, name: String) -> Result<String, ActivityError> {
        Ok(format!("Hello, {}!", name))
    }
}
```

```rust title="Resonate — example-hello-world-rs/src/main.rs"
#[resonate::function]
async fn greet(ctx: &Context, name: String) -> Result<String> {
    let greeting = ctx.run(format_greeting, name).await?;
    Ok(greeting)
}

#[resonate::function]
async fn format_greeting(name: String) -> Result<String> {
    Ok(format!("Hello, {name}!"))
}
```

See it in action: [example-hello-world-rs](https://github.com/resonatehq-examples/example-hello-world-rs)





```go title="Temporal — samples-go/helloworld/helloworld.go"
func Workflow(ctx workflow.Context, name string) (string, error) {
    ao := workflow.ActivityOptions{StartToCloseTimeout: 10 * time.Second}
    ctx = workflow.WithActivityOptions(ctx, ao)

    var result string
    err := workflow.ExecuteActivity(ctx, Activity, name).Get(ctx, &result)
    return result, err
}

func Activity(ctx context.Context, name string) (string, error) {
    return "Hello " + name + "!", nil
}
```

```go title="Resonate — example-hello-world-go/main.go"
func greet(_ *resonate.Context, args GreetArgs) (string, error) {
    return fmt.Sprintf("hello, %s!", args.Name), nil
}

func main() {
    r, _ := resonate.New(resonate.Config{URL: "http://localhost:8001"})
    defer r.Stop()

    greetFn, _ := resonate.Register(r, "greet", greet)
    h, _ := greetFn.Run(ctx, id, GreetArgs{Name: "world"})
    out, _ := h.Result(ctx)
    fmt.Println(out)
}
```

See it in action: [example-hello-world-go](https://github.com/resonatehq-examples/example-hello-world-go)





`@resonate.register` (and its per-SDK equivalents) replaces the `@workflow.defn` / `@activity.defn` split. A step is just a function passed to `ctx.run` — no Task Queue wiring, no mandatory timeout policy.

Resonate promotes a procedural programming model that enables you to compose functions indefinitely and recursively.

Consider this factorial example.
How might you implement it in Temporal?






    

```python
@resonate.register
async def factorial(ctx: Context, n: int) -> int:
    if n <= 1:
        return 1
    r = await ctx.options(target="factorial-workers").rpc("factorial", n - 1)
    return n * r


async def main():
    handle = resonate.run("factorial-5", factorial, n=5)
    result = await handle.result()
    print(result)
```

See it in action: [example-recursive-factorial-py](https://github.com/resonatehq-examples/example-recursive-factorial-py)

    


    

```typescript
function* factorial(ctx: Context, n: number): Generator<any, number, any> {
  if (n <= 1) {
    return 1;
  }
  const result = yield* ctx.rpc(
    "factorial",
    n - 1,
    ctx.options({ target: "poll://any@factorial-workers" }),
  );

  return n * result;
}

const factorialR = resonate.register("factorial", factorial);

async function main() {
  const result = await factorialR.run("factorial-5", 5);
  console.log(result);
}
```

See it in action: [example-recursive-factorial-ts](https://github.com/resonatehq-examples/example-recursive-factorial-ts)

    

    

```rust
#[resonate::function]
async fn factorial(ctx: &Context, n: u64) -> Result<u64> {
    if n <= 1 {
        return Ok(1);
    }
    let result: u64 = ctx
        .rpc("factorial", n - 1)
        .target("poll://any@factorial-workers")
        .await?;

    Ok(n * result)
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::local();
    resonate.register(factorial).unwrap();

    let result: u64 = resonate.run("factorial-5", factorial, 5).await.unwrap();
    println!("{result}");

    resonate.stop().await.unwrap();
}
```

See it in action: [example-recursive-factorial-rs](https://github.com/resonatehq-examples/example-recursive-factorial-rs)

    

    

```go
type Args struct {
	N int `json:"n"`
}

func factorial(ctx *resonate.Context, args Args) (int, error) {
	if args.N <= 1 {
		return 1, nil
	}
	f, err := ctx.RPC("factorial", Args{N: args.N - 1})
	if err != nil {
		return 0, err
	}
	var result int
	if err := f.Await(&result); err != nil {
		return 0, err
	}
	return args.N * result, nil
}

func main() {
	r, _ := resonate.New(resonate.Config{URL: "http://localhost:8001"})
	defer func() { _ = r.Stop() }()

	factorialFn, _ := resonate.Register(r, "factorial", factorial)

	h, _ := factorialFn.Run(context.Background(), "factorial-5", Args{N: 5})
	result, _ := h.Result(context.Background())
	fmt.Println(result)
}
```

See it in action: [example-recursive-factorial-go](https://github.com/resonatehq-examples/example-recursive-factorial-go)

    



In Temporal, recursion like this means **child workflows** (`executeChild` / `ExecuteChildWorkflow`) — each a separately registered Workflow type, each accruing its own event history. That history accounting is what makes deep or unbounded recursion awkward in Temporal; in Resonate a function simply calls itself by its registered name (`ctx.run` / `ctx.rpc`), with no separate type and no per-child history to manage.

## Zero-dependency development

In Temporal, you always need a Temporal Service for your Worker to connect to, whether that is a local development instance or a production instance.

Resonate offers a zero-dependency development experience, where a Worker (single node application) can run without connecting to a Resonate Server.



    

```python
from resonate.resonate import Resonate

resonate = Resonate()  # no url, no RESONATE_URL/RESONATE_HOST env -> in-memory, no server

#...
```

    

    

```typescript
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

// ...
```

    

    

```rust
use resonate::prelude::*;

let resonate = Resonate::local();

// ...
```

    

    

```go
import (
	resonate "github.com/resonatehq/resonate-sdk-go"
	"github.com/resonatehq/resonate-sdk-go/localnet"
)

// Local development mode runs the server state machine in-process,
// using in-memory storage for promises and tasks.
pid := "dev-worker"
r, _ := resonate.New(resonate.Config{
	Network:   localnet.NewLocal("default", &pid),
	Heartbeat: resonate.NoopHeartbeat{}, // localnet has no lease endpoint to heartbeat against
})

// ...
```

    



## Human-in-the-loop

In Temporal, you can use Signals to unblock a Workflow Execution with input from a human — define a signal, register a handler, flip a flag, and `await` a condition:





```python title="Temporal — samples-python/hello/hello_signal.py"
@workflow.defn
class GreetingWorkflow:
    @workflow.run
    async def run(self) -> List[str]:
        greetings: List[str] = []
        while True:
            await workflow.wait_condition(
                lambda: not self._pending_greetings.empty() or self._exit)
            # …drain self._pending_greetings into greetings…
            if self._exit:
                return greetings

    @workflow.signal
    def exit(self) -> None:
        self._exit = True
```

```python title="Unblock it externally"
await handle.signal(GreetingWorkflow.exit)
```





```typescript title="Temporal — samples-typescript/signals-queries/src/workflows.ts"
export const unblockSignal = wf.defineSignal('unblock');
export const isBlockedQuery = wf.defineQuery<boolean>('isBlocked');

export async function unblockOrCancel(): Promise<void> {
  let isBlocked = true;
  wf.setHandler(unblockSignal, () => void (isBlocked = false));
  wf.setHandler(isBlockedQuery, () => isBlocked);
  await wf.condition(() => !isBlocked);              // blocks here
}
```

```typescript title="Unblock it externally"
await handle.signal(unblockSignal);
```





```rust title="Temporal — sdk-rust/crates/sdk/examples/message_passing/workflows.rs"
#[workflow]
pub struct MessagePassingWorkflow { counter: i32 }

#[workflow_methods]
impl MessagePassingWorkflow {
    #[run]
    pub async fn run(ctx: &mut WorkflowContext<Self>, target: i32) -> WorkflowResult<i32> {
        ctx.wait_condition(|s| s.counter >= target).await;   // blocks here
        Ok(ctx.state(|s| s.counter))
    }

    #[signal]
    pub fn increment(&mut self, _ctx: &mut SyncWorkflowContext<Self>, amount: i32) {
        self.counter += amount;
    }
}
```

Unblock it externally by sending the `increment` signal. The Resonate Rust
equivalent is in the tabs below.





```go title="Temporal — samples-go/await-signals/await_signals_workflow.go (excerpt)"
func AwaitSignalsWorkflow(ctx workflow.Context) (err error) {
    var a AwaitSignals
    workflow.Go(ctx, a.Listen)                     // signal handlers in a goroutine
    err = workflow.Await(ctx, func() bool {        // blocks until Signal1 arrives
        return a.Signal1Received
    })
    // … then awaits Signal2 and Signal3 via workflow.AwaitWithTimeout …
    return
}
// a.Listen: selector.AddReceive(workflow.GetSignalChannel(ctx, "Signal1"), …)
```





With Resonate, you can achieve the same effect by creating a Durable Promise that is not attached to any function execution, and then await on it.
Then, you can resolve it from anywhere, optionally sending data into the function while doing so.



    

```python
# worker.py
@resonate.register
async def foo(ctx: Context) -> str:
    blocking_promise = ctx.promise()
    promise_id = await blocking_promise.id()
    # ... hand promise_id to the human, e.g. via a leaf that emails/pages them ...
    # wait for the promise to be resolved
    data = await blocking_promise
    # ...
    return data
```

See it in action: [example-human-in-the-loop-py](https://github.com/resonatehq-examples/example-human-in-the-loop-py)

```python
# client.py
from resonate.types import Value

async def main():
    # ...
    await resonate.promises.resolve(promise_id, Value(data=data))
```

    

    

```typescript
function* foo(context: Context) {
  const blockingPromise = yield* context.promise();
  // ...
  // wait for the promise to be resolved
  data = yield* blockingPromise;
  // ...
}
```

See it in action: [example-human-in-the-loop-ts](https://github.com/resonatehq-examples/example-human-in-the-loop-ts)

```typescript
// client.ts
// promises.resolve does not run the codec, so encode the payload the way the
// codec expects: JSON → base64 string in the `data` field.
const data = Buffer.from(JSON.stringify(value), "utf8").toString("base64");
await resonate.promises.resolve(promiseId, { data });
```

    

    

```rust
// worker.rs
#[resonate::function]
async fn foo(ctx: &Context) -> Result<()> {
    // Latent durable promise — no function backing it. Resolved externally.
    let blocking_promise = ctx.promise::<bool>().create()?;
    let _promise_id = blocking_promise.id().await?;
    // ...
    // suspend until the promise is resolved (survives crashes)
    let _data = blocking_promise.await?;
    // ...
    Ok(())
}
```

See it in action: [example-human-in-the-loop-rs](https://github.com/resonatehq-examples/example-human-in-the-loop-rs)

```rust
use resonate::types::Value;

// resolve from anywhere
resonate
    .promises
    .resolve(&promise_id, Value::from_serializable(data)?)
    .await?;
```

    

    

```go
func foo(ctx *resonate.Context, _ struct{}) (string, error) {
	// Latent durable promise — no function backing it. Resolved externally.
	f, err := ctx.Promise()
	if err != nil {
		return "", err
	}
	promiseID := f.ID() // hand this ID to whoever resolves it
	_ = promiseID
	// ...
	// Await suspends the workflow until the promise settles (survives crashes).
	var data string
	if err := f.Await(&data); err != nil {
		return "", err
	}
	// ...
	return data, nil
}
```

See it in action: [example-human-in-the-loop-go](https://github.com/resonatehq-examples/example-human-in-the-loop-go)

```shell
# Resolve the latent promise from outside the running program — e.g. a human
# approving the request via the Resonate CLI or server API.
# `data` must be a JSON-quoted string: the CLI base64-encodes it before storing,
# and the worker's codec base64-decodes then JSON-parses it. A bare "approved"
# would decode to the bytes `approved`, which is not valid JSON (DecodingError).
resonate promises resolve <promise-id> --value '{"headers": {}, "data": "\"approved\""}'
```

    



## Durable timers

Temporal's `sleep-for-days` shows a durable timer racing against a signal. Resonate's equivalent is `ctx.sleep` — a single durable promise that survives crashes.


Temporal accepts human strings (`'30 days'`) or a `timedelta`. Resonate's units differ **per SDK**: TypeScript takes **milliseconds**, Python takes a `timedelta`, Go and Rust take a native `Duration`. Converting `'30 days'` for the TS SDK means `30 * 24 * 60 * 60 * 1000`.






```python title="Temporal — samples-python/sleep_for_days/workflows.py"
# raced against a completion signal inside asyncio.wait(...):
await workflow.sleep(timedelta(days=30))   # timedelta
```

```python title="Resonate — example-durable-sleep-py/worker.py"
@resonate.register
async def sleeping_workflow(ctx: Context, wf_id: str, secs: float) -> str:
    await ctx.sleep(timedelta(seconds=secs))    # timedelta, not a bare number
    return f"Workflow {wf_id} slept for {secs} seconds."
```

See it in action: [example-durable-sleep-py](https://github.com/resonatehq-examples/example-durable-sleep-py)





```typescript title="Temporal — samples-typescript/sleep-for-days/src/workflows.ts"
await Promise.race([sleep('30 days'), condition(() => isComplete)]);
```

```typescript title="Resonate — example-durable-sleep-ts/worker.ts"
function* sleepingWorkflow(ctx: Context, ms: number) {
  yield* ctx.sleep(ms);                     // milliseconds
  return `Slept for ${ms / 1000} seconds`;
}
```

See it in action: [example-durable-sleep-ts](https://github.com/resonatehq-examples/example-durable-sleep-ts)





```rust title="Temporal — sdk-rust/crates/sdk/examples/timer_examples/workflows.rs"
#[run]
pub async fn run(ctx: &mut WorkflowContext<Self>) -> WorkflowResult<String> {
    ctx.timer(Duration::from_secs(1)).await;   // durable timer
    // …select! race + cancellable-timer demo omitted…
}
```

```rust title="Resonate — example-durable-sleep-rs/src/bin/worker.rs"
#[resonate::function]
async fn sleeping_workflow(ctx: &Context, secs: u64) -> Result<String> {
    ctx.sleep(Duration::from_secs(secs)).await?;   // std::time::Duration
    Ok(format!("Slept for {secs} seconds"))
}
```

See it in action: [example-durable-sleep-rs](https://github.com/resonatehq-examples/example-durable-sleep-rs)





```go title="Temporal — samples-go/sleep-for-days/sleepfordays_workflow.go"
selector := workflow.NewSelector(ctx)
selector.AddFuture(workflow.NewTimer(ctx, time.Hour*24*30), func(f workflow.Future) {})
selector.AddReceive(sigChan, func(c workflow.ReceiveChannel, more bool) { isComplete = true })
selector.Select(ctx)
```

```go title="Resonate — example-durable-sleep-go/main.go"
func sleepingWorkflow(ctx *resonate.Context, args SleepArgs) (string, error) {
    d := time.Duration(args.Secs) * time.Second
    f, err := ctx.Sleep(d)                   // time.Duration
    if err != nil {
        return "", err
    }
    if err := f.Await(nil); err != nil {     // Await(nil) — no return value
        return "", err
    }
    return fmt.Sprintf("slept for %d second(s)", args.Secs), nil
}
```

See it in action: [example-durable-sleep-go](https://github.com/resonatehq-examples/example-durable-sleep-go)





## Fan-out / fan-in

Start many units of work in parallel, then join all results. In Temporal you spawn activities (or children) without awaiting, then await them together. Resonate is the same shape: start each with a non-blocking invocation, then await each promise.


The non-blocking spawn step — TS `ctx.beginRun`, Rust `.spawn()`, Go `ctx.RPC` — each returns a future immediately; you await them after all are started. Python needs no separate spawn call: `ctx.run`/`ctx.rpc` already return a future the moment they're called, so fanning out is just calling several before awaiting any of them.






```python title="Temporal — samples-python/hello/hello_parallel_activity.py"
results = await asyncio.gather(
    workflow.execute_activity(say_hello_activity, "user1", start_to_close_timeout=timedelta(seconds=5)),
    workflow.execute_activity(say_hello_activity, "user2", start_to_close_timeout=timedelta(seconds=5)),
    # …user3 … user5 …
)
```

```python title="Resonate — example-fan-out-fan-in-py/workflow.py"
# fan-out: ctx.run returns a future immediately, without blocking
email_f = ctx.run(send_email, event)
sms_f = ctx.run(send_sms, event)
# fan-in: await each
email = await email_f
sms = await sms_f
```

See it in action: [example-fan-out-fan-in-py](https://github.com/resonatehq-examples/example-fan-out-fan-in-py)





```typescript title="Temporal — samples-typescript/child-workflows/src/workflows.ts"
const responseArray = await Promise.all(
  names.map((name) => executeChild(childWorkflow, { args: [name] })),
);
```

```typescript title="Resonate — example-fan-out-fan-in-ts/src/workflow.ts"
// fan-out: beginRun returns a future immediately
const emailFuture = yield* ctx.beginRun(sendEmail, event);
const smsFuture   = yield* ctx.beginRun(sendSms, event);
// fan-in: await each
const results = [yield* emailFuture, yield* smsFuture];
```

See it in action: [example-fan-out-fan-in-ts](https://github.com/resonatehq-examples/example-fan-out-fan-in-ts)





**Temporal Rust has no dedicated fan-out sample** — its `child_workflows` example starts children sequentially. The Resonate Rust equivalent fans out with `.spawn()`:

```rust title="Resonate — example-fan-out-fan-in-rs/src/main.rs"
// fan-out: .spawn() returns a handle immediately
let h1 = ctx.run(process_item, items[0].clone()).spawn()?;
let h2 = ctx.run(process_item, items[1].clone()).spawn()?;
// fan-in: await each
let r1 = h1.await?;
let r2 = h2.await?;
```

See it in action: [example-fan-out-fan-in-rs](https://github.com/resonatehq-examples/example-fan-out-fan-in-rs)





```go title="Temporal — samples-go/splitmerge-future/splitmerge_workflow.go"
var results []workflow.Future
for i := 0; i < processorCount; i++ {                    // fan-out
    results = append(results, workflow.ExecuteActivity(ctx, ChunkProcessingActivity, i+1))
}
for i := 0; i < processorCount; i++ {                    // fan-in
    var r ChunkResult
    _ = results[i].Get(ctx, &r)
}
```

```go title="Resonate — example-fan-out-fan-in-go/main.go"
futures := make([]*resonate.Future, 0, len(args.Channels))
for _, ch := range args.Channels {                       // fan-out
    f, _ := ctx.RPC("send", SendArgs{Channel: ch, Message: args.Message})
    futures = append(futures, f)
}
for _, f := range futures {                              // fan-in
    var d Delivery
    _ = f.Await(&d)
}
```

See it in action: [example-fan-out-fan-in-go](https://github.com/resonatehq-examples/example-fan-out-fan-in-go)





## Saga / compensation

A saga runs a sequence of steps and, on failure, runs **compensations** to undo the completed ones. Temporal's samples register compensation closures and drain them on error. Resonate's examples write the compensation inline in a `try`/`catch`, because the durable generator itself is the recovery record.





**Temporal** — `samples-python/message_passing/waiting_for_handlers_and_compensation/workflows.py` (the compensation itself is a single activity call):

```python
async def workflow_compensation(self):
    await workflow.execute_activity(
        activity_executed_to_perform_workflow_compensation,
        start_to_close_timeout=timedelta(seconds=10),
    )
```

```python title="Resonate — example-money-transfer-py/main.py"
from resonate.retry import Never


async def transfer_money(ctx: Context, source, target, amount, *, simulate_credit_failure=False):
    transfer_id = ctx.info.id                    # the workflow id is the transfer id
    await ctx.run(apply_entry, f"{transfer_id}-debit", source, -amount, "debit")
    try:
        await ctx.options(retry_policy=Never()).run(
            credit_target, f"{transfer_id}-credit", target, amount,
            fail=simulate_credit_failure,
        )
    except Exception as err:
        # compensate inline
        await ctx.run(apply_entry, f"{transfer_id}-reversal", source, amount, "reversal")
        return {"transfer_id": transfer_id, "status": "compensated", "error": str(err)}
    return {"transfer_id": transfer_id, "status": "committed"}
```

See it in action: [example-money-transfer-py](https://github.com/resonatehq-examples/example-money-transfer-py)





```typescript title="Temporal — samples-typescript/saga/src/workflows.ts"
const compensations: Compensation[] = [];
try {
  await addAddress({ accountId, address });
  compensations.unshift({ message: '…', fn: () => clearPostalAddresses({ accountId }) });

  // …addClient + its compensation omitted for brevity…
  await addBankAccount({ accountId, details });
  compensations.unshift({ message: '…', fn: () => disconnectBankAccounts({ accountId }) });
} catch (err) {
  await compensate(compensations);   // drains the stack LIFO
  throw err;
}
```

```typescript title="Resonate — example-saga-booking-ts/src/workflow.ts"
let flightId: string | undefined;
let hotelId: string | undefined;
try {
  flightId = yield* ctx.run(bookFlight, tripId);
  hotelId  = yield* ctx.run(bookHotel, tripId);
  const carId = yield* ctx.run(bookCarRental, tripId, shouldFail,
    ctx.options({ retryPolicy: noRetry }));
  return { status: "success", tripId, flightId, hotelId, carId };
} catch (error) {
  if (hotelId)  yield* ctx.run(cancelHotel, tripId, hotelId);
  if (flightId) yield* ctx.run(cancelFlight, tripId, flightId);
  return { status: "failed", tripId, error: (error as Error).message };
}
```

Temporal pushes typed `Compensation` closures onto a stack and drains it in a separate `compensate()` function. Resonate writes the undo inline in `catch`, guarded by `if (hotelId)` — no stack, no helper.

See it in action: [example-saga-booking-ts](https://github.com/resonatehq-examples/example-saga-booking-ts)





```rust title="Temporal — sdk-rust/crates/sdk/examples/saga/workflows.rs"
#[run]
pub async fn run(ctx: &mut WorkflowContext<Self>, trip_id: String) -> WorkflowResult<Vec<String>> {
    let mut saga = Saga::new(ctx, activity_opts());
    match Self::book_trip(&mut saga, trip_id).await {
        Ok(ids) => Ok(ids),
        Err(e) => { saga.compensate().await; Err(e.into()) }   // run compensations
    }
}
// book_trip: saga.step(book_hotel, …, cancel_hotel).await? — one step + compensation per booking
```

```rust title="Resonate — example-money-transfer-rs/src/main.rs"
#[resonate::function]
async fn transfer_money(ctx: &Context, args: TransferArgs) -> Result<TransferResult> {
    // Step 1 — debit the source (durable checkpoint).
    ctx.run(apply_entry, EntryArgs {
        op_id: format!("{}-debit", args.transfer_id),
        account: args.source.clone(),
        amount: -args.amount,
        note: "debit".to_string(),
    }).await?;

    // Step 2 — credit the target; on failure, compensate by reversing the debit.
    let credit_outcome = ctx.run(credit_target, CreditArgs {
        op_id: format!("{}-credit", args.transfer_id),
        target: args.target.clone(),
        amount: args.amount,
        fail: args.simulate_credit_failure,
    }).await;

    if let Err(err) = credit_outcome {
        // compensate inline — also durable + idempotent
        ctx.run(apply_entry, EntryArgs {
            op_id: format!("{}-reversal", args.transfer_id),
            account: args.source.clone(),
            amount: args.amount,
            note: "reversal".to_string(),
        }).await?;
        return Ok(TransferResult {
            transfer_id: args.transfer_id,
            status: "compensated".to_string(),
            error: Some(err.to_string()),
        });
    }

    Ok(TransferResult {
        transfer_id: args.transfer_id,
        status: "committed".to_string(),
        error: None,
    })
}
```

See it in action: [example-money-transfer-rs](https://github.com/resonatehq-examples/example-money-transfer-rs)





**Temporal** — `samples-go/saga/workflow.go` (uses stacked `defer` for LIFO compensation):

```go
func TransferMoney(ctx workflow.Context, td TransferDetails) (err error) {
    err = workflow.ExecuteActivity(ctx, Withdraw, td).Get(ctx, nil)
    if err != nil { return err }
    defer func() {
        if err != nil {
            errC := workflow.ExecuteActivity(ctx, WithdrawCompensation, td).Get(ctx, nil)
            err = multierr.Append(err, errC)
        }
    }()

    err = workflow.ExecuteActivity(ctx, Deposit, td).Get(ctx, nil)
    // …Deposit's own defer-compensation + a final failing step omitted for brevity…
    return err
}
```


There is currently no `example-saga-booking-go` or `example-money-transfer-go`. The migration maps the same way as the other languages — `ctx.Run(...)` per step, compensation inline in the error branch — but until a Go example ships, treat this cell as a known gap rather than a worked sample.






## Long-running loops

Temporal's `continue-as-new` exists to reset a Workflow's event history before it hits the size limit. Resonate has no per-execution event history that grows unboundedly, so for finite loops you just… loop.


For bounded loops, the Resonate example is a plain `while`/`for` — no `continue-as-new` needed. **But** for *truly unbounded* loops, a naive loop in a single durable invocation accumulates child promises that get re-walked on replay; once replay time exceeds the task lease, the worker loop stalls and stops making progress. The production-correct pattern is `ctx.detached` **tail-recursion** (the SDK docblock calls this out explicitly). The shipped examples below use the naive loop, which is correct for demos and bounded counts; reach for `detached` when the loop is genuinely infinite.






```typescript title="Temporal — samples-typescript/continue-as-new/src/workflows.ts"
export async function loopingWorkflow(iteration = 0): Promise<void> {
  if (iteration === 10) return;
  await sleep(1000);
  await continueAsNew<typeof loopingWorkflow>(iteration + 1);
}
```

```typescript title="Resonate — example-infinite-workflow-ts/src/workflow.ts"
function* healthMonitor(ctx: Context, config: MonitorConfig): Generator<any, MonitorResult, any> {
  let iteration = 0;
  // No continueAsNew — Resonate has no history limit.
  while (iteration < config.maxIterations) {
    iteration++;
    yield* ctx.run(checkAllServices, config.services, iteration);
    if (iteration < config.maxIterations) yield* ctx.sleep(config.intervalMs);
  }
  // ...
}
```

For a genuinely unbounded loop, split per-iteration with `ctx.detached` (from the SDK docblock):

```typescript
function* playGame(ctx: Context, n: number) {
  // ...one iteration of work...
  yield* ctx.detached(playGame, n + 1);   // tail call, then return
}
```

See it in action: [example-infinite-workflow-ts](https://github.com/resonatehq-examples/example-infinite-workflow-ts)





```go title="Temporal — samples-go/child-workflow-continue-as-new/child_workflow.go"
func SampleChildWorkflow(ctx workflow.Context, totalCount, runCount int) (string, error) {
    if runCount <= 0 {
        return "", errors.New("invalid run count")
    }
    totalCount++
    runCount--
    if runCount == 0 {
        return fmt.Sprintf("completed after %v runs", totalCount), nil
    }
    return "", workflow.NewContinueAsNewError(ctx, SampleChildWorkflow, totalCount, runCount)
}
```

```go title="Resonate — example-infinite-workflow-go/main.go"
func heartbeatWorkflow(ctx *resonate.Context, args WorkflowArgs) (WorkflowResult, error) {
    for i := 0; args.Iterations == 0 || i < args.Iterations; i++ {
        tickF, err := ctx.Run(heartbeatTick, TickArgs{Tick: i + 1})
        if err != nil { return WorkflowResult{}, err }
        if err := tickF.Await(nil); err != nil { return WorkflowResult{}, err }

        sleepF, err := ctx.Sleep(time.Duration(args.IntervalSec) * time.Second)
        if err != nil { return WorkflowResult{}, err }
        if err := sleepF.Await(nil); err != nil { return WorkflowResult{}, err }
    }
    return WorkflowResult{Ticks: args.Iterations}, nil
}
```

The Go SDK also has `ctx.Detached` for the unbounded case; the shipped example uses a plain `for` loop.

See it in action: [example-infinite-workflow-go](https://github.com/resonatehq-examples/example-infinite-workflow-go)






`example-infinite-workflow-py` does not exist. Temporal's source is `samples-python/hello/hello_continue_as_new.py` (`workflow.continue_as_new(iteration + 1)`). The Resonate equivalent is a plain `while` loop (`while … : await ctx.run(...) ; await ctx.sleep(...)`), with `ctx.detached("workflow_name", n + 1)` for the unbounded case (`detached` dispatches by registered name, not by function reference) — but until an example ships, treat this as a known gap.







`example-infinite-workflow-rs` does not exist yet. Temporal's Rust `continue_as_new` example (`sdk-rust/crates/sdk/examples/continue_as_new`) maps to a plain Resonate `loop`/`while` with `ctx.detached` for the unbounded case — treat the missing Resonate example as a known gap until one ships.






## Distributed mutex

Temporal's `mutex` sample is ~130 lines across two workflows: a lock-manager workflow with a signal queue, `uuid4()` release tokens, `continueAsNew` for history management, and timeout-based deadlock prevention. In Resonate, the generator itself is the lock.


This pattern currently has a Resonate example in TypeScript only.


```typescript title="Temporal — samples-typescript/mutex/src/workflows.ts (excerpt)"
export async function lockWorkflow(requests = Array<LockRequest>()): Promise<void> {
  setHandler(lockRequestSignal, (req) => { requests.push(req); });
  while (!workflowInfo().continueAsNewSuggested) {
    await condition(() => requests.length > 0);
    const req = requests.shift()!;
    const releaseSignalName = uuid4();
    await getExternalWorkflowHandle(req.initiatorId).signal(lockAcquiredSignal, { releaseSignalName });
    let released = false;
    setHandler(defineSignal(releaseSignalName), () => { released = true; });
    await condition(() => released, req.timeoutMs);   // auto-release on timeout
  }
  if (requests.length > 0) await continueAsNew<typeof lockWorkflow>(requests);
}
```

```typescript title="Resonate — example-distributed-mutex-ts/src/workflow.ts"
function* exclusiveResourceAccess(ctx: Context, resource: string, workers: string[]): Generator<any, MutexResult, any> {
  const results: WorkResult[] = [];
  // The generator IS the lock: each yield* blocks until the previous completes,
  // so no two workers touch the resource at once.
  for (let i = 0; i < workers.length; i++) {
    const result = yield* ctx.run(accessResource, resource, workers[i]!);
    results.push(result);
  }
  return { resource, processed: results };
}
```

No lock-manager workflow, no dynamic signal names, no `uuid4()` tokens, no `continueAsNew`, no deadlock surface. Sequential `yield* ctx.run()` calls are serialized by the runtime, with crash recovery built in.

See it in action: [example-distributed-mutex-ts](https://github.com/resonatehq-examples/example-distributed-mutex-ts)

## Encryption

Temporal encrypts payloads with a `PayloadCodec` (`encode`/`decode` over `Payload[]`), a `DataConverter` wrapping it, and a separate codec server so the Web UI can decrypt. Resonate takes a single `Encryptor` as one constructor option; workflow code is untouched.


This pattern currently has a Resonate example in TypeScript only.


```typescript title="Temporal — samples-typescript/encryption/src/encryption-codec.ts (excerpt)"
export class EncryptionCodec implements PayloadCodec {
  async encode(payloads: Payload[]): Promise<Payload[]> {
    return Promise.all(payloads.map(async (payload) => ({
      metadata: {
        [METADATA_ENCODING_KEY]: encode(ENCODING),
        [METADATA_ENCRYPTION_KEY_ID]: encode(this.defaultKeyId),
      },
      data: await encrypt(temporal.api.common.v1.Payload.encode(payload).finish(), this.keys.get(this.defaultKeyId)!),
    })));
  }
  async decode(payloads: Payload[]): Promise<Payload[]> { /* …mirror of encode… */ }
}
```

```typescript title="Resonate — example-encryption-ts/src/encryptor.ts + index.ts"
export class AesGcmEncryptor implements Encryptor {
  encrypt(plaintext: Value): Value {
    if (!plaintext.data) return plaintext;
    const iv = randomBytes(IV_LENGTH);
    const cipher = createCipheriv(ALGORITHM, this.rawKey, iv);
    const packed = Buffer.concat([iv, cipher.update(plaintext.data, "utf8"), cipher.final(), cipher.getAuthTag()]);
    return { headers: { ...plaintext.headers, "x-encrypted": "true" }, data: packed.toString("base64") };
  }
  decrypt(ciphertext: Value): Value { /* …mirror of encrypt… */ }
}

// wired once at startup — workflow code is unchanged:
const resonate = new Resonate({ encryptor: new AesGcmEncryptor(ENCRYPTION_KEY, "demo-key-v1") });
```

Temporal: a `PayloadCodec` over protobuf `Payload[]`, a `DataConverter`, and a codec server (~7 files). Resonate: one `Encryptor` (`encrypt(Value): Value`) passed as a constructor option. The SDK handles promise-store serialization transparently.

See it in action: [example-encryption-ts](https://github.com/resonatehq-examples/example-encryption-ts)


A few coverage gaps to plan around: **saga in Go** has no example yet
(`example-money-transfer-go` / `example-saga-booking-go`); **long-running loops in
Python and Rust** have no example yet (`example-infinite-workflow-py` / `-rs`);
**distributed mutex** and **encryption** are TypeScript-only. The
[examples library](https://github.com/resonatehq-examples) is the source of truth
for what exists today.


## Distributed execution

In Temporal, you can run multiple Workers to handle the load of your application.
You use Task Queue Names to identify which Workers should handle which Workflows and Activities.

In Resonate, you can register workers in groups and send invocations to the groups.
Resonate will automatically load balance the invocations across the Workers in the group.



    

```python
# worker.py
resonate = Resonate(
    url="http://localhost:8001",
    group="workers",
    # ...
)
```

See it in action: [example-load-balancing-py](https://github.com/resonatehq-examples/example-load-balancing-py)

```python
# client.py
resonate = Resonate(
    url="http://localhost:8001",
    group="client",
)

async def main():
    # ...
    handle = resonate.options(target="poll://any@workers").rpc(promise_id, "function_name", params)
    result = await handle.result()
```

    

    

```typescript
// worker.ts
const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "workers",
});
```

See it in action: [example-load-balancing-ts](https://github.com/resonatehq-examples/example-load-balancing-ts)

```typescript
//client.ts
const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "client",
});

async function main() {
  resonate.rpc(
    promiseId,
    "function_name",
    params,
    resonate.options({
      target: "poll://any@workers",
    })
  );
}
```

    

    

```rust
// worker.rs
let resonate = Resonate::new(ResonateConfig {
    url: Some("http://localhost:8001".into()),
    group: Some("workers".into()),
    ..Default::default()
});
```

See it in action: [example-load-balancing-rs](https://github.com/resonatehq-examples/example-load-balancing-rs)

```rust
// client.rs
let resonate = Resonate::new(ResonateConfig {
    url: Some("http://localhost:8001".into()),
    group: Some("client".into()),
    ..Default::default()
});

let result: u64 = resonate
    .rpc(&promise_id, "function_name", params)
    .target("poll://any@workers")
    .await?;
```

    

    

```go
// worker
r, _ := resonate.New(resonate.Config{
	Network: httpnet.NewHTTP("http://localhost:8001", httpnet.HTTPOptions{
		Group: "workers",
	}),
})
```

See it in action: [example-load-balancing-go](https://github.com/resonatehq-examples/example-load-balancing-go)

```go
// client
r, _ := resonate.New(resonate.Config{
	Network: httpnet.NewHTTP("http://localhost:8001", httpnet.HTTPOptions{
		Group: "client",
	}),
})

h, _ := r.RPC(context.Background(), promiseID, "function_name", params,
	resonate.RPCOptions{Target: "poll://any@workers"})
```

    



## Decentralized architecture

In Temporal, any given Workflow Execution is tied to a specific Temporal Service.
This forces a star-like topology (centralized system) where all Workers in an application connect to a single Temporal Service.

Additionally, Temporal requires you to size your Temporal Service ahead of time to handle the load of all Workers in your application.
If you size it incorrectly, you have to migrate to a new setup, which is a complex process.

Resonate applications, on the other hand, can use multiple Resonate Servers to durably store data (Durable Promises), which can be added dynamically as the application scales.



    



    

    



    



## System complexity

The level of system complexity is perhaps the biggest difference between Resonate and Temporal.

Resonate at its core believes in simplicity.

This belief drives many of the design decisions in Resonate, and has resulted in a much smaller API surface than Temporal.

This smaller API surface and desire for simplicity have also resulted in a much smaller set of components.

For example, Temporal SDKs run to tens of thousands of lines of code to manage the complexity of their implementation — roughly 48,000 in TypeScript, 69,000 in Python, and 84,000 in Go.
The Resonate SDKs are between about 6,000 and 14,000 lines depending on the language.
(SDK source only, excluding tests and generated protobuf bindings, measured at the time of writing — clone the repos and check.)

A Temporal Service is a complex system consisting of multiple individual components, each consisting of tens of thousands of lines of code, that need to be configured, deployed, and scaled independently.
A Resonate Server, on the other hand, is a single binary that is easy to deploy. And the Resonate system can scale by just adding more Resonate Servers, each with an underlying database.

Additionally, Temporal exposes many complex APIs to the developer which they are required to use for failure detection, load balancing, and more.
Resonate's belief in simplicity means that much of this complexity is pushed into the platform and automatically handled for you.

For example, Temporal defines four separate Activity timeouts — schedule-to-close, start-to-close, schedule-to-start, and heartbeat.
Only one of them is strictly required (either schedule-to-close or start-to-close), but each covers a different failure mode, so choosing the right combination is a decision you make per Activity.
Long-running Activities that need failure detected before the timeout expires record heartbeats themselves, and Workers expose a set of concurrency and rate-limiting knobs to tune.

Resonate exposes a single timeout to the developer — the resolution deadline of the Durable Promise.
Failure detection, heartbeating, and load balancing across Workers are handled by the platform: the SDK heartbeats the task lease, the server notices a dead Worker, and the task is re-dispatched without any application code.

Ultimately, as a developer, you will find many areas where Resonate has chosen to promote a specific model for the sake of simplicity, and to avoid indulging in what we believe to be unnecessary complexity.

---

---
url: https://docs.resonatehq.io/evaluate/how-it-works
title: How it works
---

OK, so now that you know _why_ Resonate is useful, let's dive into _how_ it works.

## Checkpoints and replays

Have you heard the term "Durable Execution"?
It means that an application workflow/function can resume from where it left off after the hosting process has disappeared (i.e. crashed, restarted, etc.).

The most practical way to achieve this, so that there is a coherent and sequential flow to code that the developer writes, is by checkpointing and replaying.

That is one of the things Resonate does.
Resonate checkpoints at steps in your application code, basically whenever you use a Resonate SDK API.
At each checkpoint Resonate saves some data to a datastore (database).

_**In Resonate, we call the checkpoints Durable Promises.**_

Resonate may execute a function many times using the stored data to reach the next step.
The Durable Promise ID acting as a unique identifier for the checkpoint and idempotency key for the function execution.
When the invoked function completes, the result is stored in the Durable Promise.

![Checkpointing](/images/checkpointing.png)

As the developer, you decide whether to invoke a local function, invoke a remote function, promisify an external system, and when to await the result — all of which is considered "durable" thanks to checkpointing and replaying.

## Message passing

Each instance of a Resonate Worker (application node, microservice, etc.) runs in its own process.
And each instance needs to be able to send and receive messages from a Resonate Server.

![Resonate system architecture](/images/resonate-architecture.png)

The protocol used to pass these messages is called [Async RPC](https://www.async-rpc.io/), and it is completely agnostic to the transport.

For example, Resonate can pass all its messages over HTTP APIs, or over GCP Pub/Sub topics, or some workers might receive on one transport and send on another. Kafka transport is [planned](/deploy/message-transports#planned) for a future release.

The Async RPC protocol is designed to enable reliable and scalable communication between distributed processes, no matter the transport.

Resonate already ships several transport plugins and more are being developed — see [Message transports](/deploy/message-transports) for the current set.

For the formal treatment of these protocols — promise state transitions, task lifecycle, and message-passing semantics — see the [Distributed Async Await specification](https://distributed-async-await.io/spec).

Additionally, thanks to the protocol, Resonate offers built-in service discovery and load balancing.

When a worker or microservice connects to a Resonate Server, it registers itself both uniquely and as part of a group.
This enables a Resonate Server to track which workers or microservices are available for a given function.
It then load balances requests across them.

---

---
url: https://docs.resonatehq.io/evaluate/how-resonate-is-tested
title: How Resonate is tested
---

This page reflects Resonate Server v0.9.8, `@resonatehq/sdk` v0.11.4 (TypeScript), `resonate-sdk` v0.7.4 (Python), `resonate-sdk` v0.6.0 (Rust), `resonate-sdk` v0.1.1 (Java), and the Resonate Go SDK 0.1.0.


Resonate's correctness story rests on three layers, each covering a different surface: an executable formal specification of the protocol in Lean 4, differential random testing of the server against an independent in-memory oracle, and deterministic simulation testing of the TypeScript SDK. Unit, integration, and end-to-end suites across all five SDKs sit alongside these. Deterministic simulation currently covers the TypeScript SDK; the other SDKs are tested conventionally, against a live server.

## Determinism is a protocol feature

Resonate's determinism hooks live in the protocol itself, not in a simulator wrapped around the code under test.

When the server runs with `debug = true` in its config, every request envelope may carry a `resonate:debug_time` field, and the handler uses that value as "now" instead of the wall clock ([`src/util.rs`](https://github.com/resonatehq/resonate/blob/main/src/util.rs), [`src/server.rs`](https://github.com/resonatehq/resonate/blob/main/src/server.rs)). Handlers take time as a parameter rather than reading an ambient clock, so a test controls every time value the handler path observes — timers, timeouts, and schedules fire exactly when the test drives them to. With `debug = false` (the default), the field is stripped and the server runs on wall-clock time.

Deterministic tests therefore run against the real server binary, over its real HTTP interface, with no separate simulator build to keep in sync with production code. And because the hook is part of the protocol rather than any one codebase, a harness built on it can drive any server that implements the protocol — the conformance testbed below leans on exactly this.

## The Lean 4 abstract machine

The Distributed Async Await protocol — the protocol every Resonate server and SDK speaks — is specified twice, on purpose. [`resonatehq/resonate-specification`](https://github.com/resonatehq/resonate-specification) is the executable abstract machine in Lean 4 — the normative, machine-checkable definition of the protocol's handlers and state transitions: promises, tasks, and schedules. The [prose specification](https://distributed-async-await.io/spec) is the human-readable companion that explains the same protocol. Where prose and Lean disagree, the Lean model wins.

The model encodes each protocol handler as a pure, deterministic function:

```lean
-- every handler has this shape: "now" is the only input that carries time
def promiseCreate (req : PromiseCreateReq) (now : Nat) : H PromiseCreateRes := do
  ...
```

Handlers read state and emit named effects — `setPromise`, `setTask`, `setSchedule`, outbox writes — and nothing else, which keeps the model directly auditable ([`spec/02-abstract`](https://github.com/resonatehq/resonate-specification/tree/main/spec/02-abstract)). It builds with a single command:

```shell title="Build the Lean model"
lake build spec    # the specification — the fast loop
lake build valid   # the trace checker
lake build         # everything, including the decide sweeps (minutes)
```

The model specifies 18 of the 21 handlers a client can reach in full: five promise handlers (`promiseCreate`, `promiseGet`, `promiseSettle`, `promiseRegisterCallback`, `promiseRegisterListener`), ten task handlers (`taskGet`, `taskCreate`, `taskAcquire`, `taskFence`, `taskHeartbeat`, `taskSuspend`, `taskFulfill`, `taskRelease`, `taskHalt`, `taskContinue`), and three schedule handlers (`scheduleGet`, `scheduleCreate`, `scheduleDelete`). The three search handlers are stubbed at `501` while their specs are being written. Alongside these sit six internal steps — the transitions background jobs fire: promise timeout, listener drain, callback drain, lease timeout, retry dispatch, and schedule firing ([`spec/02-abstract/internal.lean`](https://github.com/resonatehq/resonate-specification/blob/main/spec/02-abstract/internal.lean)).

### The property catalogue

The model carries a catalogue of 95 decidable properties — invariants over server state, stated as executable predicates in [`spec/02-abstract/properties.lean`](https://github.com/resonatehq/resonate-specification/blob/main/spec/02-abstract/properties.lean). They're checked two ways.

First, by exhaustive sweep: [`spec/04-theorems/properties-check.lean`](https://github.com/resonatehq/resonate-specification/blob/main/spec/04-theorems/properties-check.lean) evaluates the full catalogue over every script of length up to three drawn from an eleven-step adversarial alphabet — 1,464 scripts in total — and the sweep is a theorem proved by `decide`, meaning Lean's kernel runs the entire check during `lake build`. A green build *is* the certificate; there's no separate test run to forget. What the sweep certifies is bounded — every behavior reachable in three steps; beyond that it says nothing — which is why the catalogue is checked a second way.

Second, by proof: 32 of the 95 properties are proved as theorems that hold along *all* reachable traces, at any depth ([`spec/04-theorems/holds.lean`](https://github.com/resonatehq/resonate-specification/blob/main/spec/04-theorems/holds.lean)). The remaining 63 are backed by the sweep alone so far, and the file says so.

The protocol's central liveness property — settle a promise, and its awaiters come back — is stated in [`spec/04-theorems/liveness.lean`](https://github.com/resonatehq/resonate-specification/blob/main/spec/04-theorems/liveness.lean):

```lean title="The central liveness property"
def EventuallyAwaiterResumed : Prop :=
  ∀ tr : Trace, Valid true tr → ClockAdvances tr →
    WeaklyFairOn tr isSettlementStep → WeaklyFairOn tr isCallbackStep →
    ∀ (t : Nat) (a x : String),
      (∃ p, promiseAt (tr t).state a = some p ∧
              p.state ≠ .pending ∧ p.callbacks.contains x = true) →
      ∃ u : Nat, t ≤ u ∧
        (∀ p, promiseAt (tr u).state a = some p → p.callbacks.contains x = false) ∧
        (∀ w, taskAt (tr u).state x = some w →
           w.state = .fulfilled ∨ (w.state ≠ .suspended ∧ w.resumes.contains a = true))
```

In words: on any valid trace where the clock keeps advancing and the settlement and callback steps are treated fairly, once a promise settles, every task awaiting it is eventually resumed — or the task's own timeout won the race first, in which case the timeout path owns the cleanup. The statement quantifies over infinite traces, so it can't be proved by enumeration; what the repo proves instead are its bounded shadows — `boundedWakeSweep` checks the wake obligation over the full 1,464-script corpus, and a companion theorem, `wake_requires_fairness`, shows the fairness assumptions aren't decorative: drop them and the obligation genuinely fails.

### Holding real servers to the model

The spec repo also ships a trace checker, [`valid/`](https://github.com/resonatehq/resonate-specification/tree/main/valid): capture real traffic from a running server as newline-delimited JSON, one event per external call, and ask whether the abstract machine can account for it. Two implementations answer that question — `valid/lean`, which searches for an accepting run of the Lean machine, and `valid/porc`, a Go port of the same machine wired into the [Porcupine](https://github.com/anishathalye/porcupine) linearizability checker. They're ports of one model, so agreement between them catches drift and translation errors; a regression test pins the exact event at which both checkers refute a known-bad capture. Conformance here is an instrument, not a per-build gate: a server is held to the model when its traffic is captured and run through the checker.

## Resonate Server

The Resonate Server ([`resonatehq/resonate`](https://github.com/resonatehq/resonate), written in Rust) is tested in several layers on every pull request.

### Differential random testing

[`diff/differential.rs`](https://github.com/resonatehq/resonate/blob/main/diff/differential.rs) defines a test named `differential_random`. It drives one randomly-generated sequence of API operations through multiple backends at once — always an in-memory SQLite instance and the Oracle reference model; Postgres and MySQL too, when environment variables supply connection URLs. Every operation must produce the same HTTP status and response body from every backend. State is cross-checked as well: narrower checks around each operation, and a comparison of the full snapshot — promises, tasks, callbacks, listeners, messages, timeouts — at every 200-step batch boundary. The test is sequential, one operation at a time; concurrent histories are the linearizability checker's job below.

The Oracle ([`src/oracle.rs`](https://github.com/resonatehq/resonate/blob/main/src/oracle.rs)) is a second, independent, in-memory implementation of the protocol state machine, written separately from the storage backends rather than derived from them. When implementations that share only the protocol agree on every response and every snapshot, agreement is evidence; a disagreement is an immediate test failure with a field-level diff of the divergence.

Generation is steered: uncovered operations are forced first, and the run ends only after all twenty-two operation kinds are covered *and* twenty consecutive 200-step batches produce no new (operation, status, state-shape) combination — a stopping heuristic over the protocol surface, not a code-coverage measure — capped at 200,000 steps. In CI the test runs on every pull request as part of `cargo test --all-features`, against SQLite and the Oracle; the Postgres and MySQL backends are exercised locally:

```shell title="Run the differential test locally"
# SQLite + Oracle only (no external database required):
cargo test --test differential -- --nocapture

# All backends:
TEST_POSTGRES_URL=postgres://<USER>:<PASSWORD>@localhost:5432/resonate \
TEST_MYSQL_URL=mysql://<USER>:<PASSWORD>@localhost:3306/resonate \
  cargo test --test differential -- --nocapture
```

### Unit tests

The server's unit tests run with `cargo test --all-features` and cover configuration parsing, transport message handling, and individual processing modules. CI gates every pull request on format (`cargo fmt`), compilation (`cargo check`), and linting (`cargo clippy --all-features -- -D warnings`) before tests run.

### Conformance and linearizability

A separate CI job (visible in [`ci.yml`](https://github.com/resonatehq/resonate/blob/main/.github/workflows/ci.yml)) runs the conformance testbed against the server on every pull request, as a matrix over all three storage backends — SQLite, Postgres, and MySQL. The testbed drives the server over HTTP: state-machine transition tests, randomized fuzz runs against a reference model, and linearizability checking of concurrent operation histories with [Porcupine](https://github.com/anishathalye/porcupine). The testbed itself is not yet public — the CI steps that fetch and run it are.

## TypeScript SDK

The TypeScript SDK ([`resonatehq/resonate-sdk-ts`](https://github.com/resonatehq/resonate-sdk-ts)) carries a conventional Jest test suite and a dedicated deterministic simulation test.

### Deterministic simulation testing

The DST harness lives in [`sim/`](https://github.com/resonatehq/resonate-sdk-ts/tree/main/sim) and runs on a schedule via [`.github/workflows/dst.yml`](https://github.com/resonatehq/resonate-sdk-ts/blob/main/.github/workflows/dst.yml) — every twenty minutes, across Ubuntu, Windows, and macOS, against Node 18, 20, and 22.

The harness uses a seeded linear-congruential PRNG. From a single integer seed, it derives the full behavior of the run: which function to invoke at each step, whether a message is dropped, duplicated, or delayed, and whether a worker process drops out and comes back. A default run executes 10,000 steps across three simulated worker processes and one simulated server process, exercising recursive fan-out patterns and multi-step chained functions. The simulation wraps the SDK's real core logic in a simulated network: the code under test is the code you'd ship. The transport standing in for the network is not — transport-level bugs are the end-to-end suites' job.

Determinism is verified explicitly: CI runs each seed twice and diffs the two logs. Same seed, different output is a failing run — a check that exists to catch nondeterminism itself, the one bug class that would quietly destroy the reproducibility everything else depends on. When a run fails, a GitHub issue is filed automatically with the seed, the commit SHA, and the exact command to reproduce it — [issue #414](https://github.com/resonatehq/resonate-sdk-ts/issues/414) is one such report:

```shell title="Reproduce a DST failure"
npm run dst -- --seed <seed> --steps 10000
```

### Jest unit and integration suite

The Jest suite covers the core execution engine, coroutine scheduling, retry policies, network transport, codec, encryption, and function registry. It runs via `npm test` in CI alongside linting and type checks.

## Python SDK

The Python SDK ([`resonatehq/resonate-sdk-py`](https://github.com/resonatehq/resonate-sdk-py)) runs `pytest` with branch coverage on Python 3.12, 3.13, and 3.14 across Ubuntu, macOS, and Windows.

The suite includes [`tests/test_invariants.py`](https://github.com/resonatehq/resonate-sdk-py/blob/main/tests/test_invariants.py), which formalizes the structural replay contract of the SDK's execution tree model. The invariants capture properties from the internal `tree.md` specification — among them that a node's settler type is fixed across replays, that settled promise records never retreat to pending, that the execution tree reaches a fixed point after the first replay under an unchanged cache, and that the frontier shrinks monotonically as steps settle. Each invariant is driven across a battery of workflow shapes, and the test asserts the property at every step of the settle-to-done trajectory rather than only at the final state.

CI also runs the Python SDK's examples end-to-end against a live Resonate server binary, downloaded from the public release page.

## Rust SDK

The Rust SDK ([`resonatehq/resonate-sdk-rs`](https://github.com/resonatehq/resonate-sdk-rs)) runs `cargo test --workspace` for its unit suite and `cargo test -p resonate-sdk --test e2e` for end-to-end tests against a live server. The e2e suite runs in CI against a server container on every pull request and covers durable function execution, fan-out/fan-in, promise resolution, retry behavior, and heartbeating.

## Go SDK

The Go SDK ([`resonatehq/resonate-sdk-go`](https://github.com/resonatehq/resonate-sdk-go)) runs `go test -race -timeout 5m ./...` — the Go race detector is enabled on every test run. End-to-end tests in [`e2e_test.go`](https://github.com/resonatehq/resonate-sdk-go/blob/main/e2e_test.go) target a live Resonate server and cover the full execution lifecycle: durable sleep, fan-out, promise resolution, and load balancing across worker groups. Without `RESONATE_URL` set, the e2e tests skip cleanly so `go test ./...` works without a server.

## Java SDK

The Java SDK ([`resonatehq/resonate-sdk-java`](https://github.com/resonatehq/resonate-sdk-java)) compiles against Java 21 and runs its test suite against Java 21, 24, and 25 via `./gradlew test`. The suite includes [`InvariantsTest.java`](https://github.com/resonatehq/resonate-sdk-java/blob/main/src/test/java/io/resonatehq/resonate/InvariantsTest.java), a port of the Python SDK's replay-invariant suite — the same structural contract, checked in a second language. CI also runs the SDK's examples end-to-end against a live server.

## Where to go next

To see the system these tests protect, the [quickstart](/get-started/quickstart) gets a durable function running in a few minutes. Questions about the testing approach are welcome in [Discord](https://resonatehq.io/discord).

---

---
url: https://docs.resonatehq.io/evaluate
title: Evaluate Resonate
---

<img src="/images/banner-evaluate-dark.png" alt="Evaluate Resonate section" className="hidden dark:block" />
<img src="/images/banner-evaluate-light.png" alt="Evaluate Resonate section" className="block dark:hidden" />

**Considering Resonate?**

Evaluate Resonate to understand its capabilities and how it works.

---

---
url: https://docs.resonatehq.io/evaluate/why-resonate
title: Why Resonate
---

**Resonate is the [durable execution](https://www.resonatehq.io/durable-execution) engine that agents build with, deploy on, and operate &mdash; at a fraction of the cost of anything else.**

It is the implementation of a [distributed async/await](https://distributed-async-await.io/spec) programming model: a formal, language- and transport-agnostic protocol for writing functions that survive process restarts, run for hours or months, and coordinate across many machines.

This page explains the three pillars that make Resonate different, the business model that ships those pillars, and what this means for agents and the humans who work with them.

## The three pillars

### 1. Agent-native

Agents are the new developers. Increasingly, software is selected, written, configured, and deployed by AI agents — not by humans choosing platforms and libraries by hand. The platform that agents reach for is the platform that wins.

Resonate is built for that world from the ground up:

- **The SDK is designed for agent consumption.** Predictable APIs, deterministic execution, clear failure modes. An agent reading the SDK reference can build correct distributed workflows on the first try.
- **The docs are written for both humans and agents.** Skill files (machine-readable agent guidance) sit alongside human tutorials. The CLI reference is canonical and exhaustive.
- **The operational surface is CLI-first.** Agents do not click. They script. The Resonate CLI lets agents invoke functions, inspect promises, visualize execution graphs, and manage the server — all without leaving the terminal.

When we say "agent-native," we mean: an autonomous coding agent should be able to build, deploy, and operate a Resonate application end to end without ever loading a web page.

### 2. Generated &amp; optimized

Most durable execution platforms ship a single general-purpose server: hand-written code that has to handle every possible stack, every possible transport, every possible storage backend. Generality has a tax — every workflow pays for abstractions it doesn't use, in state transitions, network requests, and operational chatter.

Resonate takes a different path. The ecosystem is built on **open-source, pluggable components** — transports, storage backends, wire formats — that you can assemble to match your stack. On top of that, we generate **stack-specific components** for customers who need a server tailored to their exact infrastructure. HTTP push, HTTP poll, or GCP Pub/Sub for transport today — Kafka and SQS [are planned](/deploy/message-transports#planned) — Postgres or DynamoDB for state, gRPC or REST for the wire — we generate a complete Resonate server that includes only what your stack requires. Minimal state transitions, minimal network chatter, nothing wasted.

This is not AI-generated slop. The underlying [Async RPC protocol](https://www.async-rpc.io) is a fully formal JSON Schema specification — a machine-verifiable contract that constrains what "correct" means. AI is used throughout our development and testing processes, guided by these specs and protocols, to produce highly optimized software. The protocol is the contract; the implementation is generated against it, verified by [Deterministic Simulation Testing](#quality-is-not-optional), and delivered as production-grade source code.

### 3. Cost-efficient by design

Generated components plus serverless-native deployment produces a cost story that is not incremental — it is categorical.

Fewer state transitions means fewer database writes, fewer network round trips, fewer compute-seconds. Serverless-native architecture means you pay only for execution that is actually happening. Together, these effects compound.

**In extreme cases,** workloads that cost less than $100/year to run on Resonate could cost $50,000–$80,000/year on popular hosted durable execution platforms. That is not a rounding error — it is the consequence of removing unnecessary work from the critical path.

Cost is the ultimate forcing function. When an agent evaluates options, Resonate wins on cost by 100&ndash;800x.

## Quality is not optional

Two things should give you confidence in Resonate&apos;s correctness:

**Formal modeling.** The [Distributed Async Await specification](https://distributed-async-await.io/spec) and the [Async RPC protocol](https://www.async-rpc.io) underlying Resonate are formally modeled and continuously probed for correctness. The protocol is a contract, not a vibe.

**Deterministic Simulation Testing.** Every major component &mdash; the Resonate Server and each SDK &mdash; is subjected to DST. This finds complex edge cases long before they reach production, on top of conventional unit and integration tests.

The new server is also linearizable. Combined with DST, this is the foundation of the correctness story. The full approach &mdash; with links to the test code, the CI workflows, and the Lean 4 model &mdash; is on [How Resonate is tested](/evaluate/how-resonate-is-tested).

## Open everything

The [Async RPC protocol](https://www.async-rpc.io), the [Distributed Async Await specification](https://distributed-async-await.io/spec), and the open-source Resonate server are all fully open. The promise, schedule, and task state transitions are formalised as an [executable Lean 4 abstract machine](https://github.com/resonatehq/resonate-specification) — the machine-checkable ground truth alongside the prose spec. Adopting Resonate means adopting a protocol, not a vendor. Everything you need to fork or build your own is available to you.

---

---
url: https://docs.resonatehq.io/get-started/claude-code
title: Durable bash
---

Resonate ships an MCP tool, `resonate-bash`, that turns any shell script into a durable, asynchronous task. You point Claude Code at a local Resonate server, and Claude gains the ability to hand off a script and be notified when it terminates — without holding the wait in its context window.

This page walks through what `resonate-bash` is good at and how to set it up.

## What `resonate-bash` is good at

The polling loop runs in the shell, not in the model. The model is not invoked during the wait. That's the property that makes the rest worthwhile.

### Long-running polling loops

Waiting for an external system to reach a state — a CI run finishes, a deploy goes live, DNS propagates, an image-generation job returns, a Tensorlake sandbox completes, a BigQuery export job lands.

```bash title="Wait for a GitHub Actions run to finish"
until gh run view 12345 --json status -q .status | grep -q completed; do
  sleep 60
done
```

Submitted to `resonate-bash` with a 1-hour timeout, that loop runs in the shell on the resonate host. Claude is notified the moment the run completes.

### Operations that need to outlive the session

Promises live on the Resonate server, not in the calling Claude Code session. If the laptop closes, the host hiccups, or you start a new conversation tomorrow, the work continues. A later session can look up the promise ID and read the result with the same MCP server.

### Named, queryable state

Promise IDs are first-class. Prefix them by project and date (`ci-watch-2026-05-21`, `dns-propagation-2026-05-21`) and filter `promise-search` later by the `tags` parameter to audit what fired across days.

### Fire-and-watch coordination with external systems

Most CI tools, deploy platforms, image-generation APIs, and data-export jobs expose a status endpoint but no webhook. `resonate-bash` is the right shape for that: submit the work, poll in the shell, get notified on completion. Tensorlake, Vectorizer.ai, Recraft, Midjourney, and any "submit job, poll status" service fit this mold cleanly.

### Composable with the rest of the promise API

The same promise IDs work with `promise-create`, `promise-listen`, and `promise-settle`. A one-off durable script can be promoted into a multi-step workflow later without re-architecture.


Always write idempotent scripts. For "trigger external action then poll" patterns, structure as `check-then-trigger + poll` so a restart does not double-fire.


---

## Prerequisites

- macOS (Apple Silicon or Intel) with Homebrew, or a Linux host with the `resonate` binary on `$PATH`.
- Claude Code installed.
- (Optional, for the Tensorlake target) a Tensorlake API key from [tensorlake.ai](https://tensorlake.ai).


The examples below assume `/opt/homebrew/bin/resonate` (Apple Silicon Homebrew). On Intel Mac use `/usr/local/bin/resonate`; on Linux use whichever path your installer chose.


---

## 1. Install the Resonate binary

```shell
brew install resonatehq/tap/resonate
resonate --version   # expect 0.9.7 or newer
```

A single binary serves as both the server (`resonate dev` / `resonate serve`) and the MCP shim Claude talks to (`resonate mcp`).

---

## 2. Run the Resonate server with the bash transport enabled

Start with the foreground option to confirm everything works, then switch to the launchd option for a persistent install.


This guide uses `8888` to avoid colliding with `resonate dev`'s default port `8001` (which you may already be running for other work). Pick whatever you want — just keep the port consistent across the server, the plist, and the MCP `--server` URL in step 3.






In-memory storage; stops on Ctrl-C. Good for confirming the wiring.

```shell
# Only needed if you'll target bash://tensorlake/...
export TENSORLAKE_API_KEY="tl_apiKey_REPLACE_ME"

resonate dev \
  --server-port 8888 \
  --transports-bash-exec-enabled true
```


`--transports-bash-exec-enabled` requires `true` or `false`. A bare flag will error with `a value is required for '--transports-bash-exec-enabled <BOOL>'`.


Verify in another shell:

```shell
curl -s http://localhost:8888/health   # → 200 OK
```





Persistent install that auto-starts at login.

Write `~/Library/LaunchAgents/io.resonatehq.resonate.dev.plist`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>io.resonatehq.resonate.dev</string>

    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/resonate</string>
        <string>dev</string>
        <string>--server-port</string>
        <string>8888</string>
        <string>--transports-bash-exec-enabled</string>
        <string>true</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/tmp/resonate-dev.log</string>

    <key>StandardErrorPath</key>
    <string>/tmp/resonate-dev.log</string>
</dict>
</plist>
```

If you target `bash://tensorlake/...`, add an `EnvironmentVariables` block to the `<dict>` above so the API key is visible to the resonate process (not just your shell):

```xml
    <key>EnvironmentVariables</key>
    <dict>
        <key>TENSORLAKE_API_KEY</key>
        <string>tl_apiKey_REPLACE_ME</string>
    </dict>
```

Load it:

```shell
launchctl load ~/Library/LaunchAgents/io.resonatehq.resonate.dev.plist
launchctl list | grep resonate          # expect PID, exit code 0
curl -s http://localhost:8888/health    # → 200 OK
```

**Restart cheat-sheet:**

| When | Command |
|---|---|
| Changed the binary or want a clean restart | `launchctl kickstart -k gui/$(id -u)/io.resonatehq.resonate.dev` |
| Changed `EnvironmentVariables` or `ProgramArguments` in the plist | `launchctl unload <plist> && launchctl load <plist>` (kickstart will **not** pick up new env vars) |

Logs: `tail -f /tmp/resonate-dev.log`.


The plist stores any API keys in plaintext under your home directory. For a hardened setup, fetch keys from Keychain in a wrapper script and exec `resonate` from there.






---

## 3. Wire Claude Code to the Resonate MCP server

Edit `~/.claude.json` and add a `resonate` entry under `mcpServers`. Merge with any existing MCP entries — don't overwrite the file.

```json
{
  "mcpServers": {
    "resonate": {
      "type": "stdio",
      "command": "/opt/homebrew/bin/resonate",
      "args": ["mcp", "--server", "http://localhost:8888"],
      "env": {}
    }
  }
}
```

---

## 4. Enable the Claude Code preview channel

The `mcp__resonate__resonate-bash` tool ships behind a Claude Code preview channel. Update your `claude` alias in `~/.zshrc` (or `~/.bashrc`):

```shell
alias claude='claude --dangerously-load-development-channels server:resonate'
```

Reload the shell:

```shell
source ~/.zshrc
```

---

## 5. Verify

Open a fresh `claude` session and run:

```text
/mcp
```

`resonate` should be listed and connected. If it isn't, see [Troubleshooting](#troubleshooting).

Then exercise the tool with a real durable promise:

> Please watch my desktop for a file `Resonate.md` to appear, with resonate.

Claude should call `mcp__resonate__resonate-bash` with a poll-until-exists script. `touch ~/Desktop/Resonate.md` in another shell — Claude will be notified the moment the promise resolves.

Useful follow-up prompts:

> How did you do that? Show me the promise. And show me the script.

> What else can you use resonate for? Give me three examples.

> Run `echo hello from $RESONATE_PROMISE_ID` on tensorlake.

---

## Tool reference

### Parameters

| Parameter | Required | Default | Description |
|---|---|---|---|
| `script` | yes | — | Inline bash script. Will be base64-encoded into `param.data` for you. |
| `target` | no | `bash://` | Where the script runs. See [target addresses](#target-addresses). |
| `timeoutMs` | no | 5 min | Promise deadline relative to now (milliseconds). |
| `id` | no | `bash-<millis>-<nanos>` | Deterministic promise id for idempotency. |
| `tags` | no | — | JSON object merged into promise tags (`resonate:target` is set automatically). |

The tool registers a listener and resolves via channel notification when the script terminates, returning `{exit_code, stdout, stderr}`.

### Target addresses

| Address | Where it runs | Notes |
|---|---|---|
| `bash://` | Local shell on the resonate host | Default if `target` is omitted |
| `bash://docker/<image>` | `docker run --rm <image> bash -c <script>` | Image required; the resonate host must have Docker |
| `bash://tensorlake/<image>` | Tensorlake Sandboxes API | `<image>` optional — empty path uses Tensorlake's default sandbox. Requires `TENSORLAKE_API_KEY` on the resonate process |

### Env vars injected into every script

| Variable | Meaning |
|---|---|
| `RESONATE_PROMISE_ID` | The promise/task id |
| `RESONATE_PROMISE_CREATED_AT` | ms since epoch — **stable across retries** |
| `RESONATE_PROMISE_TIMEOUT_AT` | ms since epoch — **stable across retries** |

Loop **until `$RESONATE_PROMISE_TIMEOUT_AT`**, not for a fixed duration. That keeps a restart-from-top retry idempotent.

### Failure semantics

- **Script exits non-zero** → workflow failure; the promise rejects with the exit info.
- **Script killed** (local signal, Docker exit 137 / 143, Tensorlake `signaled`) → treated as **infrastructure failure**: the lease expires and the message is redispatched to a fresh worker. Don't rely on signals to short-circuit a workflow.
- **Crash/restart** → the script restarts from the top. Idempotent scripts only.

---

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| `/mcp` doesn't show `resonate` | MCP entry missing from `~/.claude.json`, or resonate server isn't running | `curl http://localhost:8888/health`; check the JSON entry |
| `mcp__resonate__resonate-bash` tool absent in Claude | Missing `--dangerously-load-development-channels server:resonate` flag | Re-check the alias; restart `claude` |
| Promise resolves with `TENSORLAKE_API_KEY env var not set` | Env var not in resonate process env | For launchd: `unload` then `load` (kickstart won't pick up new env). Verify with `ps eww $(launchctl list \| awk '/resonate/{print $1}') \| tr ' ' '\n' \| grep TENSORLAKE` |
| Promises stuck `pending` forever | Bash exec transport not enabled | Confirm `--transports-bash-exec-enabled` is in the resonate launch args |
| Tensorlake sandbox creation hangs | Sandbox readiness timeout (120s) exceeded; bad image name | Check `/tmp/resonate-dev.log` for `tensorlake create` errors |

### Tensorlake-specific gotchas

- Sandbox lifetime is hardcoded server-side to 600s. Promises with longer timeouts will see a fresh sandbox per retry.
- `TENSORLAKE_API_KEY` is read directly from the resonate process env via `std::env::var` — not from `RESONATE_*` config. It must be visible to the **resonate process**, not just your interactive shell.

---

---
url: https://docs.resonatehq.io/get-started/cli-guide
title: Resonate CLI
---

The Resonate CLI is your primary tool for running the server, managing Durable Promises, and interacting with the Resonate system.

## Getting help

The CLI has excellent built-in help. Use `--help` on any command to see detailed usage:

```shell title="Get help on any command"
resonate --help
resonate <command> --help
resonate <command> <subcommand> --help
```

**Examples:**

```shell title="See all available commands"
resonate --help
```

```shell title="Learn about the promises command"
resonate promises --help
```

```shell title="See how to resolve a promise"
resonate promises resolve --help
```


The CLI help is always up-to-date with your installed version. The built-in examples show exactly what syntax to use.


## Common workflows

### Start a development server

```shell title="Start server with in-memory storage"
resonate dev
```

The server starts on:
- HTTP API: `http://localhost:8001`
- Metrics: `http://localhost:9090`

See `resonate dev --help` for options.

### Start a production server

```shell title="Start with PostgreSQL"
resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
```

See `resonate serve --help` for all flags, or [Run a server](/deploy/run-server) for the full configuration story (`resonate.toml` + env vars + flags).

### Invoke a function

```shell title="Trigger a function manually"
resonate invoke order-123 --func processOrder --arg '{"orderId": "123"}'
```

Useful for:
- Testing functions outside your application
- Triggering workflows manually
- Debugging function behavior

### Manage Durable Promises

**Create a promise:**

```shell title="Create a promise for human-in-the-loop"
resonate promises create approval-456 --timeout 24h
```

**Resolve a promise:**

```shell title="Unblock a waiting workflow"
resonate promises resolve approval-456 --data '{"approved": true}'
```

**Check promise state:**

```shell title="Inspect a promise"
resonate promises get order-123
```

**Search for promises:**

```shell title="Find pending promises"
resonate promises search --state pending --limit 10
```

### Work with schedules

**Create a recurring schedule:**

```shell title="Run a function every hour"
resonate schedules create hourly-sync \
  --cron "0 * * * *" \
  --promise-id "sync-{{.timestamp}}" \
  --promise-timeout 1h \
  --promise-tags '{"resonate:target": "poll://any@default"}'
```

The `resonate:target` tag routes each fired promise to a worker group — the server rejects a schedule without it. Cron expressions are evaluated in UTC; see the [Schedules & cron reference](/reference/schedules) for the format and day-of-week convention.

**List schedules:**

```shell title="See all schedules"
resonate schedules search --limit 10
```

**Delete a schedule:**

```shell title="Remove a schedule"
resonate schedules delete hourly-sync
```

## Authentication

If your server requires JWT auth, pass a bearer token with every CLI call:

```shell title="Use bearer token"
resonate promises get order-123 --token YOUR_TOKEN
```

The `--token` flag is a global option — it works on every subcommand.

See [Security](/deploy/security) for how to enable JWT auth on the server.

## Configuration

The Resonate server is configured by layering, in this order: defaults → `resonate.toml` (optional) → `RESONATE_*` env vars → CLI flags. Any of the four can override the previous.

```shell title="Example: serve with auth and PostgreSQL via flags"
resonate serve \
  --auth-publickey /etc/resonate/auth/public.pem \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
```

The same configuration as a [`resonate.toml`](/deploy/run-server#resonatetoml):

```toml title="resonate.toml"
[auth]
publickey = "/etc/resonate/auth/public.pem"

[storage]
type = "postgres"

[storage.postgres]
url = "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"
```

Run `resonate serve --help` for all available flags.

## Tips and tricks

### Filter searches with flags

`promises search` filters by `--state` and `--tags` (there is no ID-pattern argument):

```shell title="Search promises by state and tags"
resonate promises search --state resolved --limit 20
resonate promises search --tags '{"resonate:target": "poll://any@default"}' --limit 20
```

### Pipe JSON output to jq

Every command already prints JSON to stdout, so scripting is a pipe away:

```shell title="Get machine-readable output"
resonate promises get order-123 | jq -r '.promise.state'
```

Useful for scripting and automation.

### Check server health

```shell title="Verify server is running"
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8001/health
# 200 when healthy
```

### View metrics

```shell title="Prometheus metrics"
curl http://localhost:9090/metrics
```

### Connect to remote server

```shell title="Point CLI to a remote server"
resonate promises get order-123 --server https://resonate.yourcompany.com
```

## Troubleshooting

### Command not found

**Error:** `resonate: command not found`

**Solution:** Install the Resonate CLI using [Homebrew](/deploy/run-server#install-with-homebrew) or download from [GitHub releases](https://github.com/resonatehq/resonate/releases).

### Connection refused

**Error:** `connect: connection refused`

**Solution:** 
1. Is the server running? Start it with `resonate dev`
2. Using the correct URL? Default is `http://localhost:8001`
3. Check the `--server` flag points to the right address

### Authentication failed

**Error:** `401 Unauthorized`

**Solution:**
1. Does your server require auth? Check the server configuration
2. Providing correct credentials? Use `--token` or `--username`/`--password`
3. Using the right auth method? (token vs basic)

### Promise not found

**Error:** `404 Not Found`

**Solution:**
1. Check the promise ID is correct (IDs are case-sensitive)
2. Was the promise created? Use `resonate promises search` to verify
3. Did the promise expire? Check timeout settings

## Next steps

- Start a development server (`resonate dev`) and connect your SDK
- Explore [example applications](/get-started/examples) that show real-world CLI usage
- Read about [production deployment](/deploy/run-server) with persistent storage
- Review the [TypeScript SDK guide](/develop/typescript) or [Python SDK guide](/develop/python)

---

---
url: https://docs.resonatehq.io/get-started/examples/async-agent-tools
title: Async agent tools
---

<img src="/images/example-async-agent-tools-dark.png" alt="Async Agent Tools banner" className="hidden dark:block" />
<img src="/images/example-async-agent-tools-light.png" alt="Async Agent Tools banner" className="block dark:hidden" />

A FastMCP server exposes three tools — start, probe, await — backed by a durable Resonate workflow. The LLM kicks off long jobs, polls them, and collects results without blocking on the work.


Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development. TypeScript SDK example repo is forthcoming.



  
  


## The problem

MCP standardizes tool calling but not what happens when a tool takes minutes, hits a flaky upstream, or runs while the agent's MCP host crashes. Every tool implementation reinvents timeouts, retries, idempotency, and crash recovery — and most get at least one wrong.

## Resonate's solution

Split a tool into three smaller MCP tools — `start_gathering`, `probe_status`, `await_result` — and back them with a durable Resonate function. `start_gathering` returns a promise ID immediately, `probe_status` reports without blocking, `await_result` blocks the agent only when it actually wants the answer. Crashes don't lose progress and the same job ID deduplicates retries.

## Code walkthrough

The server exposes one durable function (`weather_data`) and three thin MCP tools that wrap Resonate's promise APIs.

### The durable function

The MCP tool dispatches a Resonate workflow that does the actual side-effecting work. Whatever the tool does — call an external API, stream rows from a DB, transform a payload — happens here, with retries and crash recovery wrapped around it.





```python title="weather_data.py — the durable function"
from __future__ import annotations

import asyncio
import calendar
import os
from typing import TYPE_CHECKING

import requests
from fastmcp import FastMCP
from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

mcp = FastMCP("timer")
url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url)


async def weather_data(ctx: Context, latitude, longitude, year, month, timezone="America/Edmonton"):
    start_date = f"{year}-{int(month):02d}-01"
    end_day = calendar.monthrange(int(year), int(month))[1]
    end_date = f"{year}-{int(month):02d}-{end_day}"

    response = requests.get(
        "https://archive-api.open-meteo.com/v1/archive",
        params={
            "latitude": latitude, "longitude": longitude,
            "start_date": start_date, "end_date": end_date,
            "daily": "temperature_2m_max,temperature_2m_min,precipitation_sum",
            "timezone": timezone,
        },
    )
    response.raise_for_status()
    return response.json()


resonate.register(weather_data)
```





```rust title="src/bin/worker.rs"
use resonate::prelude::*;

#[resonate::function]
async fn get_forecast(ctx: &Context, lat: f64, lon: f64) -> Result<String> {
    // ctx.run checkpoints the HTTP call — a retry of the MCP tool with the
    // same lat/lon reconnects to this workflow rather than re-fetching.
    let json = ctx.run(fetch_nws, (lat, lon)).await?;
    Ok(json)
}

#[resonate::function]
async fn fetch_nws(lat: f64, lon: f64) -> Result<String> {
    let url = format!("https://api.weather.gov/points/{lat},{lon}");
    // ...HTTP call returning the response body.
}
```





### The three async MCP tools

Each tool is a thin shell around a Resonate API call: kick off, poll, await (Python). The Rust port collapses the same pattern into a single tool that dispatches via `resonate.rpc(...)` and awaits a deterministic-ID promise — same dedup, fewer tools.





```python title="weather_data.py — the MCP tools"
@mcp.tool()
def start_gathering(latitude, longitude, year, month):
    """Start a weather data gathering job."""
    job_name = f"weather_data_{latitude}_{longitude}_{year}_{month}"
    # Fire-and-forget: dispatch the workflow, return the ID immediately.
    resonate.run(job_name, weather_data, latitude, longitude, year, month)
    return {"job_name": job_name}


@mcp.tool()
def probe_status(job_names):
    """Probe one or more jobs without blocking."""
    statuses = []
    for job_name in job_names:
        statuses.append({"job_name": job_name, "status": "check /await_result for result"})
    return statuses


@mcp.tool()
def await_result(job_names):
    """Block until jobs complete and return their results."""
    async def _gather():
        results = {}
        for n in job_names:
            handle = resonate.run(n, weather_data)  # reconnects to existing
            results[n] = await handle.result()
        return results
    return asyncio.run(_gather())
```





```rust title="src/bin/weather_server.rs"
#[tool_router(server_handler)]
impl WeatherBridge {
    #[tool(description = "Get the forecast for the given lat/lon.")]
    async fn get_forecast(&self, Parameters(p): Parameters<ForecastArgs>) -> Result<CallToolResult> {
        let id = format!("forecast-{}-{}", p.lat, p.lon);
        // Same id reconnects to an in-flight execution rather than re-fetching.
        let result: String = self.resonate
            .rpc(&id, "get_forecast", (p.lat, p.lon))
            .target("poll://any@workers")
            .await?;
        Ok(CallToolResult::success(vec![Content::text(result)]))
    }
}
```





The same job/promise ID is the deduplication key: if the agent retries with the same arguments, Resonate reconnects to the in-flight execution rather than running the work twice.

## Run it locally

You need a Resonate Server, the MCP server, and Claude Desktop (or any MCP client) configured to load the server.





Clone the repo and install dependencies (uses [uv](https://docs.astral.sh/uv/)):

```shell
git clone https://github.com/resonatehq-examples/example-async-tools-mcp-server-py
cd example-async-tools-mcp-server-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — MCP server"
uv run python weather_data.py
```





```shell
git clone https://github.com/resonatehq-examples/example-mcp-tools-rs
cd example-mcp-tools-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — durable worker"
cargo run --bin worker
```

The MCP server (`weather-server` binary) is launched by Claude Desktop directly via stdio — see the config below.





Configure Claude Desktop to launch the server. Add to `claude_desktop_config.json` (the Developers tab in Claude's settings shows the path):

```json
{
  "mcpServers": {
    "weather": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory", "ABSOLUTE/PATH/TO/example-async-tools-mcp-server-py",
        "run", "proxy.py"
      ]
    }
  }
}
```

Restart Claude Desktop. The three tools (`start_gathering`, `probe_status`, `await_result`) will appear in the MCP server panel. Ask Claude to gather historic weather data for a few cities — it will start jobs, poll their status, and collect results without blocking on each gather.

## Try the dedup story

Ask Claude to gather data for the same city twice. The second `start_gathering` call returns the same `job_name`, and Resonate's promise dedup means the underlying API call doesn't fire twice. This is the same primitive that makes safe LLM retries free.

## Related

- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — the same fire-and-forget shape, accessed via REST instead of MCP.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — pausing a workflow on external resolution.

---

---
url: https://docs.resonatehq.io/get-started/examples/async-http-api-endpoints
title: Async HTTP APIs
---

<img src="/images/example-async-http-api-dark.png" alt="Async HTTP API banner" className="hidden dark:block" />
<img src="/images/example-async-http-api-light.png" alt="Async HTTP API banner" className="block dark:hidden" />

A FastAPI gateway converts every inbound request into a durable workflow, returns a promise ID immediately, and exposes a `/wait` endpoint clients poll for completion.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Synchronous HTTP either blocks the client until work finishes or punts the polling problem to whoever calls you. Hand-rolled status tracking gets out of sync, server crashes leave clients guessing whether work completed, and retries duplicate work that already ran.

## Resonate's solution

Each inbound request becomes a durable workflow keyed by a client-provided ID. The gateway returns the ID immediately; clients poll a status endpoint that asks Resonate whether the promise has resolved. Crashes don't lose progress — the workflow resumes on a survivor and the same ID still answers the poll.

## Code walkthrough

Two processes: a **gateway** that accepts HTTP requests and a **worker** that runs the durable function.

### The gateway

`POST /begin` enqueues durable work and returns a promise ID. `GET /wait` polls for completion. The same client-provided ID deduplicates retries — sending `/begin` twice with the same ID reconnects to the in-flight execution.





```typescript title="gateway.ts"
import express from "express";
import { randomUUID } from "node:crypto";
import { Resonate } from "@resonatehq/sdk";

const app = express();
app.use(express.json());

const resonate = new Resonate({ url: "http://localhost:8001", group: "gateway" });

app.post("/begin", async (req, res) => {
  const id = (req.query.id as string) ?? randomUUID();
  const data = req.body && Object.keys(req.body).length > 0 ? req.body : { foo: "bar" };

  // beginRpc returns immediately. Same id reconnects to the in-flight execution.
  const handle = await resonate.beginRpc(
    id,
    "foo",
    data,
    resonate.options({ target: "poll://any@worker" }),
  );

  res.json({ promise: handle.id, status: "pending", wait: `/wait?id=${handle.id}` });
});

app.get("/wait", async (req, res) => {
  const id = req.query.id as string;
  const handle = await resonate.get(id);

  // done() is non-blocking — asks the server for current state.
  if (await handle.done()) {
    const result = await handle.result();
    return res.json({ status: "resolved", promise_id: id, result });
  }
  res.json({ status: "pending", promise_id: id });
});

app.listen(5001, "127.0.0.1");
```





```python title="main.py"
from __future__ import annotations

import asyncio
import os
import uuid

from fastapi import FastAPI, HTTPException
from resonate.resonate import Resonate

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
app = FastAPI()
resonate = Resonate(url=url, group="gateway")


@app.post("/begin")
def begin(data=None, id=None):
    # Client-provided ID enables deduplication and safe retries.
    if id is None:
        id = str(uuid.uuid4())
    if data is None:
        data = {"foo": "bar"}

    handle = resonate.options(target="poll://any@worker").rpc(id, "foo", data)
    return {"promise": handle.promise_id, "status": "pending", "wait": f"/wait?id={id}"}


@app.get("/wait")
async def wait(id: str):
    try:
        handle = await resonate.get(id)
        # Poll for completion — done() checks server state without re-dispatching.
        if handle.done():
            result = await handle.result()
            return {"status": "resolved", "promise_id": id, "result": result}
        return {"status": "pending", "promise_id": id, "message": "Processing in progress"}
    except Exception:
        raise HTTPException(status_code=404, detail=f"{id} not found")
```





```rust title="src/bin/gateway.rs"
use axum::{routing::{get, post}, Json, Router};
use resonate::prelude::*;
use uuid::Uuid;

async fn begin(State(r): State<Resonate>, Json(body): Json<Value>) -> impl IntoResponse {
    let id = body.get("id").and_then(|v| v.as_str()).map(String::from)
        .unwrap_or_else(|| Uuid::new_v4().to_string());

    // .spawn() returns a handle without blocking on completion.
    let _: ResonateHandle<Value> = r
        .rpc(&id, "foo", body.clone())
        .target("poll://any@worker")
        .spawn()
        .await
        .unwrap();

    Json(json!({ "promise": id, "status": "pending", "wait": format!("/wait?id={id}") }))
}

async fn wait(State(r): State<Resonate>, Query(q): Query<HashMap<String, String>>) -> impl IntoResponse {
    let id = q.get("id").cloned().unwrap_or_default();
    let handle: ResonateHandle<Value> = r.get(&id).await.unwrap();
    if handle.done().await.unwrap() {
        let result = handle.result().await.unwrap();
        return Json(json!({ "status": "resolved", "promise_id": id, "result": result }));
    }
    Json(json!({ "status": "pending", "promise_id": id }))
}
```





### The worker

`resonate.register(foo)` (Python) or `resonate.register("foo", foo)` (TypeScript) exposes `foo` as a durable function. The gateway's `rpc(...)` dispatches the call to whichever worker in the `worker` group claims it first; if that worker dies mid-execution, another picks up the workflow.





```typescript title="worker.ts"
import { Resonate, type Context } from "@resonatehq/sdk";

const resonate = new Resonate({ url: "http://localhost:8001", group: "worker" });

// Inputs and return value must be JSON-serializable.
function* foo(_: Context, data: unknown) {
  // Real workloads call ctx.run(stepFn, ...) for checkpointed side effects.
  return { result: `Processed: ${JSON.stringify(data)}`, timestamp: Date.now() };
}

resonate.register("foo", foo);
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os
import time
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="worker")


async def foo(ctx: Context, data) -> dict:
    # Real work goes here — external APIs, DB writes, anything serializable.
    return {"result": f"Processed: {data}", "timestamp": time.time()}


resonate.register(foo)


async def main() -> None:
    # Keep the worker alive to receive invocations.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/worker.rs"
use resonate::prelude::*;
use serde_json::Value;

#[resonate::function]
async fn foo(_: &Context, data: Value) -> Result<Value> {
    // Real workloads call ctx.run(stepFn, ...) for checkpointed side effects.
    Ok(json!({ "result": format!("Processed: {data}"), "timestamp": now() }))
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        group: Some("worker".into()),
        ..Default::default()
    });
    resonate.register(foo).unwrap();
    tokio::signal::ctrl_c().await.unwrap();
}
```





## Run it locally

You need a Resonate Server, the worker, and the gateway running in separate terminals.





Clone the repo and install:

```shell
git clone https://github.com/resonatehq-examples/example-async-http-api-ts
cd example-async-http-api-ts
bun install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
bun run worker
```

```shell title="Terminal 3 — gateway"
bun run gateway
```





Clone the repo and install dependencies (uses [uv](https://docs.astral.sh/uv/)):

```shell
git clone https://github.com/resonatehq-examples/example-async-http-api-py
cd example-async-http-api-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
uv run python worker.py
```

```shell title="Terminal 3 — gateway"
uv run uvicorn main:app --host 127.0.0.1 --port 5001
```





```shell
git clone https://github.com/resonatehq-examples/example-async-http-api-rs
cd example-async-http-api-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
cargo run --bin worker
```

```shell title="Terminal 3 — gateway"
cargo run --bin gateway
```





Begin a workflow:

```shell
curl -X POST "http://localhost:5001/begin?id=job-001" \
  -H "Content-Type: application/json" \
  -d '{"foo": "hello"}'
```

The response includes a `wait` URL. Poll it:

```shell
curl "http://localhost:5001/wait?id=job-001"
```

You'll see `pending` until the worker completes, then `resolved` with the result.

## Try the dedup story

Call `/begin` twice with the same `id`. Resonate doesn't run the work twice — the second call reconnects to the in-flight execution and the polling endpoint returns the same eventual result. This is the same idempotency primitive that makes safe retries inexpensive.

## Related

- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — the same gateway+worker shape, with a workflow that suspends on a durable promise.
- [Load balancing](/get-started/examples/load-balancing) — what happens when you run multiple workers in the same group.

---

---
url: https://docs.resonatehq.io/get-started/examples/async-rpc
title: Async RPC
---

<img src="/images/example-async-rpc-dark.png" alt="Async RPC banner" className="hidden dark:block" />
<img src="/images/example-async-rpc-light.png" alt="Async RPC banner" className="block dark:hidden" />

A gateway calls service A, which calls service B, which calls service C. Each step uses Resonate's remote function invocation APIs, so the entire chain is durable — a crash on any service resumes the call without re-running prior steps.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current).



  
  


## The problem

Cross-service calls inside a request flow are where most distributed systems fall over. The HTTP request from a client is ephemeral — if the client or any service in the chain crashes, the request is lost and has to start over. Teams paper this over with retries, idempotency keys, and saga frameworks; it's a lot of glue, and the seams leak.

## Resonate's solution

Resonate exposes two layers of remote function invocation:

- **`resonate.rpc(...)`** — *ephemeral to durable*. Called from a regular process (like an HTTP handler). The receiving function is durable; the caller is not.
- **`ctx.options(...).rpc(...)`** — *durable to durable*. Called from inside another durable function. Both ends checkpoint, so the chain stays resumable end-to-end.
- **`ctx.detached(...)`** — fire-and-forget dispatch from inside a durable function. Returns a promise handle without blocking on the result.

## Code walkthrough

The example chains a gateway through `service-a` → `service-b`. Each service is a separate process that registers its function with the Resonate Server and listens for invocations.

### The gateway (ephemeral → durable)





```typescript title="src/gateway.ts"
app.post("/await-chain", async (_req, res) => {
  const promiseId = "await-chain";
  // Ephemeral-to-durable: HTTP handler calls into a durable service.
  const handle = await resonate.beginRpc<number>(
    promiseId,
    "foo",
    "foo",
    resonate.options({ target: "poll://any@service-a" }),
  );
  // Block the HTTP response on the chain's result.
  const message = await handle.result();
  res.status(200).json({ message });
});
```





```python title="src/gateway.py"
@app.route("/await-chain", methods=["POST"])
def await_chain_route_handler():
    promise_id = "await-chain"
    # Ephemeral-to-durable: HTTP handler calls into a durable service.
    handle = resonate.options(target="poll://any@service-a").rpc(promise_id, "foo")
    # Block the HTTP response on the chain's result.
    import asyncio
    message = asyncio.run(handle.result())
    return jsonify({"message": message}), 200
```





`resonate.beginRpc` (TypeScript) / `resonate.options(...).rpc(...)` (Python) dispatches `foo` on whichever process is registered as `service-a`. The promise ID makes the call idempotent — re-running the same handler with the same ID reconnects to the in-flight execution rather than starting a duplicate chain.

### Service A → Service B (durable → durable)





```typescript title="src/service_a.ts"
function* foo(ctx: Context): Generator<any, number, any> {
  // ctx.rpc dispatches to service-b and waits for the result.
  // Both sides are durable; the call resumes if either process crashes.
  const result: number = yield* ctx.rpc<number>(
    "bar",
    ctx.options({ target: "poll://any@service-b" }),
  );
  return result + 1;
}

resonate.register("foo", foo);
```

```typescript title="src/service_b.ts"
function* bar(ctx: Context): Generator<any, number, any> {
  const result: number = yield* ctx.rpc<number>(
    "baz",
    ctx.options({ target: "poll://any@service-c" }),
  );
  return result + 1;
}

resonate.register("bar", bar);
```

For fire-and-forget calls, swap `ctx.rpc` for `ctx.detached`:

```typescript
// Detached: dispatch and don't wait. Returns immediately.
yield* ctx.detached("qux", ctx.options({ target: "poll://any@service-d" }));
```





```python title="src/service_a.py"
async def foo(ctx: Context) -> int:
    # ctx.options(...).rpc dispatches to service-b and waits for the result.
    # Both sides are durable; the call resumes if either process crashes.
    result = await ctx.options(target="poll://any@service-b").rpc("bar")
    return result + 1

resonate.register("foo", foo)
```

```python title="src/service_b.py"
async def bar(ctx: Context) -> int:
    result = await ctx.options(target="poll://any@service-c").rpc("baz")
    return result + 1

resonate.register("bar", bar)
```

For fire-and-forget calls — kicking off work without blocking on its result — use `ctx.detached`:

```python
# Detached: dispatch and don't wait. Returns the promise handle.
audit_future = ctx.options(target="poll://any@service-d").detached("qux")
audit_id = await audit_future.id()
```





The `ctx.options(...).rpc(...)` call inside a durable function is the durable equivalent of `await someService.bar()`. The result is checkpointed, so a worker that completes `bar` and then dies still passes its result back when the chain resumes.

## Run it locally

Both repos ship with nine services so you can exercise the await-chain, detached-chain, and fan-out flows.





```shell
git clone https://github.com/resonatehq-examples/example-async-rpc-ts
cd example-async-rpc-ts
bun install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

Start each service in its own terminal (`a` through `i`):

```shell
bun run a
bun run b
# ...c through i, one terminal each
```

Start the gateway:

```shell
bun run gateway
```





```shell
git clone https://github.com/resonatehq-examples/example-async-rpc-py
cd example-async-rpc-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

Start each service in its own terminal:

```shell
uv run python src/service_a.py
uv run python src/service_b.py
# ...service_c through service_i, one terminal each
```

Start the gateway:

```shell
uv run python src/gateway.py
```





Trigger the await-chain:

```shell
curl -X POST http://localhost:5000/await-chain
```

The gateway logs each step as the chain hops from `service-a` to `service-b` to `service-c`, returning a final value back through the gateway to the HTTP response.

## Try the recovery story

Trigger the chain, then kill `service-b` while `service-c` is still working. Restart `service-b`. The chain resumes — `service-b` doesn't re-call `service-c` (its result is already checkpointed); it just returns the cached result up the stack to `service-a`.

## Related

- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — the same ephemeral-to-durable pattern, focused on the HTTP boundary.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — `ctx.promise()` is the suspend-and-resume cousin of `ctx.options(...).rpc(...)`.

---

---
url: https://docs.resonatehq.io/get-started/examples/deep-research-agent
title: Deep research agent
---

<img src="/images/example-deep-research-agent-dark.png" alt="Deep Research Agent banner" className="hidden dark:block" />
<img src="/images/example-deep-research-agent-light.png" alt="Deep Research Agent banner" className="block dark:hidden" />

A research agent receives a broad topic, asks an LLM to break it into 2–3 subtopics, and recursively dispatches each subtopic to itself. Every LLM call and every recursive subagent is a durable promise — kill the worker mid-research, the tree resumes from the last unanswered branch.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Real research is recursive. A topic like "distributed systems" decomposes into "consensus", "replication", "failure detection" — each of which decomposes again. Doing this by hand is tedious; doing it with a single long LLM call hits context limits, takes forever, and can't recover from a transient failure.

Implementing the loop yourself means handling parallelism, retries, partial failure, and crash recovery on top of the LLM logic. Most agents skip recovery entirely — one timeout and the whole tree is lost.

## Resonate's solution

Define one durable function — `research(topic, depth)` — that prompts the LLM, dispatches subagents recursively when the LLM calls a tool, and joins the results. Each LLM call checkpoints. Each subagent is its own durable execution. Crashes mid-tree resume from the last unfinished branch; nothing re-runs that already finished.

## Code walkthrough

The agent is a single recursive function. Its only inputs are a topic and a depth budget; depth gates whether the LLM can call the `research` tool again or must summarize.





```typescript title="src/agent.ts"
export function* research(
  ctx: Context,
  topic: string,
  depth: number,
): Generator<any, string, any> {
  const messages = [
    { role: "system", content: SYSTEM_PROMPT },
    { role: "user", content: `Research ${topic}` },
  ];

  while (true) {
    // Prompt the LLM. Tool access only when depth > 0.
    const message = yield* ctx.run(prompt, messages, depth > 0);
    messages.push(message);

    if (message.tool_calls) {
      // Fan out: dispatch one durable subagent per tool call, in parallel.
      const handles = [];
      for (const tool_call of message.tool_calls) {
        const args = JSON.parse(tool_call.function.arguments);
        if (tool_call.function.name === "research") {
          const handle = yield* ctx.beginRpc(research, args.topic, depth - 1);
          handles.push([tool_call, handle]);
        }
      }
      // Fan in: each handle is durable; await them in order.
      for (const [tool_call, handle] of handles) {
        const result = yield* handle;
        messages.push({ role: "tool", tool_call_id: tool_call.id, content: result });
      }
    } else {
      return message.content || "";
    }
  }
}

resonate.register("research", research);
```





```python title="research.py"
from __future__ import annotations

import asyncio
import json
import os
import time
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url)


async def research(ctx: Context, topic: str, depth: int) -> str:
    messages = [
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": f"Research {topic}"},
    ]

    while True:
        # Prompt the LLM. Tool access only when depth > 0.
        message = await ctx.run(prompt, messages, depth > 0)
        messages.append(message)

        if message.tool_calls:
            # Fan out: dispatch one durable subagent per tool call, in parallel.
            handles = []
            for tool_call in message.tool_calls:
                args = json.loads(tool_call.function.arguments)
                if tool_call.function.name == "research":
                    handle = ctx.run(research, args["topic"], depth - 1)
                    handles.append((tool_call, handle))
            # Fan in: each handle is durable; await them in order.
            for (tool_call, handle) in handles:
                result = await handle
                messages.append({"role": "tool", "tool_call_id": tool_call.id, "content": result})
        else:
            return message.content


resonate.register(research)
```





```rust title="src/main.rs"
#[resonate::function]
async fn research(ctx: &Context, topic: String, depth: u32) -> Result<String> {
    let mut messages = vec![
        json!({"role": "system", "content": SYSTEM_PROMPT}),
        json!({"role": "user", "content": format!("Research {topic}")}),
    ];

    loop {
        let message = ctx.run(prompt, (messages.clone(), depth > 0)).await?;
        messages.push(message.clone());

        if let Some(tool_calls) = message["tool_calls"].as_array() {
            // Fan out: spawn one durable subagent per tool call.
            let mut handles = vec![];
            for tc in tool_calls {
                let args: Value = serde_json::from_str(tc["function"]["arguments"].as_str().unwrap())?;
                if tc["function"]["name"] == "research" {
                    let h = ctx.run(research, (args["topic"].as_str().unwrap().into(), depth - 1)).spawn()?;
                    handles.push((tc.clone(), h));
                }
            }
            // Fan in.
            for (tc, h) in handles {
                let result = h.await?;
                messages.push(json!({"role": "tool", "tool_call_id": tc["id"], "content": result}));
            }
        } else {
            return Ok(message["content"].as_str().unwrap_or("").to_string());
        }
    }
}
```





The recursion is the whole pattern. `ctx.beginRpc` (TS) / `ctx.run(research, ...)` without `await` (Python) / `ctx.run(...).spawn()` (Rust) dispatches a child `research` execution and returns a handle immediately — children can be awaited later, each checkpointing on its own LLM calls. The outer loop awaits handles in order and feeds their results back to the LLM as tool messages.

## Run it locally

You need an OpenAI API key, the Resonate Server, and the worker.





```shell
git clone https://github.com/resonatehq-examples/example-openai-deep-research-agent-ts
cd example-openai-deep-research-agent-ts
npm install
export OPENAI_API_KEY=sk-...
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — agent"
npx tsx src/index.ts
```

The agent prints a recursive trace as it decomposes the topic. Try killing the worker mid-research and restarting — execution resumes from the last unfinished branch.





```shell
git clone https://github.com/resonatehq-examples/example-openai-deep-research-agent-py
cd example-openai-deep-research-agent-py
uv sync
export OPENAI_API_KEY=sk-...
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — agent"
uv run python research.py
```

The agent prints a recursive trace as it decomposes the topic. Try killing the worker mid-research and restarting — execution resumes from the last unfinished branch.





```shell
git clone https://github.com/resonatehq-examples/example-openai-deep-research-agent-rs
cd example-openai-deep-research-agent-rs
cargo build
export OPENAI_API_KEY=sk-...
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — agent"
cargo run --bin research -- run-1 "Distributed systems" 2
```

The CLI takes `<id> <topic> [depth]`. Increase the depth and watch the call graph grow.





## Try the depth dial

The `depth` argument bounds the recursion. `depth=0` forces the LLM to summarize without calling the research tool. `depth=1` allows one layer of subagents but their children must summarize. Increase the depth and watch the call graph grow — `resonate tree research.1` from the CLI renders the full durable structure.

## Related

- [Async agent tools](/get-started/examples/async-agent-tools) — exposing durable workflows to an LLM via MCP.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — pausing an agent until a human approves the next step.

---

---
url: https://docs.resonatehq.io/get-started/examples/durable-serverless-cloud-run-workers
title: Cloud Run workers
---

<img src="/images/example-cloud-run-workers-dark.png" alt="Cloud Run Workers banner" className="hidden dark:block" />
<img src="/images/example-cloud-run-workers-light.png" alt="Cloud Run Workers banner" className="block dark:hidden" />

A countdown workflow running as a single Google Cloud Function. The function sleeps between notifications via `ctx.sleep`, terminating the container while suspended. Resonate fires the function back up at the right time and the workflow continues from the next iteration — long-running logic on short-lived compute.


TypeScript: `@resonatehq/sdk` v0.11.4 + `@resonatehq/gcp` for the Cloud Functions adapter. Python and Rust adapters are forthcoming.



  


## The problem

Cloud Functions and Cloud Run give you scale-to-zero and rapid horizontal scaling, but the runtime is stateless and execution-time-bounded. Long-running business logic — a 30-day trial expiry, a multi-step approval flow, a polling loop — doesn't fit the shape: hold a process open for hours and you're paying for idle compute, restart and you've lost your place.

The conventional escape is to chain a serverless trigger to a database to a scheduler to another trigger, with bespoke compensation when any link fails. That's a lot of glue per workflow.

## Resonate's solution

Write the workflow as a normal generator function. `ctx.sleep` checkpoints the wake-up time on the Resonate Server and suspends the workflow — the Cloud Function exits cleanly. When the sleep elapses, Resonate dispatches a fresh function invocation that resumes the workflow from the next line. The same applies to any `ctx.run` or `ctx.rpc`: every yield is a suspension point that can survive a cold start.

## Code walkthrough

The whole workflow is a generator. The Cloud Function entry point is one line: register the function and expose Resonate's HTTP handler.

### The countdown workflow

```typescript title="src/count.ts"
import type { Context } from "@resonatehq/sdk";

export function* countdown(
  ctx: Context,
  count: number,
  delay: number,
  url: string,
) {
  for (let i = count; i > 0; i--) {
    // Send a notification.
    yield* ctx.run(notify, url, `Countdown: ${i}`);
    // Sleep is a suspension point — the Cloud Function exits, then resumes.
    yield* ctx.sleep(delay * 60 * 1000);
  }
  yield* ctx.run(notify, url, "Done");
}

async function notify(_ctx: Context, url: string, msg: string) {
  await fetch(url, { method: "POST", body: msg, headers: { "Content-Type": "text/plain" } });
}
```

### The Cloud Function entry point

```typescript title="src/index.ts"
import { Resonate } from "@resonatehq/gcp";
import { countdown } from "./count";

const resonate = new Resonate();
resonate.register("countdown", countdown);

export const handler = resonate.handlerHttp();
```

`@resonatehq/gcp` wraps the SDK with a Cloud Functions adapter. `handlerHttp()` returns the HTTP handler the Functions runtime expects. Each invocation drives the workflow forward by one step (one `ctx.run` or one `ctx.sleep`), then exits.

## Run it locally

```shell
git clone https://github.com/resonatehq-examples/example-countdown-gcp-ts
cd example-countdown-gcp-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — Cloud Function in local dev mode"
npm run dev
```

The Cloud Function listens on `http://localhost:8080`. Pick a unique [ntfy.sh](https://ntfy.sh) topic name and start a countdown via the Resonate CLI:

```shell
resonate invoke countdown.1 \
  --func countdown \
  --arg 5 --arg 1 --arg "https://ntfy.sh/<your-topic>" \
  --target "http://localhost:8080"
```

Open the ntfy.sh topic in your browser. Notifications arrive once per minute. Now kill the local Function process mid-countdown — the workflow resumes from the next iteration when you restart it.

## Try the deploy story

Deploy the Resonate Server to Cloud Run, deploy the countdown as a Cloud Function (Gen 2), and trigger it via the Resonate CLI. The workflow can sleep for days between notifications without paying for idle compute — Cloud Functions only spin up to advance the workflow one step at a time. The repo's README walks through the full `gcloud run deploy` and `gcloud functions deploy` commands.

## Related

- [Lambda workers](/get-started/examples/durable-serverless-lambda-workers) — same suspend-and-resume pattern on AWS.
- [Durable sleep](/get-started/examples/durable-sleep) — the underlying primitive, focused on a non-serverless worker.

---

---
url: https://docs.resonatehq.io/get-started/examples/durable-serverless-lambda-workers
title: Lambda workers
---

<img src="/images/example-lambda-workers-dark.png" alt="Lambda Workers banner" className="hidden dark:block" />
<img src="/images/example-lambda-workers-light.png" alt="Lambda Workers banner" className="block dark:hidden" />

A Lambda function behind API Gateway acts as a stateless trigger. `POST /process-document` fires a durable Resonate workflow and returns `202` immediately. The workflow itself — download, OCR, LLM analysis, storage, notification — runs on a Resonate worker that doesn't share Lambda's 15-minute ceiling.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust example repo is forthcoming.



  
  


## The problem

Lambda's 15-minute execution ceiling is fine for short tasks but fatal for anything LLM-heavy, OCR-heavy, or human-in-the-loop. Workflows that run for an hour, a day, or a week need state that survives function timeouts — and the conventional escape (Step Functions, EventBridge, DynamoDB-backed state machines) is a lot of glue per workflow.

Restate's answer is to make Lambda the executor — your Lambda function *is* the workflow handler, with Restate Cloud calling back into it for each step. That requires a CDK stack, IAM roles, a Restate Cloud environment, service registration, and the Restate Lambda adapter.

## Resonate's solution

Lambda becomes a thin trigger. The handler does one thing: call `resonate.run(...)` to start a durable workflow, then return `202`. The workflow executes on a Resonate worker (long-running Node process) — it can take hours, await human approval, suspend on `ctx.sleep` for days. Status polling is a separate `GET /status/:jobId` Lambda that asks Resonate whether the promise has resolved.

No CDK. No service registration. The Lambda calls Resonate the same way it would call any other HTTP API.

## Code walkthrough

Two pieces inside the Lambda handler — start the workflow, poll its status — and the workflow itself, which lives in a separate file because it doesn't run in Lambda.

### The Lambda handler (the stateless trigger)





```typescript title="src/handler.ts"
import { Resonate } from "@resonatehq/sdk";
import { processDocument, type DocumentJob } from "./workflow.js";

// Module-level: created once per cold start, reused across warm invocations.
const resonate = new Resonate({ url: process.env["RESONATE_URL"] });
resonate.register("processDocument", processDocument);

async function handleProcessDocument(event: APIGatewayEvent) {
  const job: DocumentJob = JSON.parse(event.body ?? "{}");

  // Fire-and-forget: the workflow runs on a Resonate worker, not in Lambda.
  // resonate.run() returns immediately; Lambda exits without waiting.
  resonate.run(`doc/${job.jobId}`, processDocument, job).catch(console.error);

  return {
    statusCode: 202,
    body: JSON.stringify({ status: "accepted", jobId: job.jobId }),
  };
}

async function handleStatus(event: APIGatewayEvent) {
  const jobId = event.pathParameters?.["jobId"];
  const handle = await resonate.get(`doc/${jobId}`);
  if (!(await handle.done())) {
    return { statusCode: 200, body: JSON.stringify({ status: "processing", jobId }) };
  }
  return { statusCode: 200, body: JSON.stringify({ status: "done", result: await handle.result() }) };
}
```





```python title="lambda_function.py"
from __future__ import annotations

import asyncio
import json
import os

from resonate.resonate import Resonate

# Module-level: created once per cold start, reused across warm invocations.
url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="gateway")


def lambda_handler(event, context):
    if event["path"] == "/process-document" and event["httpMethod"] == "POST":
        job = json.loads(event["body"])
        # rpc dispatches to the worker group and returns immediately.
        resonate.options(target="poll://any@worker").rpc(
            f"doc/{job['jobId']}", "process_document", job,
        )
        return {"statusCode": 202,
                "body": json.dumps({"status": "accepted", "jobId": job["jobId"]})}

    if event["path"].startswith("/status/"):
        job_id = event["pathParameters"]["jobId"]

        async def _check():
            handle = await resonate.get(f"doc/{job_id}")
            if handle.done():
                return await handle.result()
            return None

        result = asyncio.run(_check())
        if result is not None:
            return {"statusCode": 200,
                    "body": json.dumps({"status": "done", "result": result})}
        return {"statusCode": 200,
                "body": json.dumps({"status": "processing", "jobId": job_id})}
```





Same `jobId` deduplicates retries — API Gateway can re-fire the request without spawning duplicate work.

### The workflow (runs on the worker, not Lambda)





```typescript title="src/workflow.ts"
import type { Context } from "@resonatehq/sdk";

export function* processDocument(ctx: Context, job: DocumentJob) {
  // Each ctx.run is a checkpoint. Crash mid-step, resume from the next.
  const pageCount = yield* ctx.run(downloadDocument, job);
  const text = yield* ctx.run(extractText, job, pageCount);
  const { summary, data } = yield* ctx.run(analyzeDocument, job, text);
  const storedAt = yield* ctx.run(storeResults, job, summary, data);
  const notifiedAt = yield* ctx.run(notifyRequester, job, storedAt);

  return { jobId: job.jobId, summary, extractedData: data, storedAt, notifiedAt };
}
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="worker")


async def process_document(ctx: Context, job: dict):
    # Each ctx.run is a checkpoint. Crash mid-step, resume from the next.
    page_count = await ctx.run(download_document, job)
    text = await ctx.run(extract_text, job, page_count)
    analysis = await ctx.run(analyze_document, job, text)
    stored_at = await ctx.run(store_results, job, analysis)
    notified_at = await ctx.run(notify_requester, job, stored_at)
    return {"jobId": job["jobId"], **analysis, "stored_at": stored_at, "notified_at": notified_at}


resonate.register(process_document)


async def main() -> None:
    # Keep the worker alive to receive invocations.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





The five steps are plain functions invoked through `ctx.run`. Each result is checkpointed in a durable promise, so a worker crash mid-LLM-call resumes from the next step rather than re-running the whole pipeline.

## Run it locally

Each repo simulates API Gateway + Lambda + the worker on your machine.





```shell
git clone https://github.com/resonatehq-examples/example-aws-lambda-ts
cd example-aws-lambda-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
npm run worker
```

```shell title="Terminal 3 — local Lambda + API Gateway simulator"
npm run local
```





```shell
git clone https://github.com/resonatehq-examples/example-lambda-workers-py
cd example-lambda-workers-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
uv run python worker.py
```

```shell title="Terminal 3 — local Lambda invocation"
uv run python lambda_function.py
```





Trigger a job:

```shell
curl -X POST http://localhost:3000/process-document \
  -H "Content-Type: application/json" \
  -d '{"jobId": "demo-1", "documentUrl": "https://example.com/doc.pdf", "requesterId": "alice", "type": "invoice"}'
```

Poll for the result:

```shell
curl http://localhost:3000/status/demo-1
```

Watch the worker terminal — the five steps log as they checkpoint.

## Try the recovery story

Start the workflow, then kill the worker mid-pipeline (e.g. during the LLM analysis step). Restart the worker. Resonate replays only the steps that hadn't checkpointed; everything before the kill is reused from durable promises. The `GET /status/:jobId` endpoint never reports a failure — it just shows `processing` longer.

## Related

- [Cloud Run workers](/get-started/examples/durable-serverless-cloud-run-workers) — same suspend-and-resume pattern on GCP, with the workflow itself running on the serverless platform.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — the same fire-and-forget shape on a non-serverless gateway.

---

---
url: https://docs.resonatehq.io/get-started/examples/durable-sleep
title: Durable sleep
---

<img src="/images/example-durable-sleep-dark.png" alt="Durable Sleep banner" className="hidden dark:block" />
<img src="/images/example-durable-sleep-light.png" alt="Durable Sleep banner" className="block dark:hidden" />

A workflow yields `ctx.sleep` and the runtime suspends it. Hours, days, or weeks later the worker wakes the workflow up exactly where it stopped — no cron, no scheduler, no external state.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

A real business process may need to wait for hours, days, or months — a 30-day trial expiry, a 24-hour billing cycle, a 7-day reminder. Holding a process open that long is fragile: machines reboot, deployments cycle, network blips kill connections.

The conventional escape is a cron job that wakes a separate worker which queries a database to figure out what to do next. That's three moving parts (cron, worker, state row) per workflow, and every one of them is a place for bugs to live.

## Resonate's solution

Yield a sleep from inside a workflow and the runtime checkpoints the wake-up time as a durable promise. The worker doesn't sit idle — it can pick up other work, restart, or get redeployed. When the wake-up time arrives, Resonate dispatches the workflow back to a worker and execution continues from the line after the sleep.

## Code walkthrough

Two processes: a **worker** that hosts the durable function and a **client** that dispatches it via async RPC.

### The sleeping workflow

The whole pattern is one line: `yield* ctx.sleep(ms)`. Everything around it is just framing.





```typescript title="worker.ts"
import { Resonate } from "@resonatehq/sdk";
import type { Context } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "workers",
});

function* sleepingWorkflow(ctx: Context, ms: number) {
  yield* ctx.run((ctx: Context) => console.log(`Sleeping for ${ms / 1000} seconds...`));
  yield* ctx.sleep(ms);
  return `Slept for ${ms / 1000} seconds`;
}

resonate.register("sleepingWorkflow", sleepingWorkflow);
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os
from datetime import timedelta
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="worker")


async def sleeping_workflow(ctx: Context, wf_id: str, secs: float):
    print(f"Workflow {wf_id} starting, will sleep for {secs} seconds.")
    await ctx.sleep(timedelta(seconds=secs))
    return f"Workflow {wf_id} completed after sleeping for {secs} seconds."


resonate.register(sleeping_workflow)


async def main() -> None:
    # Keep the worker alive to receive invocations.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/main.rs"
use resonate::prelude::*;
use std::time::Duration;

#[resonate::function]
async fn sleeping_workflow(ctx: &Context, secs: u64) -> Result<String> {
    println!("sleeping for {secs} seconds...");
    ctx.sleep(Duration::from_secs(secs)).await?;
    Ok(format!("slept for {secs} seconds"))
}
```





### Dispatching the workflow

The client uses async RPC to dispatch by ID. Reusing the same ID reconnects to a pending execution rather than starting a new sleep.





```typescript title="client.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "client",
});

const result = await resonate.rpc(
  "sleep-workflow-1",
  "sleepingWorkflow",
  5000,
  resonate.options({ target: "poll://any@workers" }),
);
console.log(result);
await resonate.stop();
```





```python title="client.py"
from __future__ import annotations

import asyncio
import os

from resonate.resonate import Resonate


async def main() -> None:
    url = os.environ.get("RESONATE_URL", "http://localhost:8001")
    resonate = Resonate(url=url, group="client")
    try:
        handle = resonate.options(target="poll://any@worker").rpc(
            "sleep-workflow-1", "sleeping_workflow", "sleep-workflow-1", 5.0,
        )
        result = await handle.result()
        print(result)
    finally:
        await resonate.stop()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/client.rs"
use resonate::prelude::*;

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });

    let result: String = resonate
        .rpc("sleep-workflow-1", "sleeping_workflow", 5u64)
        .target("poll://any@workers")
        .await
        .expect("rpc to worker failed");

    println!("{result}");
}
```





## Run it locally

You need the Resonate Server, the worker, and a client to dispatch.





Clone the repo:

```shell
git clone https://github.com/resonatehq-examples/example-durable-sleep-ts
cd example-durable-sleep-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
npx tsx worker.ts
```

```shell title="Terminal 3 — client"
npx tsx client.ts
```

After ~5 seconds the client prints `Slept for 5 seconds`. Now kill the worker mid-sleep and restart — the workflow resumes and still completes its sleep.





Clone the repo (uses [uv](https://docs.astral.sh/uv/)):

```shell
git clone https://github.com/resonatehq-examples/example-durable-sleep-py
cd example-durable-sleep-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
uv run python worker.py
```

```shell title="Terminal 3 — client"
uv run python client.py
```

After ~5 seconds the client prints the completion message. Kill the worker mid-sleep and restart — the workflow resumes and still completes.





```shell
git clone https://github.com/resonatehq-examples/example-durable-sleep-rs
cd example-durable-sleep-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
cargo run --bin worker
```

```shell title="Terminal 3 — client"
cargo run --bin client
```

After ~5 seconds the client prints the completion message. Kill the worker mid-sleep and restart — the workflow resumes and still completes.





## Try the long-sleep story

Change the sleep duration to a day, week, or month. The workflow sleeps without holding a process open — kill the worker, redeploy your code, restart your laptop. When the wake-up time arrives, Resonate dispatches the workflow to whichever worker is alive.

## Related

- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — same suspension primitive, but resolved by an external signal instead of a timer.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — kicking off long-running work without blocking the caller.

---

---
url: https://docs.resonatehq.io/get-started/examples/fan-out-fan-in
title: Fan-out / fan-in
---

<img src="/images/example-fan-out-fan-in-dark.png" alt="Fan-out Fan-in banner" className="hidden dark:block" />
<img src="/images/example-fan-out-fan-in-light.png" alt="Fan-out Fan-in banner" className="block dark:hidden" />

A workflow spawns four notification channels (email, SMS, Slack, push) in parallel and joins their results. Total wall time approaches the slowest channel, not the sum. If one channel fails and retries, the others stay checkpointed — they don't re-send.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development. Go: `0.1.0` is tagged, but the tag lacks the `v` prefix Go's module resolver requires, so the example pins a `main` commit instead (see [Go SDK](/develop/go)).



  
  
  
  


## The problem

Sequential calls — even three or four — turn into the latency tax you don't notice until you do. Fan them out manually with `Promise.all` (or its language equivalent) and you've collapsed the latency, but you've also given up checkpointing: a crash mid-batch re-runs everything when the workflow recovers, and a retry of one branch blasts the same email twice to the customer.

## Resonate's solution

Each branch becomes its own durable promise. Spawn them with `beginRun` (TypeScript), unawaited `ctx.run(...)` handles (Python), `.spawn()` (Rust), or `ctx.RPC` (Go) — all branches run concurrently. If a single branch fails and retries, the others are already checkpointed; they don't re-execute. Crash recovery only re-runs whatever was in flight when the worker died.

## Code walkthrough

The fan-out is N spawn calls. The fan-in is N awaits. The fact that each is durable is what makes this safe — every other implementation has subtle re-execution bugs.





```typescript title="src/workflow.ts"
import type { Context } from "@resonatehq/sdk";
import { sendEmail, sendSms, sendSlack, sendPush, type OrderEvent } from "./channels";

export function* notifyAll(ctx: Context, event: OrderEvent, simulateCrash: boolean) {
  const start = Date.now();

  // Fan-out: spawn all 4 channels at once. Each beginRun returns a future.
  const emailFuture = yield* ctx.beginRun(sendEmail, event);
  const smsFuture   = yield* ctx.beginRun(sendSms, event);
  const slackFuture = yield* ctx.beginRun(sendSlack, event);
  const pushFuture  = yield* ctx.beginRun(sendPush, event, simulateCrash);

  // Fan-in: each future is durable. If push retries, email/sms/slack stay
  // checkpointed and do NOT re-send.
  const results = [
    yield* emailFuture,
    yield* smsFuture,
    yield* slackFuture,
    yield* pushFuture,
  ];

  return {
    orderId: event.orderId,
    channelsNotified: results.filter((r) => r.success).length,
    totalMs: Date.now() - start,
    results,
  };
}
```





```python title="workflow.py"
from __future__ import annotations

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from resonate.context import Context

from channels import send_email, send_push, send_slack, send_sms


async def notify_all(ctx: Context, event: dict, simulate_crash: bool):
    # Fan-out: ctx.run(...) returns a handle immediately, so all four
    # channels start at once — each is its own durable child.
    f_email = ctx.run(send_email, event)
    f_sms = ctx.run(send_sms, event)
    f_slack = ctx.run(send_slack, event)
    f_push = ctx.run(send_push, event, simulate_crash)

    # Fan-in: await each handle to collect its result. If push retries, the
    # others stay checkpointed and do NOT re-send.
    email = await f_email
    sms = await f_sms
    slack = await f_slack
    push = await f_push
    results = [email, sms, slack, push]
    return {
        "order_id": event["order_id"],
        "channels_notified": sum(1 for r in results if r.get("success")),
        "results": results,
    }
```

In the v0.7 SDK line, `ctx.run(...)` returns a handle immediately without blocking, so issuing all four calls first starts every channel concurrently; awaiting each handle then collects the results. Each `ctx.run` is a durable child checkpoint, so if push retries, email/SMS/Slack stay checkpointed and do not re-execute.





```rust title="src/main.rs"
use resonate::prelude::*;
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Clone)]
struct WorkItem { id: u32, data: String }

#[derive(Serialize, Deserialize, Debug)]
struct WorkResult { id: u32, output: String }

#[resonate::function]
async fn fan_out_fan_in(ctx: &Context, items: Vec<WorkItem>) -> Result<Vec<WorkResult>> {
    // Fan-out: spawn three items in parallel.
    let h1 = ctx.run(process_item, items[0].clone()).spawn()?;
    let h2 = ctx.run(process_item, items[1].clone()).spawn()?;
    let h3 = ctx.run(process_item, items[2].clone()).spawn()?;

    // Fan-in: each handle is individually durable.
    let r1 = h1.await?;
    let r2 = h2.await?;
    let r3 = h3.await?;
    Ok(vec![r1, r2, r3])
}

#[resonate::function]
async fn process_item(item: WorkItem) -> Result<WorkResult> {
    Ok(WorkResult {
        id: item.id,
        output: format!("Processed: {} (item #{})", item.data, item.id),
    })
}
```





```go title="main.go"
type FanoutArgs struct {
	Channels []string `json:"channels"`
	Message  string   `json:"message"`
}

type FanoutResult struct {
	Delivered []Delivery `json:"delivered"`
}

type SendArgs struct {
	Channel string `json:"channel"`
	Message string `json:"message"`
}

type Delivery struct {
	Channel string `json:"channel"`
	OK      bool   `json:"ok"`
	Reason  string `json:"reason,omitempty"`
}

// fanout dispatches one ctx.RPC call per channel without awaiting in between,
// then awaits all of them. The dispatches happen in series in user code but
// run concurrently on the server side; the Awaits block until every child
// promise settles.
func fanout(ctx *resonate.Context, args FanoutArgs) (FanoutResult, error) {
	futures := make([]*resonate.Future, 0, len(args.Channels))
	for _, ch := range args.Channels {
		f, err := ctx.RPC("send", SendArgs{Channel: ch, Message: args.Message})
		if err != nil {
			return FanoutResult{}, err
		}
		futures = append(futures, f)
	}

	out := FanoutResult{Delivered: make([]Delivery, 0, len(futures))}
	for i, f := range futures {
		var d Delivery
		if err := f.Await(&d); err != nil {
			out.Delivered = append(out.Delivered, Delivery{
				Channel: args.Channels[i],
				OK:      false,
				Reason:  err.Error(),
			})
			continue
		}
		out.Delivered = append(out.Delivered, d)
	}
	return out, nil
}

// send is the child function that "delivers" a message to one channel. In a
// real system this would call a provider API (Twilio, SES, Slack, ...). Here
// it just prints and returns a Delivery record.
func send(_ *resonate.Context, args SendArgs) (Delivery, error) {
	fmt.Printf("  [send] %-8s <- %q\n", args.Channel, args.Message)
	return Delivery{Channel: args.Channel, OK: true}, nil
}
```

Go's fan-out uses `ctx.RPC` — each call creates a durable child promise for the registered `send` function and returns a `*Future` without waiting for the child to finish. The second loop awaits each future to fan in; the children run concurrently as separate durable promises, dispatched by the server to any worker subscribed to `send`.





The TypeScript example includes a `--crash` flag that simulates the push channel failing on its first attempt. When you run it with `--crash`, the workflow retries the push channel — but watching the logs, email/SMS/Slack don't re-send. They're each their own durable promise, already resolved.

## Run it locally





```shell
git clone https://github.com/resonatehq-examples/example-fan-out-fan-in-ts
cd example-fan-out-fan-in-ts
bun install
```

Run the happy path (all 4 channels in parallel):

```shell
bun run src/index.ts
```

Then run with the crash flag — push fails, retries, but the other three stay completed:

```shell
bun run src/index.ts -- --crash
```

The log output shows the wall time vs the sum of the individual channel times — fan-out collapses the total to roughly `max(channels)`.





```shell
git clone https://github.com/resonatehq-examples/example-fan-out-fan-in-py
cd example-fan-out-fan-in-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — happy path"
uv run python main.py
```

Or with the crash flag — push fails, retries, but the other three stay completed:

```shell
uv run python main.py --crash
```





```shell
git clone https://github.com/resonatehq-examples/example-fan-out-fan-in-rs
cd example-fan-out-fan-in-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
cargo run
```

```shell title="Terminal 3 — invoke"
resonate invoke fan-out.1 \
  --func fan_out_fan_in \
  --arg '[{"id":1,"data":"a"},{"id":2,"data":"b"},{"id":3,"data":"c"}]'
```





```shell
git clone https://github.com/resonatehq-examples/example-fan-out-fan-in-go
cd example-fan-out-fan-in-go
go mod download
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — workflow"
go run .
# or with custom channels
go run . -channels=email,sms,slack,push,webhook -message="ship it"
```

The single process registers both `fanout` and `send`, then invokes the workflow. The `[send]` lines arrive in non-deterministic order — that's the concurrency — while the final aggregation respects the input channel order.





## Try the recovery story

While the fan-out is mid-flight, kill the worker. Resonate replays only the branches that hadn't checkpointed; everything that completed before the kill is reused from durable promises. The wall time goes up by however long the worker was down, but no branch double-executes.

## Related

- [Recursive factorial](/get-started/examples/recursive-factorial) — the same primitive, applied to a recursive call graph.
- [Deep research agent](/get-started/examples/deep-research-agent) — fan-out applied to LLM tool calls.

---

---
url: https://docs.resonatehq.io/get-started/examples/hello-world
title: Hello world
---

<img src="/images/example-hello-world-dark.png" alt="Hello World banner" className="hidden dark:block" />
<img src="/images/example-hello-world-light.png" alt="Hello World banner" className="block dark:hidden" />

The smallest example that exercises the durable execution loop. A registered workflow function calls two leaf functions through `ctx.run`, and Resonate checkpoints each return value.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Before any "real" example makes sense, you need to see the wiring: a function gets registered, the workflow runtime invokes it, sub-calls go through a `Context`, and each step's result is checkpointed. Without that mental model, every more elaborate example reads as magic.

## Resonate's solution

Two things, both small. **Register** a function with the Resonate instance — that's how Resonate knows it can dispatch the function and durably checkpoint its result. **Invoke** it through the run/RPC API — that's how the function moves from "regular code" to "durable workflow." The rest of every example in this section is variations on those two moves.

## Code walkthrough

The workflow is a generator (TypeScript) or async function (Python) or `#[resonate::function]` async fn (Rust). It receives a `Context` and calls leaf functions through `ctx.run`. Leaves can be plain functions — Resonate handles the dispatch and the checkpointing.





```typescript title="index.ts"
import { Resonate } from "@resonatehq/sdk";
import type { Context } from "@resonatehq/sdk";

const resonate = new Resonate();

async function bar(_: Context, greetee: string) {
  return `Hello ${greetee} from bar!`;
}

async function baz(_: Context, greetee: string) {
  return `Hello ${greetee} from baz!`;
}

function* foo(ctx: Context, greetee: string): Generator<any, string, any> {
  // Each ctx.run is a checkpoint — its return value is durably stored.
  const barGreeting = yield* ctx.run(bar, greetee);
  const bazGreeting = yield* ctx.run(baz, greetee);
  return `Hello ${greetee} from foo! ${barGreeting} ${bazGreeting}`;
}

const fooR = resonate.register("foo", foo);

const result = await fooR.run("greeting-workflow", "World");
console.log(result);
await resonate.stop();
```





```python title="main.py"
from __future__ import annotations

import asyncio
import os
import time
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context


async def bar(ctx: Context, greetee: str) -> str:
    return f"Hello {greetee} from bar!"


async def baz(ctx: Context, greetee: str) -> str:
    return f"Hello {greetee} from baz!"


async def foo(ctx: Context, greetee: str) -> str:
    # Each ctx.run is a checkpoint — its return value is durably stored.
    bar_greeting = await ctx.run(bar, greetee=greetee)
    baz_greeting = await ctx.run(baz, greetee=greetee)
    return f"Hello {greetee} from foo! {bar_greeting} {baz_greeting}"


async def main() -> None:
    url = os.environ.get("RESONATE_URL", "http://localhost:8001")
    r = Resonate(url=url)
    r.register(foo)
    try:
        handle = r.run(f"greeting-{time.time_ns()}", foo, "World")
        result = await handle.result()
        print(result)
    finally:
        await r.stop()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/main.rs"
use resonate::prelude::*;

#[resonate::function]
async fn greet(ctx: &Context, name: String) -> Result<String> {
    let greeting = ctx.run(format_greeting, name).await?;
    Ok(greeting)
}

#[resonate::function]
async fn format_greeting(name: String) -> Result<String> {
    Ok(format!("Hello, {name}! Welcome to durable execution."))
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });
    resonate.register(greet).unwrap();
    resonate.register(format_greeting).unwrap();

    println!("Worker started. Waiting for invocations...");
    tokio::signal::ctrl_c().await.expect("Failed to listen for ctrl-c");
}
```





The TypeScript example invokes the workflow in-process — no server needed. The Python and Rust examples register the function with a long-running worker and connect to a Resonate Server.

## Run it locally





Clone the repo:

```shell
git clone https://github.com/resonatehq-examples/example-hello-world-ts
cd example-hello-world-ts
npm install
```

Run the workflow in-process:

```shell
npx tsx index.ts
```

You should see three log lines (`running foo`, `running bar`, `running baz`, possibly with `foo` repeating as the workflow replays after each yield) followed by the assembled greeting.





Clone the repo:

```shell
git clone https://github.com/resonatehq-examples/example-hello-world-py
cd example-hello-world-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — run the workflow"
uv run main.py
```

You should see the assembled greeting printed after all three durable steps checkpoint.





Clone the repo and build:

```shell
git clone https://github.com/resonatehq-examples/example-hello-world-rs
cd example-hello-world-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
cargo run
```

```shell title="Terminal 3 — invoke"
resonate invoke greet-1 --func greet --arg '"World"'
```

Inspect the durable call graph:

```shell
resonate tree greet-1
```





## Try the recovery story (Rust)

With the worker running in Rust, kill it mid-execution and restart. Resonate replays the workflow from the last checkpointed step rather than from the beginning. `resonate tree greet-1` renders the durable call graph as it grows.

## Related

- [Durable sleep](/get-started/examples/durable-sleep) — adds suspension to the picture.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — adds external resolution via a durable promise.

---

---
url: https://docs.resonatehq.io/get-started/examples/human-in-the-loop
title: Human-in-the-loop
---

<img src="/images/example-human-in-the-loop-dark.png" alt="Human in the Loop banner" className="hidden dark:block" />
<img src="/images/example-human-in-the-loop-light.png" alt="Human in the Loop banner" className="block dark:hidden" />

A workflow blocks on a durable promise, prints a callback URL, and resumes the moment a human resolves it — from any process, any machine, any time.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Real processes wait on humans — refunds, reviews, address confirmations — for seconds to weeks, with the answer arriving over email, webhook, UI, or CLI. Without a runtime that understands suspension, you hand-roll the coordination layer: a queue to park the work, a job to wake it up, a row to track which step you're on, a polling loop somewhere — every shop reinvents it, every implementation has its own bugs.

## Resonate's solution

Yield a Resonate Promise from inside a workflow and execution suspends until that promise resolves. The promise has a stable ID; anything that knows the ID — another process, a CLI, an HTTP handler, a button click — can resolve it. No scheduler, no queue, no external state machine.

## Code walkthrough

Two processes: a **worker** runs the workflow, a **gateway** drives HTTP.

### The blocking workflow

The workflow creates a promise, makes its ID visible (here via a `sendEmail` step that prints a callback URL), then yields the promise. Execution pauses until something resolves it.





```typescript title="worker.ts"
function* fooWorkflow(ctx: Context, workflowId: string) {
  // Latent durable promise — resolved externally.
  const blockingPromise = yield* ctx.promise({});

  // Make the promise ID reachable from outside — email, webhook, log, etc.
  yield* ctx.run(sendEmail, blockingPromise.id);
  console.log("workflow blocked, waiting on human interaction");

  // Suspend until the promise resolves. Survives crashes.
  const data = yield* blockingPromise;
  console.log(`workflow unblocked, promise resolved with ${data}`);
  return `foo workflow ${workflowId} complete`;
}

resonate.register("foo-workflow", fooWorkflow);
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="workers")


async def send_email(ctx: Context, promise_id: str) -> None:
    print(f"workflow blocked, waiting on human interaction (promise id: {promise_id!r})")


async def foo(ctx: Context, workflow_id: str):
    # Latent durable promise — resolved externally.
    blocking_promise = ctx.promise()
    promise_id = await blocking_promise.id()

    # Make the promise ID reachable from outside — email, webhook, log, etc.
    await ctx.run(send_email, promise_id)

    # Suspend until the promise resolves. Survives crashes.
    data = await blocking_promise
    print(f"workflow {workflow_id} unblocked, promise resolved")
    return {"message": f"workflow {workflow_id} completed"}


resonate.register(foo)
```





```rust title="src/bin/worker.rs"
use resonate::prelude::*;

#[resonate::function]
async fn foo(ctx: &Context, workflow_id: String) -> Result<String> {
    // Latent durable promise — resolved externally.
    let blocking_promise = ctx.promise::<bool>().create()?;
    let promise_id = blocking_promise.id().await?;

    // Make the promise ID reachable from outside — email, webhook, log, etc.
    ctx.run(send_email, promise_id).await?;
    println!("blocked, waiting on human interaction (workflow {workflow_id})");

    // Suspend until the promise resolves. Survives crashes.
    let _approved = blocking_promise.await?;
    println!("unblocked, promise resolved");
    Ok(format!("workflow {workflow_id} completed"))
}
```





### Resolving the promise

The gateway exposes two endpoints — one to start a workflow, one to resolve the blocking promise. Resolving the promise unblocks the workflow waiting on that ID, from any process.





```typescript title="gateway.ts"
app.post("/start-workflow", async (req, res) => {
  const workflowId = req.body?.workflow_id;
  // Same workflow_id reconnects to a PENDING execution rather than starting a new one.
  const result = await resonate.rpc(
    workflowId,
    "foo-workflow",
    workflowId,
    resonate.options({ target: "poll://any@workers" }),
  );
  res.status(200).json({ message: result });
});

app.get("/unblock-workflow", async (req, res) => {
  const promiseId = req.query.promise_id as string;
  const data = Buffer.from(JSON.stringify("human_approval"), "utf8").toString("base64");
  await resonate.promises.resolve(promiseId, { data });
  res.status(200).json({ message: "workflow unblocked" });
});
```





```python title="gateway.py"
from __future__ import annotations

import asyncio
import os

from flask import Flask, jsonify, request
from resonate.resonate import Resonate
from resonate.types import Value

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="gateway")
app = Flask(__name__)


@app.route("/start-workflow", methods=["POST"])
def start_workflow():
    data = request.get_json()
    # Same workflow_id reconnects to a PENDING execution rather than starting a new one.
    handle = resonate.options(target="poll://any@workers").rpc(
        data["workflow_id"], "foo", data["workflow_id"]
    )
    return jsonify({"message": f"workflow {data['workflow_id']} started"}), 200


@app.route("/unblock-workflow", methods=["GET"])
def unblock_workflow():
    promise_id = request.args.get("promise_id")
    asyncio.run(resonate.promises.resolve(promise_id, Value(data="human_approval")))
    return jsonify({"message": "workflow unblocked"}), 200
```





```rust title="src/bin/gateway.rs"
use axum::{extract::{Path, State}, response::IntoResponse, Json};
use resonate::prelude::*;
use resonate::types::Value;
use serde::Deserialize;
use serde_json::json;
use std::sync::Arc;

#[derive(Deserialize)]
struct StartReq { workflow_id: String }

#[derive(Clone)]
struct AppState { resonate: Arc<Resonate> }

async fn start_workflow(
    State(state): State<AppState>,
    Json(req): Json<StartReq>,
) -> impl IntoResponse {
    // Same workflow_id reconnects to a PENDING execution rather than starting a new one.
    let result: String = state.resonate
        .rpc(&req.workflow_id, "foo", &req.workflow_id)
        .target("poll://any@workers")
        .await
        .unwrap();
    Json(json!({ "message": result }))
}

async fn resolve(
    State(state): State<AppState>,
    Path(promise_id): Path<String>,
) -> impl IntoResponse {
    state.resonate.promises.resolve(&promise_id, Value::from_serializable(json!(true)).unwrap()).await.unwrap();
    Json(json!({ "message": "promise resolved" }))
}
```





## Run it locally

You need the Resonate Server, the worker, and the gateway running.





Clone the repo and install dependencies (uses [Bun](https://bun.sh/)):

```shell
git clone https://github.com/resonatehq-examples/example-human-in-the-loop-ts
cd example-human-in-the-loop-ts
bun install
```

In separate terminals, start the Resonate Server, the worker, and the gateway:

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — gateway"
bun run gateway.ts
```

```shell title="Terminal 3 — worker"
bun run worker.ts
```

Start a workflow:

```shell
curl -X POST http://localhost:5001/start-workflow \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "hitl-001"}'
```

The worker prints a callback URL — visit it to unblock the workflow.





Clone the repo and install dependencies (uses [uv](https://docs.astral.sh/uv/)):

```shell
git clone https://github.com/resonatehq-examples/example-human-in-the-loop-py
cd example-human-in-the-loop-py
uv sync
```

In separate terminals, start the Resonate Server, the worker, and the gateway:

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — gateway"
uv run gateway
```

```shell title="Terminal 3 — worker"
uv run worker
```

Start a workflow:

```shell
curl -X POST http://localhost:5001/start-workflow \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "hitl-001"}'
```

The worker prints a callback URL — visit it to unblock the workflow.





Clone the repo and build (uses the [Rust toolchain](https://rustup.rs/)):

```shell
git clone https://github.com/resonatehq-examples/example-human-in-the-loop-rs
cd example-human-in-the-loop-rs
cargo build
```

In separate terminals, start the Resonate Server, the worker, and the gateway:

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — gateway"
cargo run --bin gateway
```

```shell title="Terminal 3 — worker"
cargo run --bin worker
```

Start a workflow:

```shell
curl -X POST http://localhost:5001/start-workflow \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "hitl-001"}'
```

The worker prints a `CLICK TO RESOLVE` URL — visit it to unblock the workflow.





## Try the recovery story

Same setup, load balancing and crash recovery included. Run multiple workers in parallel, start several workflows with different IDs, and watch them spread across workers. Kill one mid-block — Resonate reassigns it and the workflow resumes on a survivor.

## Related

- [Load balancing](/get-started/examples/load-balancing) — same primitive, focused on multi-worker dispatch.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — kicking off long workflows from HTTP without holding the connection.

---

---
url: https://docs.resonatehq.io/get-started/examples
title: Examples
---

<img src="/images/banner-examples-dark.png" alt="Resonate Examples banner" className="hidden dark:block" />
<img src="/images/banner-examples-light.png" alt="Resonate Examples banner" className="block dark:hidden" />

Runnable example projects, one per pattern. Clone, read, modify.

---

---
url: https://docs.resonatehq.io/get-started/examples/kafka-worker
title: Kafka worker
---

<img src="/images/example-kafka-worker-dark.png" alt="Kafka Worker banner" className="hidden dark:block" />
<img src="/images/example-kafka-worker-light.png" alt="Kafka Worker banner" className="block dark:hidden" />

A consumer pulls messages from a Kafka topic and dispatches each one through a durable Resonate workflow. Per-message state lives in durable promises, so a worker that dies mid-batch resumes cleanly without redoing completed steps.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



All three repos run against [Redpanda](https://redpanda.com/) for local development because the broker boots in seconds, but the code uses the Kafka wire protocol — `kafkajs` for TypeScript, `confluent-kafka-python` for Python, `rdkafka` for Rust. Point any of them at any Kafka-compatible broker — Apache Kafka, Redpanda, or a managed offering — by changing the bootstrap-server config.



  
  
  


## The problem

A worker between two queues has two recurring problems. **Head-of-line blocking** — if the first message kicks off an hour-long task and the next one would take 30 seconds, the short job sits behind the long one unless the worker handles concurrency. **Repeated work on crashes** — if a multi-step task is half-done when the worker dies, restart usually means repeating completed steps and emitting duplicate side-effects downstream.

Most teams write per-message dedup tables, idempotency keys, and recovery scaffolding — repeatedly, and rarely well.

## Resonate's solution

Each Kafka message becomes the ID of a durable workflow. Resonate runs the workflow concurrently with whatever else is in flight, checkpoints every step, and dedups by ID — so a retry of a partially-completed message reconnects to its in-flight execution rather than starting over. When the workflow finishes, the worker emits a "done" message to the next topic.

## Code walkthrough

The pattern is a small consume loop that hands each message to a durable workflow run. The workflow itself does the per-message work — here, deleting batches of records until none remain, then emitting a completion event.

### The durable workflow





```typescript title="src/workflow.ts"
import { Resonate, type Context } from "@resonatehq/sdk";

export const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "workers",
});

function* workflow(ctx: Context, recordId: string, offset: string) {
  console.log(`processing record ${recordId} (offset ${offset})`);
  // Loop until deleteBatch reports no more rows.
  while (yield* ctx.run(deleteBatch, recordId)) {
    yield* ctx.sleep(5_000);
  }
  yield* ctx.run(enqueueCompletion, recordId, offset);
}

resonate.register("workflow", workflow);
```





```python title="record_deletor/delete.py"
from __future__ import annotations

import asyncio
import json
import os
from datetime import timedelta
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url)


async def delete_batch(ctx: Context, record_id: str, batch_size: int = 10) -> bool:
    # Real work goes here. Returns True if more batches remain.
    print(f"deleting a batch of rows for record {record_id}")
    # ...transient failures throw; durable retry handles them.
    return more_remaining


async def enqueue(ctx: Context, msg_id: str, previous_offset: int) -> None:
    # Emit a completion event to the downstream topic.
    payload = json.dumps((msg_id, previous_offset)).encode("utf-8")
    producer.produce("records_that_were_deleted", value=payload)
    producer.flush()


async def workflow(ctx: Context, record_id: str, offset: int) -> None:
    print(f"processing record {record_id} (offset {offset})")
    # Loop until delete_batch reports no more rows.
    while await ctx.run(delete_batch, record_id):
        await ctx.sleep(timedelta(seconds=5))
    await ctx.run(enqueue, record_id, offset)


resonate.register(workflow)
```





```rust title="src/lib.rs"
use resonate::prelude::*;
use std::time::Duration;

#[resonate::function]
pub async fn workflow(ctx: &Context, record_id: String, offset: i64) -> Result<()> {
    println!("processing record {record_id} (offset {offset})");
    // Loop until delete_batch reports no more rows.
    while ctx.run(delete_batch, record_id.clone()).await? {
        ctx.sleep(Duration::from_secs(5)).await?;
    }
    ctx.run(enqueue_completion, (record_id, offset)).await?;
    Ok(())
}
```





Each `ctx.run` is a checkpoint. A worker crash mid-loop resumes from the next batch rather than from message zero, and `delete_batch` / `deleteBatch` doesn't run again for batches that already completed.

### The Kafka consumer





```typescript title="src/consumer.ts"
const consumer = kafka.consumer({ groupId: CONSUMER_GROUP_ID });
await consumer.connect();
await consumer.subscribe({ topic: TOPIC_TO_DELETE, fromBeginning: true });

await consumer.run({
  eachMessage: async ({ message }) => {
    const recordId = JSON.parse(message.value!.toString("utf-8")) as string;
    // beginRun is non-blocking. The recordId acts as the durable promise id,
    // so duplicate invocations dedupe.
    await resonate.beginRun(recordId, "workflow", recordId, message.offset);
  },
});
```





```python title="record_deletor/consumer.py"
def consume():
    consumer.subscribe(["records_to_be_deleted"])
    try:
        while True:
            msg = consumer.poll(timeout=1.0)
            if msg is None or msg.error():
                continue
            record_id = json.loads(msg.value().decode("utf-8"))
            if isinstance(record_id, str):
                record_id = [record_id]
            # The message ID is the workflow ID — same record reconnects
            # to its in-flight execution rather than starting over.
            resonate.run(record_id[0], workflow, record_id[0], msg.offset())
    finally:
        consumer.close()
```





```rust title="src/bin/consumer.rs"
let consumer: StreamConsumer = ClientConfig::new()
    .set("group.id", CONSUMER_GROUP_ID)
    .set("bootstrap.servers", "localhost:9092")
    .create()?;
consumer.subscribe(&[TOPIC_TO_DELETE])?;

while let Some(msg) = consumer.recv().await.ok() {
    let record_id: String = serde_json::from_slice(msg.payload().unwrap())?;
    // .spawn() is non-blocking. record_id acts as the durable promise id.
    let _: ResonateHandle<()> = resonate
        .run(&record_id, "workflow", (record_id.clone(), msg.offset()))
        .target("poll://any@workers")
        .spawn()
        .await?;
}
```





`beginRun` / `resonate.run(...)` / `.spawn()` is non-blocking — the consumer keeps polling while the workflow runs in the background. The same `recordId` deduplicates retries by design.

## Run it locally

Both repos ship a `docker-compose.yml` for Redpanda (Redpanda boots faster than Apache Kafka locally; the worker code is identical for both).





```shell
git clone https://github.com/resonatehq-examples/example-kafka-worker-ts
cd example-kafka-worker-ts
bun install
```

```shell title="Terminal 1 — the broker"
docker compose up
```

```shell title="Terminal 2 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 3 — the worker"
bun run consumer
```

```shell title="Terminal 4 — produce records"
bun run producer -- -n 10
```





Clone the repo (uses [uv](https://docs.astral.sh/uv/)):

```shell
git clone https://github.com/resonatehq-examples/example-kafka-worker-py
cd example-kafka-worker-py
uv sync
```

```shell title="Terminal 1 — the broker"
cd redpanda && docker compose up
```

```shell title="Terminal 2 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 3 — the worker"
uv run python -m record_deletor.delete
```

```shell title="Terminal 4 — produce records"
uv run python -m record_producer.produce -n 10
```





```shell
git clone https://github.com/resonatehq-examples/example-kafka-worker-rs
cd example-kafka-worker-rs
cargo build
```

```shell title="Terminal 1 — the broker"
docker compose up
```

```shell title="Terminal 2 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 3 — the worker"
cargo run --bin consumer
```

```shell title="Terminal 4 — produce records"
cargo run --bin producer -- -n 10
```

(`rdkafka` requires `cmake` at build time — install via `brew install cmake` if missing.)





Watch the worker terminal — it consumes each message, runs the durable workflow, and re-emits a completion event when each finishes.

## Try the recovery story

While the worker is processing a batch, kill it. Restart it. Resonate replays the workflow from the last unfinished step — already-deleted batches are not redone, the loop continues, the completion event still fires exactly once.

## Related

- [Load balancing](/get-started/examples/load-balancing) — same dispatch pattern across multiple worker instances.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — the same workflow-per-input shape, sourced from HTTP rather than Kafka.

---

---
url: https://docs.resonatehq.io/get-started/examples/load-balancing
title: Load balancing
---

<img src="/images/example-load-balancing-dark.png" alt="Load Balancing banner" className="hidden dark:block" />
<img src="/images/example-load-balancing-light.png" alt="Load Balancing banner" className="block dark:hidden" />

Run several workers in the same group. Calls to `target: "poll://any@<group>"` get dispatched to whichever worker claims them first. When a worker dies mid-execution, Resonate reassigns the work to a survivor — no service registry, no leader election, no glue.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development. Go: `0.1.0` is tagged, but the tag lacks the `v` prefix Go's module resolver requires, so the example pins a `main` commit instead (see [Go SDK](/develop/go)).



  
  
  
  


## The problem

A single worker eventually runs out of capacity, and a single worker is also a single point of failure. The textbook fix is to run several — but that opens its own can: which worker has spare capacity, how does the caller find one, what happens when the chosen worker dies mid-job, who takes the work over?

Most teams end up bolting service discovery, load balancing, and recovery onto application code in three different places, each with its own bugs.

## Resonate's solution

Resonate ships service discovery, load balancing, and crash recovery behind one primitive: the `target` schema. Workers in the same group long-poll the server; the caller dispatches with `target: "poll://any@<group>"` and the server hands the work to whichever worker is ready. If that worker dies before completing, the workflow's durable promise stays open and another worker in the group picks it up.

## Code walkthrough

Two pieces: a **worker** that registers a durable function and joins a group, and a **client** that dispatches work to that group.

### The worker group

Each worker process is identical except for the `group` it joins. Run as many as you want — they share work automatically.





```typescript title="worker.ts"
import { Resonate } from "@resonatehq/sdk";
import type { Context } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "workers",
});

function computeSomething(ctx: Context, args: { id: string; computeCost: number }) {
  console.log(`${args.id} starting computation`);
  setTimeout(() => {
    console.log(`${args.id} computed something that cost ${args.computeCost} seconds`);
  }, args.computeCost * 1000);
}

resonate.register("computeSomething", computeSomething);
console.log("worker is running...");
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os
from datetime import timedelta
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="worker-group")


async def compute_something(ctx: Context, id: str, compute_cost: int) -> None:
    print(f"starting computation {id}")
    await ctx.sleep(timedelta(seconds=compute_cost))
    print(f"computed something that cost {compute_cost} seconds")


resonate.register(compute_something)


async def main() -> None:
    print("worker running...")
    # Keep the worker alive to receive invocations.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/worker.rs"
use resonate::prelude::*;
use std::time::Duration;

#[resonate::function]
async fn compute_something(ctx: &Context, id: String, compute_cost: u64) -> Result<()> {
    println!("{id} starting computation");
    ctx.sleep(Duration::from_secs(compute_cost)).await?;
    println!("{id} computed something that cost {compute_cost} seconds");
    Ok(())
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        group: Some("workers".into()),
        ..Default::default()
    });
    resonate.register(compute_something).unwrap();
    println!("worker is running...");
    tokio::signal::ctrl_c().await.unwrap();
}
```





```go title="main.go"
// WorkArgs carries the task identifier sent from client to worker.
type WorkArgs struct {
	TaskName string `json:"taskName"`
}

// computeSomething simulates a unit of work. It records which worker
// handled the task so the client can print the distribution.
func computeSomething(workerID string) func(_ *resonate.Context, args WorkArgs) (string, error) {
	return func(_ *resonate.Context, args WorkArgs) (string, error) {
		// Simulate a small amount of work.
		time.Sleep(50 * time.Millisecond)
		result := fmt.Sprintf("worker-%s handled %s", workerID, args.TaskName)
		fmt.Printf("[worker-%s] handling %s → done\n", workerID, args.TaskName)
		return result, nil
	}
}
```

Each worker instance is created with `httpnet.NewHTTP(url, httpnet.HTTPOptions{Group: ...})` and registers `computeSomething` under that shared group. The example spins several up inside one process — in production each would be its own process:

```go title="main.go"
		r, err := resonate.New(resonate.Config{
			Network: httpnet.NewHTTP(*url, httpnet.HTTPOptions{
				PID:   pid,
				Group: *group,
			}),
		})
		if err != nil {
			log.Fatalf("resonate.New (worker-%s): %v", workerID, err)
		}
		workerInstances[i] = r

		// Register the compute function with a closure that captures the worker ID.
		if _, err := resonate.Register(r, "computeSomething", computeSomething(workerID)); err != nil {
			log.Fatalf("Register (worker-%s): %v", workerID, err)
		}
```





### Dispatching to the group

The caller picks a target with the `poll://any@<group>` schema. `any` means "whichever worker in the group claims it first."





```typescript title="client.ts"
import { Resonate } from "@resonatehq/sdk";
import { v4 as uuid } from "uuid";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "client",
});

const id = uuid();
const computeCost = Math.floor(Math.random() * 10) + 1;
await resonate.beginRpc(
  id,
  "computeSomething",
  { id, computeCost },
  resonate.options({ target: "poll://any@workers" }),
);
await resonate.stop();
```





```python title="invoke.py"
from __future__ import annotations

import asyncio
import os
from random import randint
from uuid import uuid4

from resonate.resonate import Resonate


async def main() -> None:
    url = os.environ.get("RESONATE_URL", "http://localhost:8001")
    resonate = Resonate(url=url, group="invoke-group")
    try:
        promise_id = str(uuid4())
        compute_cost = randint(1, 10)
        handle = resonate.options(target="poll://any@worker-group").rpc(
            promise_id, "compute_something", promise_id, compute_cost,
        )
        await handle.result()
    finally:
        await resonate.stop()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/client.rs"
use rand::Rng;
use resonate::prelude::*;
use uuid::Uuid;

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });
    let id = Uuid::new_v4().to_string();
    let cost: u64 = rand::thread_rng().gen_range(1..=10);

    let _: () = resonate
        .rpc(&id, "compute_something", (id.clone(), cost))
        .target("poll://any@workers")
        .spawn()
        .await
        .unwrap();
    resonate.stop().await;
}
```





A separate client instance dispatches each task with `client.RPC` and a `poll://any@<group>` target — the server hands each task to whichever worker in the group claims it first. Both blocks below are excerpts from `main()`, where `*url`, `*group`, and `ctx` come from the parsed flags and request context:

```go title="main.go"
	clientPID := fmt.Sprintf("client-%d", time.Now().UnixNano())
	client, err := resonate.New(resonate.Config{
		Network: httpnet.NewHTTP(*url, httpnet.HTTPOptions{
			PID:   clientPID,
			Group: "client",
		}),
	})
	if err != nil {
		log.Fatalf("resonate.New (client): %v", err)
	}
	defer func() { _ = client.Stop() }()

	// Build the anycast target address for the worker group.
	target := fmt.Sprintf("poll://any@%s", *group)
```

```go title="main.go"
		id := fmt.Sprintf("%s-%s", runID, taskName)
		h, err := client.RPC(ctx, id, "computeSomething", WorkArgs{TaskName: taskName},
			resonate.RPCOptions{Target: target},
		)
```





## Run it locally

Start the server, run several workers, then dispatch repeatedly from the client.





```shell
git clone https://github.com/resonatehq-examples/example-load-balancing-ts
cd example-load-balancing-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
npx tsx worker.ts
```

```shell title="Terminal 5 — dispatch in a loop"
for i in 1 2 3 4 5 6; do npx tsx client.ts; done
```

Watch the work spread across the three worker terminals. Now kill one of them mid-execution — Resonate reassigns its in-flight workflow to a survivor.





```shell
git clone https://github.com/resonatehq-examples/example-load-balancing-py
cd example-load-balancing-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
uv run python worker.py
```

```shell title="Terminal 5 — dispatch in a loop"
for i in 1 2 3 4 5 6; do uv run python invoke.py; done
```

Watch the work spread across the three worker terminals. Kill one of them mid-execution — Resonate reassigns its in-flight workflow to a survivor.





```shell
git clone https://github.com/resonatehq-examples/example-load-balancing-rs
cd example-load-balancing-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
cargo run --bin worker
```

```shell title="Terminal 5 — dispatch in a loop"
for i in 1 2 3 4 5 6; do cargo run --bin client; done
```





Unlike the other SDKs, the Go example runs the workers **and** the client in a single binary — there's no separate terminal per worker. `-workers` controls how many worker instances it spins up.

```shell
git clone https://github.com/resonatehq-examples/example-load-balancing-go
cd example-load-balancing-go
go mod download
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — workers + client (one process)"
go run . -url=http://localhost:8001 -workers=3 -tasks=6
```

The single process starts three worker instances and a client that dispatches six tasks across the group; the `[worker-N]` log lines show the work spreading. Increase `-workers` and `-tasks` to watch the distribution change. Because the workers share this one process, the kill-a-single-worker recovery story below is the one shown by the separate-process TypeScript, Python, and Rust examples.





## Try the recovery story

Start three workers and dispatch enough jobs to keep all of them busy. Kill the worker holding a long-running job. The Resonate Server detects the loss, reassigns the workflow's durable promise to one of the survivors, and the work continues. The client never sees an error — it just gets a slightly delayed result.

The TypeScript, Python, and Rust examples run each worker as its own process, so you can `Ctrl-C` a single one to watch this happen. The Go example runs its workers inside one process, so it demonstrates the distribution but not single-worker recovery — [recursive factorial](/get-started/examples/recursive-factorial) shows the Go crash-recovery story with a separate worker process.

## Related

- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — same group dispatch, with a workflow that suspends on a durable promise.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — long-running HTTP work without holding the connection.

---

---
url: https://docs.resonatehq.io/get-started/examples/money-transfer
title: Money transfer
---

<img src="/images/example-money-transfer-dark.png" alt="Money Transfer banner" className="hidden dark:block" />
<img src="/images/example-money-transfer-light.png" alt="Money Transfer banner" className="block dark:hidden" />

A workflow debits the source account, credits the target account, and returns confirmations. Each account update is a durable checkpoint, the transfer ID is the idempotency key, and the same ID retried in seconds, hours, or days returns the cached result instead of double-spending.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Moving money between accounts is the textbook saga: you have to debit one account and credit another, but the operations live in different rows (or different databases) and have to either both happen or neither. A crash between the debit and the credit creates lost money. A retry that re-fires the debit creates duplicate money. Compensating transactions and idempotency keys are the conventional fix, and getting both right is famously hard.

## Resonate's solution

Each account update is a checkpoint. If the worker dies after the debit but before the credit, restart resumes at the credit — the debit is not re-issued. The transfer ID is the workflow ID; calling the endpoint a second time with the same ID returns the cached result rather than running the workflow again. The "saga" is just two `ctx.run` calls in sequence, with the durability story handled by Resonate.

## Code walkthrough

The workflow calls `updateAccount` (TypeScript) or `apply_entry` (Python) twice — once with a negative amount (debit) and once with a positive (credit). Each call is its own durable checkpoint. The Python repo also wires up a compensating debit-reversal in the failure path.





```typescript title="src/workflow.ts"
export function* transferMoney(
  ctx: Context,
  transferId: string,
  request: TransferRequest,
): Generator<any, TransferResult, any> {
  const { source, target, amount } = request;
  const db = ctx.getDependency("db");

  try {
    // Step 1 — debit source. Checkpointed.
    const sourceConfirmation = yield* ctx.run(
      updateAccount, db, `${transferId}-source`, source, -amount,
    );

    // Step 2 — credit target. Checkpointed.
    const targetConfirmation = yield* ctx.run(
      updateAccount, db, `${transferId}-target`, target, amount,
    );

    return { success: true, transferId, source, target, amount,
             sourceConfirmation, targetConfirmation };
  } catch (error) {
    // Compensation logic for the debit goes here when needed.
    return { success: false, transferId, source, target, amount,
             error: String(error) };
  }
}
```

The HTTP entrypoint passes a path-param `id` straight through to `transferMoney`:

```typescript title="src/index.ts"
app.post("/transfer/:id", async (req, res) => {
  const { id } = req.params;
  const { source, target, amount } = req.body;

  // Same `id` returns the same result — calling /transfer/abc twice
  // does not double-debit.
  const result = await transferMoneyR.run(id, id, { source, target, amount });
  res.json(result);
});
```





```python title="main.py"
from __future__ import annotations

import asyncio
import os
import time
from typing import TYPE_CHECKING

from resonate.resonate import Resonate
from resonate.retry import Never

if TYPE_CHECKING:
    from resonate.context import Context


async def transfer_money(
    ctx: Context,
    transfer_id: str,
    source: str,
    target: str,
    amount: float,
    *,
    simulate_credit_failure: bool = False,
):
    debit_id = f"{transfer_id}-debit"
    credit_id = f"{transfer_id}-credit"
    reversal_id = f"{transfer_id}-reversal"

    # Step 1 — debit the source (durable checkpoint).
    await ctx.run(apply_entry, debit_id, source, -amount, "debit")

    # Step 2 — credit the target. On failure, compensate by reversing
    # the debit. Never() retry policy lets the saga's compensation be
    # the response to a credit-side failure.
    try:
        await ctx.options(retry_policy=Never()).run(
            credit_target, credit_id, target, amount,
            fail=simulate_credit_failure,
        )
    except Exception as err:
        await ctx.run(apply_entry, reversal_id, source, amount, "reversal")
        return {"transfer_id": transfer_id, "status": "compensated", "error": str(err)}

    return {"transfer_id": transfer_id, "status": "committed",
            "source": source, "target": target, "amount": amount}
```

The deterministic `op_id` (`{transfer_id}-debit`, `-credit`, `-reversal`) plus an `INSERT OR IGNORE` in `apply_entry` makes each step idempotent — replaying the workflow after a crash is a no-op for completed steps.





```rust title="src/main.rs"
#[resonate::function]
async fn transfer_money(
    ctx: &Context, transfer_id: String, source: String, target: String,
    amount: f64, simulate_credit_failure: bool,
) -> Result<TransferResult> {
    let debit_id = format!("{transfer_id}-debit");
    let credit_id = format!("{transfer_id}-credit");
    let reversal_id = format!("{transfer_id}-reversal");

    // Step 1 — debit (durable checkpoint).
    ctx.run(apply_entry, (debit_id, source.clone(), -amount, "debit".into())).await?;

    // Step 2 — credit. On Err, compensate.
    match ctx
        .run(credit_target, (credit_id, target, amount, simulate_credit_failure))
        .await
    {
        Ok(_) => Ok(TransferResult::committed(transfer_id, source, /*...*/)),
        Err(_) => {
            ctx.run(apply_entry, (reversal_id, source, amount, "reversal".into())).await?;
            Ok(TransferResult::compensated(transfer_id))
        }
    }
}
```

The Rust example uses `Resonate.local()` (embedded mode, no server required) plus `with_dependency::<Mutex<Connection>>(...)` to inject the SQLite handle. `ctx.run(...).await` returns a `Result`, so saga compensation is just an `if let Err`.





`ctx.getDependency('db')` / `ctx.get_dependency(DB)` / `info.get_dependency::<T>()` (Rust) lets the step functions see the database without exposing it as a workflow argument — important, because workflow arguments must be serializable, and a DB handle is not.

## Run it locally





```shell
git clone https://github.com/resonatehq-examples/example-money-transfer-application-ts
cd example-money-transfer-application-ts
npm install
cp .env.example .env
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — server"
npm start
```

Initiate a transfer:

```shell
curl -X POST http://localhost:3000/transfer/transfer-001 \
  -H "Content-Type: application/json" \
  -d '{"source": "alice", "target": "bob", "amount": 50}'
```

Call `/transfer/transfer-001` again — the response is the same cached result; balances don't change.





```shell
git clone https://github.com/resonatehq-examples/example-money-transfer-py
cd example-money-transfer-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — run the demo"
uv run python main.py
```

The script seeds Alice with $200, runs a happy-path transfer (`alice -> bob $50`), then runs a failed transfer (`alice -> bob $75`) that triggers the compensating reversal. Final balances: `alice=150, bob=50`.





```shell
git clone https://github.com/resonatehq-examples/example-money-transfer-rs
cd example-money-transfer-rs
cargo build
```

The Rust repo runs in embedded mode (`Resonate::local()`) — no separate Resonate Server is needed for the demo.

```shell
cargo run
```

Same demo shape: seeds Alice with $200, runs a happy-path transfer, then a forced-failure transfer that compensates. Final balances: `alice=150, bob=50`.





## Try the recovery story

Modify `updateAccount` to throw on the second call (the credit). Run the workflow — the debit checkpoints, the credit fails. Fix the code, restart the server. The workflow resumes at the credit step; the debit is not re-issued. This is the recovery story sagas are usually written by hand to provide.

## Related

- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — the same idempotency-via-workflow-ID primitive, exposed over HTTP polling.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — adds external resolution to the saga shape.

---

---
url: https://docs.resonatehq.io/get-started/examples/multi-agent-orchestration
title: Multi-agent orchestration
---

<img src="/images/example-multi-agent-orchestration-dark.png" alt="Multi-agent Orchestration banner" className="hidden dark:block" />
<img src="/images/example-multi-agent-orchestration-light.png" alt="Multi-agent Orchestration banner" className="block dark:hidden" />

Three specialist agents — researcher, writer, reviewer — chained through an orchestrator. Each agent's output is a durable checkpoint, so a flaky LLM call mid-pipeline retries only the failing agent and the prior outputs stay cached.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust example repo is forthcoming.



  
  


## The problem

Multi-agent pipelines look elegant on a whiteboard and brittle in production. Each LLM call is a roll of the dice — rate limits, transient errors, model regressions. If the third agent fails, naive implementations re-run the whole pipeline, paying for the first two LLM calls again. Add a human-approval step and the pipeline now needs to hold state across hours or days, which is its own coordination problem.

## Resonate's solution

Each agent invocation is a `ctx.run` call. The orchestrator function chains them in sequence; Resonate checkpoints every output. If the writer fails, only the writer retries — the researcher's findings are reused from the durable promise. Add a `ctx.promise()` between the reviewer and the publish step and you get human-in-the-loop suspension that survives process restarts.

## Code walkthrough

The orchestrator is one generator function that calls three plain agent functions through `ctx.run`. The agents themselves are unremarkable — what matters is that Resonate sits between them.





```typescript title="src/workflow.ts"
import type { Context } from "@resonatehq/sdk";
import { researcher, writer, reviewer } from "./agents";

export function* orchestrate(
  ctx: Context,
  topic: string,
  crashOnWriter: boolean,
): Generator<any, OrchestrationResult, any> {
  // 1. Researcher gathers findings on the topic.
  const findings = yield* ctx.run(researcher, topic);

  // 2. Writer produces a draft from those findings. Checkpointed —
  //    if the writer crashes, the researcher's findings are NOT re-run.
  const draft = yield* ctx.run(writer, topic, findings, crashOnWriter);

  // 3. Reviewer checks the draft quality.
  const review = yield* ctx.run(reviewer, draft);

  const approved = review.toUpperCase().includes("APPROVED");
  return {
    status: approved ? "published" : "rejected",
    topic, findings, draft, review,
  };
}
```





```python title="src/agent.py"
from __future__ import annotations

import asyncio
import os
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url)


async def orchestrate(ctx: Context, topic: str, crash_on_writer: bool = False):
    # 1. Researcher gathers findings on the topic.
    findings = await ctx.run(researcher, topic)

    # 2. Writer produces a draft from those findings. Checkpointed —
    #    if the writer crashes, the researcher's findings are NOT re-run.
    draft = await ctx.run(writer, topic, findings, crash_on_writer)

    # 3. Reviewer checks the draft quality.
    review = await ctx.run(reviewer, draft)

    approved = "APPROVED" in review.upper()
    return {
        "status": "published" if approved else "rejected",
        "topic": topic, "findings": findings, "draft": draft, "review": review,
    }


resonate.register(orchestrate)
```

The OpenAI client is injected into the workflow via `r.with_dependency(OpenAI(...))` and accessed inside each agent with `ctx.get_dependency(OpenAI)` — keeps the agent functions free of global imports and easy to test.





The `crash` argument is a demo lever — set it to `true` and the writer throws on its first attempt. Watch the logs: the researcher runs once, the writer retries until it succeeds, the reviewer runs once. Without checkpoints, the researcher would re-run on every writer retry.

To extend the pipeline with human approval, replace the inline `approved` calculation with a durable promise:





```typescript
// Suspend until an external system (HTTP handler, CLI, button click)
// resolves the promise. ctx.promise() creates a child promise whose ID
// is `${ctx.id}.<seq>` — deterministic from the orchestrator's execution ID.
const approvalPromise = yield* ctx.promise<boolean>();
const approved = yield* approvalPromise;
```





```python
# Suspend until an external system resolves the promise.
approval = ctx.promise()
approval_id = await approval.id()
# ... surface approval_id externally (email, log, webhook) ...
approved = await approval
```





That promise survives process restarts — the orchestrator can be killed and the workflow waits in the server's promise store until a human responds.

## Run it locally





```shell
git clone https://github.com/resonatehq-examples/example-multi-agent-orchestration-ts
cd example-multi-agent-orchestration-ts
bun install
```

Run the happy path:

```shell
bun run src/index.ts
```

Run with the writer crash flag — the researcher runs once, the writer retries:

```shell
bun run src/index.ts -- --crash
```





Set up the repo and your OpenAI key:

```shell
git clone https://github.com/resonatehq-examples/example-multi-agent-orchestration-py
cd example-multi-agent-orchestration-py
uv sync
cp .env.example .env  # add your OPENAI_API_KEY
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — worker"
uv run python -m src.agent
```

```shell title="Terminal 3 — invoke"
resonate invoke orchestration.1 \
  --func orchestrate \
  --arg '"The future of durable execution in AI applications"' \
  --arg false
```

Set the second `--arg` to `true` to trigger the writer-crash demo. The researcher's "Researching" log only appears once across the retry sequence.





Watch the logs across the retry sequence — the researcher's "gathering findings" message only appears once.

## Try the human-in-the-loop extension

Swap the inline `approved` check for `ctx.promise()` and add a small HTTP server (or use the Resonate CLI) to resolve the promise. Now the orchestrator suspends after the reviewer step until a human decides whether to publish — for hours, days, or weeks. Worker crashes during the suspension don't lose progress; restart and the workflow is still waiting for the same promise.

## Related

- [Deep research agent](/get-started/examples/deep-research-agent) — recursive agent dispatch with parallel subagents.
- [Human-in-the-loop](/get-started/examples/human-in-the-loop) — the suspension primitive in detail.

---

---
url: https://docs.resonatehq.io/get-started/examples/recursive-factorial
title: Recursive factorial
---

<img src="/images/example-recursive-factorial-dark.png" alt="Recursive Factorial banner" className="hidden dark:block" />
<img src="/images/example-recursive-factorial-light.png" alt="Recursive Factorial banner" className="block dark:hidden" />

A workflow that computes `n!` by calling itself with `n-1`. Each recursive call dispatches via `ctx.rpc` to whichever worker in the group claims it — recursion ends up distributed across machines without any explicit coordination, and every step is checkpointed so a worker crash mid-recursion resumes cleanly.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development. Go: `0.1.0` is tagged, but the tag lacks the `v` prefix Go's module resolver requires, so the example pins a `main` commit instead (see [Go SDK](/develop/go)).



  
  
  
  


## The problem

Naive recursion runs in a single process. If the recursion is deep, you blow the stack. If the recursion is heavy (each call does real work), you can't parallelize across machines without writing your own dispatch layer. Add crashes to the picture and you also need to remember which branches finished and which need to retry.

## Resonate's solution

Use `ctx.rpc` instead of a direct function call. The recursive call goes to the Resonate Server, which dispatches it to whichever worker in the target group is available — so a deep recursion fans out across N workers automatically. Each call's result is a durable promise, so a worker crash mid-recursion just hands the unfinished call to a survivor.

## Code walkthrough

The pattern is one self-recursive function plus a client that kicks it off.

### The recursive workflow





```typescript title="factorialWorker.ts"
import { Resonate, type Context } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "factorial-workers",
});

function* factorial(ctx: Context, n: number): Generator<any, number, any> {
  if (n <= 1) return 1;

  // ctx.rpc dispatches to any worker in the group — this includes the worker
  // running this very call, but might also be a different machine.
  const result = yield* ctx.rpc(
    "factorial",
    n - 1,
    ctx.options({ target: "poll://any@factorial-workers" }),
  );
  return n * result;
}

resonate.register("factorial", factorial);
```





```python title="factorial_worker.py"
from __future__ import annotations

import asyncio
import os
from typing import TYPE_CHECKING

from resonate.resonate import Resonate

if TYPE_CHECKING:
    from resonate.context import Context

url = os.environ.get("RESONATE_URL", "http://localhost:8001")
resonate = Resonate(url=url, group="factorial-worker")


async def factorial(ctx: Context, n: int) -> int:
    if n <= 1:
        return 1
    # ctx.options(...).rpc dispatches to any worker in the group.
    result = await ctx.options(target="poll://any@factorial-worker").rpc(
        "factorial", n - 1,
    )
    return n * result


resonate.register(factorial)


async def main() -> None:
    print("Factorial worker is running...")
    # Keep the worker alive to receive invocations.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/worker.rs"
use resonate::prelude::*;

#[resonate::function]
async fn factorial(ctx: &Context, n: u64) -> Result<u64> {
    if n <= 1 {
        return Ok(1);
    }
    // ctx.rpc dispatches to any worker in the group.
    let result: u64 = ctx
        .rpc("factorial", n - 1)
        .target("poll://any@factorial-workers")
        .await?;
    Ok(n * result)
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        group: Some("factorial-workers".into()),
        ..Default::default()
    });
    resonate.register(factorial).unwrap();
    tokio::signal::ctrl_c().await.unwrap();
}
```





```go title="factorial/factorial.go"
const Name = "Factorial"

// WorkerGroup is the dispatch group the worker(s) join and the client targets
// when calling RPC. Using a non-default group keeps clients out of the
// task-dispatch pool — only processes that actually have Factorial registered
// will be asked to execute it.
const WorkerGroup = "factorial-workers"

// Args is the workflow input.
type Args struct {
	N int `json:"n"`
}

// Workflow computes n! by recursively dispatching factorial(n-1) via ctx.RPC.
// Each recursive call is a durable promise on the server; with multiple
// workers running, the recursion fans out across them.
func Workflow(ctx *resonate.Context, args Args) (int, error) {
	if args.N <= 1 {
		return 1, nil
	}
	f, err := ctx.RPC(Name, Args{N: args.N - 1})
	if err != nil {
		return 0, err
	}
	var sub int
	if err := f.Await(&sub); err != nil {
		return 0, err
	}
	return args.N * sub, nil
}
```

The worker binary joins the group and registers the workflow:

```go title="cmd/worker/main.go"
	pid := fmt.Sprintf("factorial-worker-%d", os.Getpid())
	r, err := resonate.New(resonate.Config{
		Network: httpnet.NewHTTP(*url, httpnet.HTTPOptions{
			PID:   pid,
			Group: factorial.WorkerGroup,
		}),
	})
	if err != nil {
		log.Fatalf("resonate.New: %v", err)
	}
	defer func() { _ = r.Stop() }()

	if _, err := resonate.Register(r, factorial.Name, factorial.Workflow); err != nil {
		log.Fatalf("Register: %v", err)
	}
```

The recursive `ctx.RPC(Name, …)` call takes no explicit target — inside a workflow the Go SDK resolves the dispatch group from the worker that's running it (`factorial-workers`), so the recursion stays within the group automatically.





### Kicking it off

The client looks identical to any other RPC call — Resonate doesn't care that the workflow happens to recurse internally.





```typescript title="factorialClient.ts"
import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
  url: "http://localhost:8001",
  group: "factorial-client",
});

const n = Number(process.argv[2] ?? 5);
const result = await resonate.rpc(
  `factorial-${n}`,
  "factorial",
  n,
  resonate.options({ target: "poll://any@factorial-workers" }),
);
console.log(`Factorial of ${n} is ${result}`);
await resonate.stop();
```





```python title="factorial_client.py"
from __future__ import annotations

import asyncio
import os
from argparse import ArgumentParser

from resonate.resonate import Resonate


async def main() -> None:
    parser = ArgumentParser()
    parser.add_argument("n", type=int)
    args = parser.parse_args()

    url = os.environ.get("RESONATE_URL", "http://localhost:8001")
    resonate = Resonate(url=url, group="factorial-client")
    try:
        handle = resonate.options(target="poll://any@factorial-worker").rpc(
            f"factorial-{args.n}", "factorial", args.n,
        )
        result = await handle.result()
        print(f"Result: {result}")
    finally:
        await resonate.stop()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/client.rs"
use resonate::prelude::*;

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });
    let n: u64 = std::env::args().nth(1).and_then(|s| s.parse().ok()).unwrap_or(5);
    let result: u64 = resonate
        .rpc(&format!("factorial-{n}"), "factorial", n)
        .target("poll://any@factorial-workers")
        .await
        .unwrap();
    println!("Factorial of {n} is {result}");
}
```





```go title="cmd/client/main.go"
	id := fmt.Sprintf("factorial-%d", *n)
	target := fmt.Sprintf("poll://any@%s", factorial.WorkerGroup)

	h, err := r.RPC(ctx, id, factorial.Name, factorial.Args{N: *n},
		resonate.RPCOptions{Target: target})
	if err != nil {
		log.Fatalf("RPC: %v", err)
	}

	var result int
	if err := h.Result(ctx, &result); err != nil {
		log.Fatalf("Result: %v", err)
	}
	fmt.Printf("factorial(%d) = %d\n", *n, result)
```

This is an excerpt from `main()`, where `r` is a `*resonate.Resonate` constructed (like the worker's) with `httpnet.NewHTTP`, but joining a `factorial-client` group. The client targets `poll://any@factorial-workers` and decodes the result into an `int`. The stable `factorial-<n>` promise ID makes a second run with the same `-n` return the cached result instantly.





## Run it locally

Start the server, run a few workers, then dispatch from the client.





```shell
git clone https://github.com/resonatehq-examples/example-recursive-factorial-ts
cd example-recursive-factorial-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
npx tsx factorialWorker.ts
```

```shell title="Terminal 5 — client"
npx tsx factorialClient.ts 10
```

Watch the three worker terminals — `factorial(10)`, `factorial(9)`, `factorial(8)` … fan out across the workers as recursion descends.





```shell
git clone https://github.com/resonatehq-examples/example-recursive-factorial-py
cd example-recursive-factorial-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
uv run python factorial_worker.py
```

```shell title="Terminal 5 — client"
uv run python factorial_client.py 10
```

Watch the three worker terminals — `factorial(10)`, `factorial(9)`, `factorial(8)` … fan out across the workers as recursion descends.





```shell
git clone https://github.com/resonatehq-examples/example-recursive-factorial-rs
cd example-recursive-factorial-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2–4 — three workers"
cargo run --bin worker
```

```shell title="Terminal 5 — client"
cargo run --bin client -- 10
```





```shell
git clone https://github.com/resonatehq-examples/example-recursive-factorial-go
cd example-recursive-factorial-go
go mod download
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminals 2+ — one or more workers"
go run ./cmd/worker
```

```shell title="Terminal 3 — client"
go run ./cmd/client -n 6
```

Run several workers and watch `factorial(6)`, `factorial(5)`, `factorial(4)` … fan out across them as the recursion descends.





## Try the recovery story

While the recursion is in flight (start with `n=20` to give it some depth), kill one of the workers. Resonate reassigns its in-flight `factorial(k)` to a survivor. Already-completed sub-results stay completed; only the unfinished branch resumes. The final answer is unchanged.

## Related

- [Hello world](/get-started/examples/hello-world) — the same primitives without the recursion.
- [Load balancing](/get-started/examples/load-balancing) — focused on the dispatch layer that makes the fan-out work.

---

---
url: https://docs.resonatehq.io/get-started/examples/schedule
title: Schedule
---

<img src="/images/example-schedule-dark.png" alt="Schedule banner" className="hidden dark:block" />
<img src="/images/example-schedule-light.png" alt="Schedule banner" className="block dark:hidden" />

Register a function to run on a cron expression and Resonate handles the rest. Every fired execution is a durable workflow — a worker that crashes mid-run hands off to a survivor, and a missed run because all workers were down still gets dispatched when one comes back.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust: 0.6.0, in active development.



  
  
  


## The problem

Cron is fine for "fire a script at a time," but stops there. If the script needs to retry, recover from a crash, dedup against double-fires, or coordinate across multiple machines, you end up wrapping cron in increasingly elaborate scaffolding — usually a queue, a separate worker, and a state table to track which runs completed.

## Resonate's solution

Tell the Resonate Server "run this function on this cron schedule." It dispatches each run as a durable workflow to whichever worker in the group claims it. The worker doesn't care about the schedule — it just runs the function, checkpoints each step, and recovers automatically if anything fails. Schedules persist across server restarts.

## Code walkthrough

Two scripts: a one-shot **schedule registration** that tells the server about the cron expression, and a **worker** that executes whatever the schedule fires.

### Register the schedule





```typescript title="src/schedule.ts"
import { Resonate } from "@resonatehq/sdk";
import { generateReport } from "./report";

const resonate = new Resonate({ url: "http://localhost:8001" });
resonate.register("generateReport", generateReport);

await resonate.schedule(
  "daily_report",   // schedule ID — re-running this script is a no-op once it exists
  "* * * * *",      // cron: every minute (use "0 9 * * *" for daily 9am)
  generateReport,
  123,              // userId argument
);
console.log("Schedule created. Start the worker to process executions.");
await resonate.stop();
```





```python title="schedule.py"
from __future__ import annotations

import asyncio
import os

from resonate.resonate import Resonate
from report import generate_report


async def main() -> None:
    resonate = Resonate(url=os.environ.get("RESONATE_URL", "http://localhost:8001"))
    resonate.register(generate_report)

    # Yield to the event loop once so the SDK's background network task
    # starts before the first call -- needed on resonate-sdk 0.7.x until
    # resonatehq/resonate-sdk-py#443 is fixed.
    await asyncio.sleep(0)

    try:
        # Schedule generate_report to run every minute.
        # Re-running this script is a no-op once the schedule exists.
        await resonate.schedule(
            id="daily_report",
            cron="* * * * *",          # every minute (change to "0 9 * * *" for daily at 9am UTC)
            func_name="generate_report",
            args=(123,),               # user_id
        )
        print("Schedule registered. Start the worker to process executions.")
    finally:
        await resonate.stop()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/schedule.rs"
use example_schedule_rs::generate_report;
use resonate::prelude::*;

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });

    resonate
        .schedule("daily_report", "* * * * *", "generate_report", 123u64)
        .await
        .expect("schedule create failed");

    println!("Schedule created. Start the worker to process executions.");
}
```





The schedule lives on the server, not in the worker. You can run the registration script once and the schedule keeps firing across worker restarts and redeploys. Re-running the script with the same ID is a no-op.

### Run the worker





```typescript title="src/worker.ts"
import { Resonate } from "@resonatehq/sdk";
import { generateReport } from "./report";

const resonate = new Resonate({ url: "http://localhost:8001" });
resonate.register("generateReport", generateReport);
console.log("Worker started. Waiting for scheduled executions...");
```





```python title="worker.py"
from __future__ import annotations

import asyncio
import os

from resonate.resonate import Resonate
from report import generate_report


async def main() -> None:
    url = os.environ.get("RESONATE_URL", "http://localhost:8001")
    resonate = Resonate(url=url)
    resonate.register(generate_report)
    print("Worker started. Waiting for scheduled executions...")
    # Keep running until interrupted.
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```





```rust title="src/bin/worker.rs"
use example_schedule_rs::generate_report;
use resonate::prelude::*;

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });
    resonate.register(generate_report).unwrap();
    println!("Worker started. Waiting for scheduled executions...");
    tokio::signal::ctrl_c().await.unwrap();
}
```





The worker is identical to any other Resonate worker — it doesn't know it's being driven by a schedule. The same function can be invoked by hand via `resonate invoke` or scheduled cron-style; both paths are durable executions.

## Run it locally





```shell
git clone https://github.com/resonatehq-examples/example-schedule-ts
cd example-schedule-ts
npm install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — register the schedule (one-shot)"
npx tsx src/schedule.ts
```

```shell title="Terminal 3 — worker"
npx tsx src/worker.ts
```

The worker prints a log line every minute as the schedule fires. Kill it for a few minutes and restart — runs that fired while it was down are dispatched as soon as it reconnects.





```shell
git clone https://github.com/resonatehq-examples/example-schedule-py
cd example-schedule-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — register the schedule (one-shot)"
uv run python schedule.py
```

```shell title="Terminal 3 — worker"
uv run python worker.py
```

The worker prints a log line every minute as the schedule fires. Kill it for a few minutes and restart — runs that fired while it was down are dispatched as soon as it reconnects.





```shell
git clone https://github.com/resonatehq-examples/example-schedule-rs
cd example-schedule-rs
cargo build
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — register the schedule (one-shot)"
cargo run --bin schedule
```

```shell title="Terminal 3 — worker"
cargo run --bin worker
```





## Try the catch-up story

Stop the worker for a few minutes. Schedule fires keep accumulating on the server. When you restart the worker, the queued runs dispatch in order — none are lost. Now bring up two workers in the same group and watch fires distribute across them.

## Related

- [Load balancing](/get-started/examples/load-balancing) — same group dispatch, focused on parallel work.
- [Durable sleep](/get-started/examples/durable-sleep) — the in-workflow analogue of cron, for delays inside a single execution.

---

---
url: https://docs.resonatehq.io/get-started/examples/webhook-handler
title: Webhook handler
---

<img src="/images/example-webhook-handler-dark.png" alt="Webhook Handler banner" className="hidden dark:block" />
<img src="/images/example-webhook-handler-light.png" alt="Webhook Handler banner" className="block dark:hidden" />

A webhook receives a payment event, kicks off a durable workflow keyed by the provider's event ID, and acknowledges immediately. Duplicate deliveries (network retries, slow ACKs) reconnect to the in-flight execution rather than re-charging the card. A crash mid-processing resumes from the next unfinished step.


TypeScript: `@resonatehq/sdk` v0.11.4 (current). Python: `resonate-sdk` v0.7.4 (current). Rust example repo is forthcoming.



  
  


## The problem

Webhook providers are built to retry — any timeout, slow ACK, or 5xx response triggers a redelivery. Your handler has to be idempotent, or duplicate deliveries double-charge the customer. The conventional fix is a "processed events" table you check before doing work, paired with a worker that polls a queue, paired with retry logic for partial failures. Three moving parts, and any one of them not being idempotent breaks the whole shape.

## Resonate's solution

The provider's event ID is the workflow ID. Resonate's promise dedup means a duplicate delivery with the same event ID reconnects to the in-flight (or completed) execution rather than starting a second one. The downstream steps — charge card, send receipt, update ledger — each checkpoint, so a crash between any two resumes from the next step rather than re-running the whole pipeline.

The handler ACKs the webhook in well under five seconds because it just dispatches the workflow and returns; the processing happens durably in the background.

## Code walkthrough

### The webhook endpoint

Receive, dispatch, ACK. The whole point is that the workflow runs in the background — Stripe (or any provider) gets its fast 200 OK regardless of how long the actual processing takes.





```typescript title="src/index.ts"
app.post("/webhook", (req, res) => {
  const event = req.body as WebhookEvent;

  // The event_id IS the workflow ID.
  // Stripe retries with the same event_id reconnect to the in-flight execution.
  resonate
    .run(`webhook/${event.event_id}`, processPayment, event, simulateCrash)
    .catch(console.error);

  // Fast ACK — Stripe needs a 200 within 5 seconds.
  res.status(200).json({ received: true });
});
```





```python title="main.py"
@app.post("/webhook")
async def webhook(event: WebhookEvent):
    # The event_id IS the workflow ID.
    # Stripe retries with the same event_id reconnect to the in-flight execution.
    resonate.run(f"webhook/{event['event_id']}", process_payment, event, simulate_crash)
    # Fast ACK — Stripe needs a 200 within 5 seconds.
    return {"received": True}
```





A separate `GET /status/:event_id` lets you poll the workflow's result if you need it.

### The exactly-once workflow

Every step is a `ctx.run` checkpoint. If the worker dies after `charge_card` but before `update_ledger`, restart resumes at `send_receipt` — the card is not charged again.





```typescript title="src/workflow.ts"
export function* processPayment(
  ctx: Context,
  event: WebhookEvent,
): Generator<any, PaymentResult, any> {
  // Validate signature and event structure.
  yield* ctx.run(validateEvent, event);

  // Charge the card. Checkpointed — duplicates skip this step.
  const chargeId = yield* ctx.run(chargeCard, event);

  // Send the receipt.
  yield* ctx.run(sendReceipt, event, chargeId);

  // Update the accounting ledger.
  return yield* ctx.run(updateLedger, event, chargeId);
}
```





```python title="workflow.py"
async def process_payment(ctx: Context, event: WebhookEvent, simulate_crash: bool):
    # Validate signature and event structure.
    await ctx.run(validate_event, event)

    # Charge the card. Checkpointed — duplicates skip this step.
    charge_id = await ctx.run(charge_card, event, simulate_crash)

    # Send the receipt.
    await ctx.run(send_receipt, event, charge_id)

    # Update the accounting ledger.
    return await ctx.run(update_ledger, event, charge_id)

resonate.register(process_payment)
```





Both repos include a `--crash` flag that simulates `charge_card` failing on the first attempt — re-running the workflow shows the charge happening exactly once even across retries.

## Run it locally





```shell
git clone https://github.com/resonatehq-examples/example-webhook-handler-ts
cd example-webhook-handler-ts
bun install
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — webhook server"
bun run src/index.ts
```





```shell
git clone https://github.com/resonatehq-examples/example-webhook-handler-py
cd example-webhook-handler-py
uv sync
```

```shell title="Terminal 1 — Resonate Server"
brew install resonatehq/tap/resonate
resonate dev
```

```shell title="Terminal 2 — webhook server"
uv run python main.py
```





Send a webhook:

```shell
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"event_id": "evt_001", "type": "payment.succeeded", "amount": 4999, "currency": "USD"}'
```

Send the same webhook again. Watch the logs — the second delivery doesn't re-charge.

## Try the crash story

Run with the crash flag — `chargeCard` / `charge_card` throws on its first attempt, the workflow retries, and the second attempt succeeds. The card is charged exactly once.





```shell
bun run src/index.ts -- --crash
```





```shell
uv run python main.py --crash
```





## Related

- [Money transfer](/get-started/examples/money-transfer) — same idempotency primitive, applied to a saga.
- [Async HTTP API endpoints](/get-started/examples/async-http-api-endpoints) — fire-and-forget HTTP with the same workflow-ID-as-dedup-key shape.

---

---
url: https://docs.resonatehq.io/get-started
title: Get started with Resonate
---

<img src="/images/banner-get-started-dark.png" alt="Get started with Resonate section" className="hidden dark:block" />
<img src="/images/banner-get-started-light.png" alt="Get started with Resonate section" className="block dark:hidden" />

**Durable execution means your functions survive crashes, restarts, and scaling — automatically.** Resonate handles retries, recovery, and state persistence so you can write normal async code.

Migrating from another platform? See the [coming from](/evaluate/coming-from/) guides.

---

---
url: https://docs.resonatehq.io/get-started/quickstart
title: Quickstart
---

<img src="/images/banner-quickstart-dark.png" alt="Resonate Quickstart banner" className="hidden dark:block" />
<img src="/images/banner-quickstart-light.png" alt="Resonate Quickstart banner" className="block dark:hidden" />

## Install the server

```shell
brew install resonatehq/tap/resonate
```

## Install the SDK





Requires **Node.js 22** or later.

```shell
npm install @resonatehq/sdk
```









```shell
pip install resonate-sdk
```





```toml title="Cargo.toml"
[dependencies]
resonate = { package = "resonate-sdk", version = "0.6" }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
```





Requires **Go 1.22** or later.

```shell
go mod init countdown
go get github.com/resonatehq/resonate-sdk-go@latest
```

The `0.1.0` git tag lacks the `v` prefix Go's module resolver requires, so `@latest` resolves to a pseudo-version pinned to the latest `main` commit instead. See the [Go SDK guide](/develop/go) for details.





Requires **Java 21** or later (the SDK uses virtual threads).

```kotlin title="build.gradle.kts"
dependencies {
    implementation("io.resonatehq:resonate-sdk-java:0.1.1")
}
```

The SDK is published on Maven Central; `0.1.1` is the latest release. The SDK is pre-release (v0.1.x) — expect API changes before `v1.0`. See the [Java SDK guide](/develop/java) for Maven coordinates and details.





## Write a function

A countdown loop that survives restarts — minutes, hours, or days.





```typescript title="countdown.ts"
import { Resonate, type Context } from "@resonatehq/sdk";

function* countdown(context: Context, count: number, delay: number) {
  for (let i = count; i > 0; i--) {
    // Run a function, persist its result
    yield* context.run((context: Context) => console.log(`Countdown: ${i}`));
    // Sleep
    yield* context.sleep(delay * 1000);
  }
  console.log("Done!");
}
// Instantiate Resonate
const resonate = new Resonate({ url: "http://localhost:8001" });
// Register the function
resonate.register(countdown);
```

[Working example](https://github.com/resonatehq-examples/example-quickstart-ts)





```python title="countdown.py"
import asyncio
from datetime import timedelta

from resonate.context import Context
from resonate.resonate import Resonate


async def countdown(ctx: Context, count: int, delay: int) -> None:
    for i in range(count, 0, -1):
        # Run a function, persist its result
        await ctx.run(ntfy, i)
        # Sleep
        await ctx.sleep(timedelta(seconds=delay))


async def ntfy(ctx: Context, i: int) -> None:
    print(f"Countdown: {i}")


async def main() -> None:
    # Instantiate Resonate
    resonate = Resonate(url="http://localhost:8001")
    # Register the functions
    resonate.register(countdown)
    resonate.register(ntfy)
    # Keep the worker alive to receive invocations
    await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```

[Working example](https://github.com/resonatehq-examples/example-quickstart-py)





```rust title="src/main.rs"
use resonate::prelude::*;
use std::time::Duration;

#[resonate::function]
async fn countdown(ctx: &Context, count: i32, delay: u64) -> Result<()> {
    for i in (1..=count).rev() {
        ctx.run(notify, i).await?;
        ctx.sleep(Duration::from_secs(delay)).await?;
    }
    println!("Done!");
    Ok(())
}

#[resonate::function]
async fn notify(i: i32) -> Result<()> {
    println!("Countdown: {i}");
    Ok(())
}

#[tokio::main]
async fn main() {
    let resonate = Resonate::new(ResonateConfig {
        url: Some("http://localhost:8001".into()),
        ..Default::default()
    });
    resonate.register(countdown).unwrap();
    resonate.register(notify).unwrap();
    // Keep the process alive to receive work
    tokio::signal::ctrl_c().await.unwrap();
}
```

[Working example](https://github.com/resonatehq-examples/example-hello-world-rs)





```go title="main.go"
package main

import (
	"fmt"
	"log"
	"os"
	"os/signal"
	"syscall"
	"time"

	resonate "github.com/resonatehq/resonate-sdk-go"
)

// CLI args arrive as a slice: `--arg 5 --arg 60` becomes args[0]=5, args[1]=60.
func countdown(ctx *resonate.Context, args []int) (struct{}, error) {
	count, delay := args[0], args[1]
	for i := count; i > 0; i-- {
		// Run a function, persist its result
		f, err := ctx.Run(notify, i)
		if err != nil {
			return struct{}{}, err
		}
		if err := f.Await(nil); err != nil {
			return struct{}{}, err
		}
		// Sleep
		s, err := ctx.Sleep(time.Duration(delay) * time.Second)
		if err != nil {
			return struct{}{}, err
		}
		if err := s.Await(nil); err != nil {
			return struct{}{}, err
		}
	}
	fmt.Println("Done!")
	return struct{}{}, nil
}

func notify(i int) (struct{}, error) {
	fmt.Printf("Countdown: %d\n", i)
	return struct{}{}, nil
}

func main() {
	// Instantiate Resonate
	r, err := resonate.New(resonate.Config{URL: "http://localhost:8001"})
	if err != nil {
		log.Fatalf("resonate.New: %v", err)
	}
	// Register the function
	if _, err := resonate.Register(r, "countdown", countdown); err != nil {
		log.Fatalf("Register: %v", err)
	}
	// Keep the worker alive to receive work
	sig := make(chan os.Signal, 1)
	signal.Notify(sig, os.Interrupt, syscall.SIGTERM)
	<-sig
}
```

Go's `Register` takes a single args type, so the CLI's `--arg 5 --arg 60` arrives as `[]int{5, 60}`. Most workflows use a named struct instead — see the [Go SDK guide](/develop/go).

[Working example](https://github.com/resonatehq-examples/example-quickstart-go)





```java title="src/main/java/io/resonatehq/examples/quickstart/Quickstart.java"
package io.resonatehq.examples.quickstart;

import io.resonatehq.resonate.Context;
import io.resonatehq.resonate.Resonate;
import java.time.Duration;
import java.util.concurrent.CountDownLatch;

public final class Quickstart {
    private Quickstart() {}

    // The two CLI --arg values arrive as positional arguments:
    // `--arg 5 --arg 60` binds to (count=5, delaySeconds=60).
    public static String countdown(Context ctx, int count, int delaySeconds) {
        for (int i = count; i > 0; i--) {
            // Run a function, persist its result.
            ctx.run(Quickstart::tick, i).await();
            // Suspend between ticks (but not after the last one) — a durable sleep.
            if (i > 1) {
                ctx.sleep(Duration.ofSeconds(delaySeconds)).await();
            }
        }
        return "done";
    }

    public static String tick(Context ctx, int i) {
        System.out.println("Countdown: " + i);
        return "ok";
    }

    public static void main(String[] args) throws InterruptedException {
        String url = System.getenv().getOrDefault("RESONATE_URL", "http://localhost:8001");
        // Instantiate Resonate
        Resonate r = Resonate.builder().url(url).build();
        // Register the workflow + its leaf
        r.register(Quickstart::countdown);
        r.register(Quickstart::tick);
        System.out.println("worker ready — registered 'countdown'. Invoke it with the Resonate CLI. Ctrl-C to exit.");
        // Keep the worker alive to receive work.
        new CountDownLatch(1).await();
    }
}
```

Java binds each CLI `--arg` to one method parameter positionally — the shared `--arg 5 --arg 60` step below becomes `(count=5, delaySeconds=60)`. This is the opposite of Go's single-slice binding. See the [Java SDK guide](/develop/java).

[Working example](https://github.com/resonatehq-examples/example-quickstart-java)





## Start the server

```shell
resonate dev
```

## Start the worker





```shell
npx ts-node countdown.ts
```





```shell
python countdown.py
```





```shell
cargo run
```





```shell
go run .
```





In a Gradle project with the `application` plugin pointed at `Quickstart` (the [working example](https://github.com/resonatehq-examples/example-quickstart-java) ships one ready to run):

```shell
./gradlew run
```





## Run the function

Run the function with execution ID `countdown.1`:

```shell
resonate invoke countdown.1 --func countdown --arg 5 --arg 60
```

## Result





```shell
npx ts-node countdown.ts
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
Done!
```





```shell
python countdown.py
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
```





```shell
cargo run
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
Done!
```





```shell
go run .
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
Done!
```





```shell
./gradlew run
worker ready — registered 'countdown'. Invoke it with the Resonate CLI. Ctrl-C to exit.
Countdown: 5
Countdown: 4
Countdown: 3
Countdown: 2
Countdown: 1
```





## What to try

Inspect the execution with `resonate tree` — it renders the call graph as durable promises.

```shell
resonate tree countdown.1
```

Now kill the worker mid-countdown and restart it with the same start command (keep `resonate dev` running). Because the invocation `countdown.1` already exists, **the countdown resumes where it stopped** instead of starting over. Use a delay long enough to interrupt it mid-countdown — for example `--arg 5 --arg 60`.

## Next steps

- [Learn how Resonate works](/evaluate/how-it-works)
- [Explore examples](/get-started/examples)

---

---
url: https://docs.resonatehq.io/index
title: Durable Execution Docs
---

<img src="/images/home-hero-dark.png" alt="Resonate" className="home-hero hidden dark:block" />
<img src="/images/home-hero-light.png" alt="Resonate" className="home-hero block dark:hidden" />

**Resonate is the durable execution engine that agents build with, deploy on, and operate.** It is the implementation of a distributed async/await programming model: a formal, language- and transport-agnostic protocol for writing functions that survive process restarts, run for hours or months, and coordinate across many machines.

Resonate is built on three pillars:

- **Agent-native** — The SDK, docs, tool definitions, and operational surface are designed for agent consumption, not just human developers. CLIs over dashboards. Skill files over screenshots. Agents are the new developers, and Resonate is the platform they reach for.
- **Generated & optimized** — Open-source pluggable components plus stack-specific generated servers. AI constrained by formal specs and protocols, producing highly optimized software tuned to exactly what your stack needs.
- **Cost-efficient by design** — Serverless-native architecture means you pay only for active execution. Workloads that cost ~$80K/year on hosted alternatives can run for under $100/year on Resonate. Orders of magnitude, not percentages.

Build agents, workflows, pipelines, and services without thinking about retries or recovery — in a few lines of code.

```typescript title="agent.ts — recursive sub-agent loop"
function* agent(context: Context, prompt: string) {
  const messages = [{ role: "user", content: prompt }];
  // The agent loop
  while (true) {
    const response = yield* context.run(think, messages);
    messages.push(response);

    if (response.subprompts) {
      // Spawn concurrent subagents
      const futures = [];
      for (const subprompt of response.subprompts) {
        futures.push(yield* context.beginRpc(agent, subprompt));
      }
      // Collect results
      for (const future of futures) {
        messages.push({ role: "tool", content: yield* future });
      }
    } else {
      return response.content;
    }
  }
}
```

---

---
url: https://docs.resonatehq.io/reference/cli
title: CLI reference
---

This page is the **single source of truth** for the `resonate` CLI. Every command, subcommand, and flag below is sourced from a specific file and line in [`resonatehq/resonate`](https://github.com/resonatehq/resonate); if the binary changes, this page is wrong until it is updated.

For default values (server flags, SDK init, retry policies), see [Defaults reference](/reference/defaults).

## Quick reference

The top-level subcommands defined in [`resonate/src/main.rs:43`](https://github.com/resonatehq/resonate/blob/main/src/main.rs#L43).

| Command | What it does | Typical use |
|---|---|---|
| [`resonate dev`](#resonate-dev) | Start the server with **in-memory SQLite** (ephemeral) | Local development, examples, smoke tests |
| [`resonate serve`](#resonate-serve) | Start the server with **persistent storage** | Production, staging, anything you don't want to lose on restart |
| [`resonate invoke`](#resonate-invoke) | Call a registered durable function by name | Trigger a workflow from the shell; smoke-test a worker |
| [`resonate promises`](#resonate-promises) | CRUD + search on durable promises | Inspect or settle promises directly; recovery work; debugging |
| [`resonate tasks`](#resonate-tasks) | Claim, fence, heartbeat, fulfill tasks | Build a custom worker outside the SDKs; inspect stuck tasks |
| [`resonate schedules`](#resonate-schedules) | CRUD + search on cron-driven schedules | Register / inspect / delete recurring jobs |
| [`resonate tree`](#resonate-tree) | Print a call-graph tree rooted at a promise ID | Debug what a workflow actually did at runtime |
| [`resonate mcp`](#resonate-mcp) | Start the MCP server (stdio transport) | Give Claude Code or another MCP client direct access to a Resonate server |

`promise`, `task`, `schedule` are accepted as singular aliases for `promises`, `tasks`, `schedules` — they map to the same handlers ([`resonate/src/main.rs:50,53,56`](https://github.com/resonatehq/resonate/blob/main/src/main.rs#L50-L56)).

## Global flags

These two flags are accepted on every **client** subcommand (promises, tasks, schedules, invoke, tree, mcp). They're defined on `GlobalArgs` in [`resonate/src/cli.rs:512-526`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L512-L526).

| Flag | Short | Default | What it does |
|---|---|---|---|
| `--server` | `-S` | `http://localhost:8001` | URL of the Resonate server to talk to |
| `--token` | `-T` | unset | JWT bearer token; required when the server has auth enabled |

```shell
# Talk to a remote server with auth
resonate -S https://resonate.example.com -T "$RESONATE_TOKEN" promises get my-promise
```

The defaults are wired so a freshly-started `resonate dev` on the same host needs no flags at all.

## Duration syntax

Several flags take a duration string. The parser is `parse_duration` at [`resonate/src/cli.rs:390-428`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L390-L428).

Accepted units: `ms`, `s`, `m`, `h`, `d`. Compound durations are summed left to right.

| Input | Resolves to |
|---|---|
| `100ms` | 100 ms |
| `30s` | 30 000 ms |
| `1m` | 60 000 ms |
| `1h` | 3 600 000 ms |
| `1d` | 86 400 000 ms |
| `1h30m` | 5 400 000 ms |
| `1d2h3m4s5ms` | 93 784 005 ms |

A bare integer like `42` (no unit) is **rejected**. `0s` is **rejected**; pass `0` or `""` if you mean zero.

## `resonate dev`

Start the Resonate server with in-memory SQLite. The database is wiped on restart.

**When you'd use it.** Local development, running examples, smoke-testing a worker before pointing it at a real server, CI jobs that don't need persistence.

```shell
resonate dev
# Resonate Server listening on 0.0.0.0:8001
```

Source: [`resonate/src/cli.rs:361-377`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L361-L377). `--storage-sqlite-path` defaults to `:memory:` for `dev` (vs `resonate.db` for `serve`); every other flag is shared with `serve`.

Override the path to keep state across `dev` restarts:

```shell
resonate dev --storage-sqlite-path ./dev.db
```

For the complete list of flags and their defaults, see [Defaults reference › Server defaults](/reference/defaults#server-defaults).

## `resonate serve`

Start the Resonate server with persistent storage. SQLite (file-backed), PostgreSQL, or MySQL.

**When you'd use it.** Anything beyond development. Production, staging, demo deployments, anything where losing state on restart is unacceptable.

```shell
# SQLite file in the current dir (default)
resonate serve

# Postgres
resonate serve \
  --storage-type postgres \
  --storage-postgres-url "postgres://<USER>:<PASSWORD>@localhost:5432/resonate"

# MySQL
resonate serve \
  --storage-type mysql \
  --storage-mysql-url "mysql://<USER>:<PASSWORD>@localhost:3306/resonate"
```

Source: [`resonate/src/cli.rs:338-356`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L338-L356). Loading order: built-in defaults → optional `resonate.toml` → environment variables → CLI flags ([`resonate/src/cli.rs:10-13`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L10-L13)).

For the complete flag list, defaults, and the environment-variable equivalents, see:

- [Defaults reference › Server defaults](/reference/defaults#server-defaults) — every flag and its default, cited file:line
- [Run a server › Configuration](/deploy/run-server#configuration) — operator-facing guide with `resonate.toml`, env vars, and recipe-style examples


The default `--tasks-retry-timeout` is `30000` ms ([`resonate/src/config.rs:253`](https://github.com/resonatehq/resonate/blob/main/src/config.rs#L253)). For most deployments, set this to `500` (milliseconds) to keep suspend/wake cycles fast on chained or recursive workflows.


## `resonate invoke`

Call a registered durable function by name. This creates a promise with the right tags so a worker (subscribed to the target) picks it up and runs the function durably.

**When you'd use it.** Trigger a workflow from the shell. Smoke-test that a worker is correctly registered. Kick off a one-off run that you don't want to write a tiny client program for.

```shell
resonate invoke my-run-001 \
  --func chargeCustomer \
  --arg cust_42 \
  --arg '{"amount": 1999, "currency": "USD"}' \
  --timeout 1h
```

Source: [`resonate/src/cli.rs:987-1088`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L987-L1088).

| Flag | Default | What it does |
|---|---|---|
| `<id>` (positional) | — | Promise ID. Must be unique across the server |
| `-f`, `--func` | — | Registered function name to invoke |
| `--arg` | — | Argument; repeatable. Each value parses as JSON; falls back to a plain string if JSON parsing fails ([`cli.rs:1043-1050`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L1043-L1050)) |
| `--json-args` | — | Alternative to `--arg`: a single JSON array of all arguments |
| `--version` | `1` | Function version |
| `-t`, `--timeout` | `1h` | Promise timeout (duration syntax above) |
| `--target` | `poll://any@default` | Where to deliver. `poll://any@<group>` routes to any worker in the dispatch group |
| `--delay` | unset | Delay before delivery (duration syntax) |

**Targets in one minute.** `poll://any@<group>` is the addressable identifier for "any worker in dispatch group `<group>`." The default group is `default` — matching the SDK init default ([Defaults reference › Cross-SDK parity](/reference/defaults#cross-sdk-parity)). If your worker subscribed to a different group, you need to say so:

```shell
resonate invoke factorial-001 \
  --func factorial --arg 10 \
  --target "poll://any@factorial-workers"
```

**Delayed delivery.** Useful for "run this in 5 seconds" smoke tests and for scheduling-like patterns without registering a real schedule:

```shell
resonate invoke heartbeat-001 --func heartbeat --delay 30s
```

## `resonate promises`

Direct CRUD + search on durable promises. The CLI alias `resonate promise <subcommand>` works identically ([`resonate/src/main.rs:50`](https://github.com/resonatehq/resonate/blob/main/src/main.rs#L50)).

**When you'd use it.** Inspect what's in the server. Settle a promise from the outside (manual recovery). Walk a list of promises with a tag filter. Build a recovery tool around the same operations the SDKs use.

Subcommands ([`resonate/src/cli.rs:539-613`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L539-L613)):

| Subcommand | What it does | Maps to protocol kind |
|---|---|---|
| `get <id>` | Fetch one promise | `promise.get` |
| `create <id> --timeout <d>` | Create a pending promise (optionally with `--param`, `--tags`) | `promise.create` |
| `resolve <id> [--value JSON]` | Resolve a pending promise | `promise.settle` |
| `reject <id> [--value JSON]` | Reject a pending promise | `promise.settle` |
| `cancel <id> [--value JSON]` | Cancel a pending promise (final state `rejected_canceled`) | `promise.settle` |
| `search [--state X] [--tags JSON] [--limit N] [--cursor C]` | Page through promises | `promise.search` |
| `register-callback <awaited> <awaiter>` | Hook one promise's completion to another | `promise.register_callback` |
| `register-listener <awaited> <address>` | Hook one promise's completion to a webhook or poll address | `promise.register_listener` |

### `resonate promises get`

```shell
resonate promises get my-run-001
```

### `resonate promises create`

```shell
resonate promises create my-run-002 \
  --timeout 1h \
  --param '{"headers": {}, "data": "hello"}' \
  --tags '{"env": "test"}'
```

`--param` and `--tags` are parsed as JSON ([`cli.rs:495-498`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L495-L498)). The `data` field inside `--param` is automatically base64-encoded ([`cli.rs:500-508`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L500-L508)) — pass it as a regular JSON value, the CLI handles encoding.

#### The `resonate:delay` tag

A promise tagged `resonate:delay` has its **task dispatch held back** until the given time — the server waits to send the task to a worker until the deadline elapses, instead of enqueueing it immediately (added in [resonatehq/resonate#844](https://github.com/resonatehq/resonate/pull/844)). The value is an absolute Unix epoch time in **milliseconds**, not a duration:

```shell
# Create the promise now, but don't dispatch its task until 2026-01-01T00:00:00Z
resonate promises create nightly-kickoff \
  --timeout 24h \
  --tags '{"resonate:target": "poll://any@default", "resonate:delay": "1767225600000"}'
```

Use it for a one-shot deferred invocation. For recurring work, use a [schedule](#resonate-schedules) instead.

### `resonate promises resolve | reject | cancel`

All three settle a pending promise; they differ only in the final state ([`cli.rs:642-652`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L642-L652)).

```shell
resonate promises resolve my-run-001 --value '{"headers": {}, "data": "ok"}'
resonate promises reject  my-run-002 --value '{"headers": {}, "data": "boom"}'
resonate promises cancel  my-run-003
```

### `resonate promises search`

`--state` accepts: `pending`, `resolved`, `rejected`, `rejected_canceled`, `rejected_timedout` ([`cli.rs:586-587`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L586-L587)). Default `--limit` is `100`.

```shell
# All pending promises tagged with env=prod
resonate promises search \
  --state pending \
  --tags '{"env": "prod"}' \
  --limit 50

# Page two using the returned cursor
resonate promises search --state pending --cursor "<cursor-from-previous-response>"
```

### `resonate promises register-callback` / `register-listener`

These wire one promise's completion to another effect.

```shell
# When promise A settles, the server enqueues a resume on promise B's awaiter task (via registered callback)
resonate promises register-callback promise-A promise-B

# When promise A resolves, the server POSTs to the URL
resonate promises register-listener promise-A "http://callback.example.com/hook"

# Or to an SSE poll address
resonate promises register-listener promise-A "poll://worker-1@default"
```

## `resonate tasks`

Direct task lifecycle operations. The CLI alias `resonate task <subcommand>` works identically ([`resonate/src/main.rs:53`](https://github.com/resonatehq/resonate/blob/main/src/main.rs#L53)).

**When you'd use it.** Build a worker outside the official SDKs. Inspect stuck tasks during incident response. Manually claim and complete a task that needs operator intervention. Most users will never call these directly — the SDKs do.

Subcommands ([`resonate/src/cli.rs:727-840`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L727-L840)):

| Subcommand | What it does | Maps to protocol kind |
|---|---|---|
| `get <id>` | Fetch one task | `task.get` |
| `create <id> --pid P --ttl D --timeout D` | Atomically create promise + acquired task | `task.create` |
| `claim <id> --pid P --version V --ttl D` | Acquire a pending task (worker entry point) | `task.acquire` |
| `fence <id> --version V --action JSON` | Execute a fenced inner action under task ownership | `task.fence` |
| `heartbeat --pid P --tasks JSON` | Renew leases for a batch of tasks | `task.heartbeat` |
| `suspend <id> --version V --actions JSON` | Suspend a task while awaiting other promises | `task.suspend` |
| `complete <id> --version V --action JSON` | Fulfill a task (settle its promise) | `task.fulfill` |
| `release <id> --version V` | Release an acquired task back to pending | `task.release` |
| `halt <id>` | Halt a task | `task.halt` |
| `continue <id>` | Resume a halted task | `task.continue` |
| `search [--state X] [--limit N] [--cursor C]` | Page through tasks | `task.search` |

`--version` carries optimistic concurrency. If the version on the server has moved, the call is rejected — that's how the server prevents two workers from both believing they own the same task.

### `resonate tasks claim`

The worker entry point. Acquire a pending task with a TTL.

```shell
resonate tasks claim task-abc \
  --pid worker-1 \
  --version 1 \
  --ttl 15s
```

The TTL is the task lease. While you hold the lease, periodic heartbeats keep it from expiring; the default server lease timeout is `15000` ms ([`resonate/src/config.rs:250`](https://github.com/resonatehq/resonate/blob/main/src/config.rs#L250)).

### `resonate tasks heartbeat`

Renew leases for any number of tasks the worker currently holds.

```shell
resonate tasks heartbeat \
  --pid worker-1 \
  --tasks '[{"id":"task-abc","version":3},{"id":"task-xyz","version":1}]'
```

### `resonate tasks complete`

Settle the task's promise and mark the task done. `--action` is the inner protocol envelope describing how to settle.

```shell
resonate tasks complete task-abc \
  --version 4 \
  --action '{"kind":"promise.settle","data":{"id":"task-abc","state":"resolved","value":{"headers":{},"data":"result"}}}'
```

### `resonate tasks search`

```shell
resonate tasks search --state acquired --limit 20
```

## `resonate schedules`

Cron-driven recurring promise creation. The CLI alias `resonate schedule <subcommand>` works identically ([`resonate/src/main.rs:56`](https://github.com/resonatehq/resonate/blob/main/src/main.rs#L56)).

**When you'd use it.** Register a recurring job. Inspect or delete an existing schedule. Audit what's running on a server.

Subcommands ([`resonate/src/cli.rs:1101-1145`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L1101-L1145)):

| Subcommand | What it does |
|---|---|
| `get <id>` | Fetch one schedule |
| `create <id> --cron <expr> --promise-id <tpl> --promise-timeout <d>` | Register a new schedule |
| `delete <id>` | Delete a schedule |
| `search [--tags JSON] [--limit N] [--cursor C]` | Page through schedules (default `--limit 10`) |

### `resonate schedules create`

`--cron` accepts a 5-, 6-, or 7-field cron expression, evaluated in **UTC only** with Quartz day-of-week numbering (`1` = Sunday — prefer day names like `MON-FRI`); see the [Schedules & cron reference](/reference/schedules) for the full format. `--promise-id` is a **template**; `{{.id}}` is substituted with the schedule's ID and `{{.timestamp}}` with the firing time (epoch ms) so each run gets a unique promise ID.

```shell
resonate schedules create nightly-rollup \
  --cron "0 2 * * *" \
  --promise-id "nightly-{{.timestamp}}" \
  --promise-timeout 1h \
  --promise-param '{"headers": {}, "data": "{}"}' \
  --promise-tags '{"resonate:target": "poll://any@default"}'
```

The `resonate:target` tag is what routes each fired promise to a worker — same convention as `resonate invoke --target`.

### `resonate schedules delete`

```shell
resonate schedules delete nightly-rollup
```

## `resonate tree`

Print the call-graph tree rooted at a promise ID. The tree walks every promise tagged with `resonate:origin=<root>` and prints them with their parent links and final states.

**When you'd use it.** Debugging. You ran a workflow, something behaved oddly, you want to see what actually happened — every `ctx.run`, every `ctx.rpc`, every sleep, every retry — as a single picture.

```shell
resonate tree my-run-001
```

```text
my-run-001 🟢 (rpc chargeCustomer)
├── my-run-001.step-1 🟢 (run validateInput)
├── my-run-001.step-2 🟢 (run fetchAccount)
├── my-run-001.sleep-1 🟢 (sleep)
└── my-run-001.step-3 🔴 (run submitCharge)
```

Source: [`resonate/src/cli.rs:1219-1321`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L1219-L1321). State icons:

| Icon | Meaning |
|---|---|
| 🟡 | `pending` |
| 🟢 | `resolved` |
| 🔴 | `rejected` / `rejected_canceled` / `rejected_timedout` |

Detail in parentheses shows the operation: `(rpc <func>)` for `ctx.rpc`, `(run <func>)` for `ctx.run`, `(sleep)` for `ctx.sleep`. Derived from the `resonate:scope` and `resonate:timer` tags ([`cli.rs:1324-1347`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L1324-L1347)).

## `resonate mcp`

Start an MCP (Model Context Protocol) server over stdio. The server proxies a Resonate server, exposing it as MCP tools so Claude Code (or any MCP client) can read and write promises directly.

**When you'd use it.** Pipe Resonate into an AI agent. The standard pattern is to register `resonate mcp` as an MCP server in Claude Code, then the agent can `promise-create`, `promise-get`, `promise-search` against your dev or prod server.

```shell
# Start it. Tracing goes to stderr; stdout is reserved for MCP framing.
resonate mcp --server http://localhost:8001
```

To wire it into Claude Code, see [Claude Code › Resonate MCP](/get-started/claude-code).

The tools the MCP server exposes (defined in [`resonate/src/mcp/mod.rs:186-260`](https://github.com/resonatehq/resonate/blob/main/src/mcp/mod.rs#L186-L260)):

| Tool | What it does |
|---|---|
| `promise-create` | Create a durable promise |
| `promise-get` | Fetch a promise |
| `promise-settle` | Resolve / reject / cancel a promise |
| `promise-search` | Search promises by state and tags |
| `promise-listen` | Block until a promise settles, then return the value |
| `resonate-bash` | Durable shell execution via the bash exec transport (requires the server to be running with `--transports-bash-exec-enabled true`) |

Like all client subcommands, it accepts `-S` / `--server` and `-T` / `--token` ([`resonate/src/cli.rs:381-385`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L381-L385)).

## Common scenarios

A few cross-cutting recipes that combine the commands above.

### Start a dev server and invoke a function

```shell
# Terminal 1
resonate dev

# Terminal 2 — your worker (TS, Py, Rs — anything subscribed to the default group)
node my-worker.js

# Terminal 3 — kick it off
resonate invoke run-001 --func myFunction --arg 42
```

### Inspect a workflow that looks stuck

```shell
# Get a top-down view of the call graph
resonate tree my-run-001

# Drill into a specific step
resonate promises get my-run-001.step-3

# Look at the tasks for the same root
resonate tasks search --state acquired --limit 20
```

### Cancel a workflow in flight

```shell
resonate promises cancel my-run-001
```

The cancel propagates: any child promise tagged `resonate:origin=my-run-001` that has a registered callback to a now-canceled parent will be settled `rejected_canceled` when the engine next walks the callback graph.

### Register a recurring job

```shell
# Every hour on the hour
resonate schedules create hourly-cleanup \
  --cron "0 * * * *" \
  --promise-id "cleanup-{{.timestamp}}" \
  --promise-timeout 30m \
  --promise-tags '{"resonate:target": "poll://any@cleanup-workers"}'

# Confirm
resonate schedules get hourly-cleanup
```

### Wire a Resonate server into Claude Code

```shell
# In Claude Code's MCP config
claude mcp add resonate -- resonate mcp --server http://localhost:8001
```

After that, Claude Code has `promise-create`, `promise-get`, `promise-search`, `promise-listen`, `promise-settle`, and `resonate-bash` as tools. See [Claude Code › Resonate MCP](/get-started/claude-code) for the full setup.

### Pipe output through `jq`

Every command prints pretty JSON to stdout ([`resonate/src/cli.rs:486-488`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L486-L488)); errors go to stderr with exit code 1 ([`cli.rs:490-493`](https://github.com/resonatehq/resonate/blob/main/src/cli.rs#L490-L493)). So scripting is straightforward:

```shell
# List the IDs of all pending promises
resonate promises search --state pending --limit 1000 | jq -r '.promises[].id'

# Find the most-recently created schedule
resonate schedules search --limit 100 | jq '.schedules | max_by(.createdAt)'
```

## Environment variables

The CLI itself reads no env vars — every flag is explicit. But the **server** (when started via `resonate serve` / `resonate dev`) reads `RESONATE_<SECTION>__<FIELD>` for every config field. See:

- [Defaults reference › Environment variables](/reference/defaults#environment-variables) — SDK + shared env vars
- [Run a server › Environment variables](/deploy/run-server#environment-variables) — server-side `RESONATE_*` map

## See also

- [Defaults reference](/reference/defaults) — every default value, cited file:line, across server and SDKs
- [Run a server](/deploy/run-server) — operator-facing deployment guide
- [Claude Code › Resonate MCP](/get-started/claude-code) — wiring `resonate mcp` into an agent
- [`resonatehq/resonate` › src/cli.rs](https://github.com/resonatehq/resonate/blob/main/src/cli.rs) — canonical CLI source
- [`resonatehq/resonate` › src/main.rs](https://github.com/resonatehq/resonate/blob/main/src/main.rs) — top-level subcommand wiring

---

---
url: https://docs.resonatehq.io/reference/defaults
title: Defaults reference
---

This page is the **single source of truth** for default values across the Resonate server and SDKs. Every value below is sourced from a specific file and line in the canonical source repositories; if a default changes in source, this page is wrong until it is updated.

If you only want to know "what does `ctx.run` retry by default?" — see [ctx.run / per-call options](#ctxrun--per-call-options) and [Retry policies](#retry-policies).

For the commands these flags belong to (`resonate serve`, `resonate dev`, `resonate invoke`, etc.) and worked usage examples, see [CLI reference](/reference/cli).

---

## Server defaults

The Resonate server is a Rust binary. Its source lives at [`resonatehq/resonate`](https://github.com/resonatehq/resonate); every default below is sourced from `src/config.rs`. The CLI flag name is the kebab-case path through the config struct (e.g. `tasks.lease_timeout` → `--tasks-lease-timeout`); the equivalent environment variable uses double-underscore nesting (e.g. `RESONATE_TASKS__LEASE_TIMEOUT`). Loading order: built-in defaults → optional `resonate.toml` → env vars.

### HTTP server

| Setting | Default | Source |
|---|---|---|
| `--server-host` | `"localhost"` | `resonate/src/config.rs:99` |
| `--server-port` | `8001` | `resonate/src/config.rs:102` |
| `--server-bind` | `"0.0.0.0"` | `resonate/src/config.rs:105` |
| `--server-shutdown-timeout` | `10000` ms | `resonate/src/config.rs:108` |
| `--server-url` | unset (falls back to `http://{host}:{port}` in response headers) | `resonate/src/config.rs:91` |
| `--server-cors-allow-origins` | empty (CORS disabled) | `resonate/src/config.rs:67` |
| `--level` | `"info"` | `resonate/src/config.rs:60` |

### Storage

| Setting | Default | Source |
|---|---|---|
| `--storage-type` | `"sqlite"` | `resonate/src/config.rs:148` |
| `--storage-sqlite-path` | `"resonate.db"` | `resonate/src/config.rs:159` |
| `--storage-postgres-url` | unset | `resonate/src/config.rs:174` |
| `--storage-postgres-pool-size` | `10` | `resonate/src/config.rs:182` |
| `--storage-mysql-url` | unset | `resonate/src/config.rs:197` |
| `--storage-mysql-pool-size` | `10` | `resonate/src/config.rs:182` (shared `default_pool_size`) |

### Tasks + background scans

| Setting | Default | Source |
|---|---|---|
| `--tasks-lease-timeout` | `15000` ms | `resonate/src/config.rs:250` |
| `--tasks-retry-timeout` | `30000` ms | `resonate/src/config.rs:253` — most deployments should lower this to `500` ms; see the [tip on Run a server](/deploy/run-server#configuration) |
| `--timeouts-poll-interval` | `1000` ms | `resonate/src/config.rs:273` |
| `--messages-poll-interval` | `100` ms | `resonate/src/config.rs:296` |
| `--messages-batch-size` | `100` | `resonate/src/config.rs:299` |

### Transports

| Setting | Default | Source |
|---|---|---|
| `--transports-http-push-enabled` | `true` | `resonate/src/config.rs:399` |
| `--transports-http-push-concurrency` | `16` | `resonate/src/config.rs:387` |
| `--transports-http-push-connect-timeout` | `10000` ms | `resonate/src/config.rs:390` |
| `--transports-http-push-request-timeout` | `180000` ms | `resonate/src/config.rs:393` |
| `--transports-http-push-auth-mode` | `"none"` | `resonate/src/config.rs:462` (`HttpPushAuthMode::None`) |
| `--transports-http-push-auth-header` | `"Authorization"` | `resonate/src/config.rs:442` |
| `--transports-http-poll-enabled` | `true` | `resonate/src/config.rs:494` |
| `--transports-http-poll-max-connections` | `1000` | `resonate/src/config.rs:485` |
| `--transports-http-poll-buffer-size` | `100` | `resonate/src/config.rs:488` |
| `--transports-gcps-enabled` | `false` | `resonate/src/config.rs:351` |
| `--transports-bash-exec-enabled` | `false` | `resonate/src/config.rs:342` |

### Observability

| Setting | Default | Source |
|---|---|---|
| `--observability-metrics-port` | `9090` (set to `0` to disable) | `resonate/src/config.rs:513` |
| `--observability-otlp-endpoint` | `"localhost:4317"` | `resonate/src/config.rs:516` |

---

## SDK init defaults

The SDK init defaults are the values you get from calling `new Resonate()` (TypeScript), `Resonate()` (Python), or `Resonate::local()` / `Resonate::new(ResonateConfig::default())` (Rust) with no arguments.

### TypeScript

| Option | Default | Source |
|---|---|---|
| `url` | resolved from `RESONATE_URL` env, otherwise local in-memory network | `resonate-sdk-ts/src/resonate.ts:147` |
| `group` | `"default"` | `resonate-sdk-ts/src/resonate.ts:103` |
| `pid` | random UUID | `resonate-sdk-ts/src/resonate.ts:149` |
| `ttl` | `1 * util.MIN` = **60,000 ms** | `resonate-sdk-ts/src/resonate.ts:105` (constant at `src/util.ts:25`) |
| `verbose` | `false` | `resonate-sdk-ts/src/resonate.ts:108` |
| `logLevel` | `"warn"` (fallback when `verbose=false`) | `resonate-sdk-ts/src/resonate.ts:137` |
| `prefix` | resolved from `RESONATE_PREFIX`, else empty | `resonate-sdk-ts/src/resonate.ts:132` |
| HTTP request timeout (`HttpNetwork`) | `RESONATE_TIMEOUT` env var if set, else `10 * util.SEC` = **10,000 ms** | `resonate-sdk-ts/src/network/http.ts:60-62` |
| HTTP URL fallback | `"http://localhost:8001"` | `resonate-sdk-ts/src/network/http.ts:58` |

There is no `workers` / `concurrency` parameter in the TypeScript SDK — task execution runs on the Node/Bun event loop with no SDK-side cap.

See [TypeScript SDK Defaults](/develop/typescript#defaults) for surface-scoped framing.

### Python

| Option | Default | Source |
|---|---|---|
| `url` | resolved from `RESONATE_URL`, else `RESONATE_HOST` + `RESONATE_PORT`, else local | `resonate-sdk-py/resonate/resonate.py:173-181` |
| `group` | `"default"` | `resonate-sdk-py/resonate/resonate.py:99` |
| `pid` | `uuid.uuid4().hex` | `resonate-sdk-py/resonate/resonate.py:161` |
| `ttl` | `10` (seconds) | `resonate-sdk-py/resonate/resonate.py:101` |
| `log_level` | `logging.INFO` | `resonate-sdk-py/resonate/resonate.py:102` |
| `workers` | `min(32, workers or (os.cpu_count() or 1))` | `resonate-sdk-py/resonate/processor.py:16` |
| `RESONATE_SCHEME` fallback | `"http"` | `resonate-sdk-py/resonate/resonate.py:179` |
| `RESONATE_PORT` fallback | `"8001"` | `resonate-sdk-py/resonate/resonate.py:180` |


Python `ttl=10` is **10 seconds**. TypeScript `ttl=60000` is **60 seconds**. They are not identical defaults in either value or unit.


See [Python SDK Defaults](/develop/python#defaults) for surface-scoped framing.

### Rust

| Option | Default | Source |
|---|---|---|
| `url` | resolved from `RESONATE_URL`, else `RESONATE_HOST`/`RESONATE_SCHEME`/`RESONATE_PORT` | `resonate-sdk-rs/resonate/src/resonate.rs:164-171` |
| `RESONATE_SCHEME` fallback | `"http"` | `resonate-sdk-rs/resonate/src/resonate.rs:168` |
| `RESONATE_PORT` fallback | `"8001"` | `resonate-sdk-rs/resonate/src/resonate.rs:169` |
| `group` | `"default"` (in `local_with`) | `resonate-sdk-rs/resonate/src/resonate.rs:121` |
| `pid` | `"default"` (in `local_with`); from network in remote mode | `resonate-sdk-rs/resonate/src/resonate.rs:120,191` |
| `ttl` | `60_000` ms (remote) / `u64::MAX` (local) | `resonate-sdk-rs/resonate/src/resonate.rs:151,127` |
| `prefix` | resolved from `RESONATE_PREFIX`, else empty | `resonate-sdk-rs/resonate/src/resonate.rs:154-156` |

The Rust SDK has no `workers` parameter — function execution runs on the user-supplied Tokio runtime.

See [Rust SDK Defaults](/develop/rust#defaults) for surface-scoped framing.

---

## ctx.run / per-call options

These are the defaults applied to a single `ctx.run(...)`, `ctx.rpc(...)`, or top-level `resonate.run(...)` call when no per-call options are passed.

### TypeScript

The TypeScript `Options` class sets the following defaults in its constructor:

| Field | Default | Source |
|---|---|---|
| `id` | `undefined` (auto-generated by the runtime) | `resonate-sdk-ts/src/options.ts:48` |
| `retryPolicy` | `undefined` at the options layer; **resolved to `new Exponential()` for regular functions, `new Never()` for generator functions** when `ctx.run` / `ctx.rpc` executes | `resonate-sdk-ts/src/options.ts:49`, resolution at `resonate-sdk-ts/src/context.ts:397,432` |
| `tags` | `{}` | `resonate-sdk-ts/src/options.ts:50` |
| `target` | `"default"` | `resonate-sdk-ts/src/options.ts:51` |
| `timeout` | `24 * util.HOUR` = **86,400,000 ms (24 h)** | `resonate-sdk-ts/src/options.ts:52` (constants at `src/util.ts:24-26`) |
| `version` | `0` | `resonate-sdk-ts/src/options.ts:53` |
| `nonRetryableErrors` | `[]` | `resonate-sdk-ts/src/options.ts:54` |

So the practical answer to "what is the default retry behaviour of `ctx.run` in the TypeScript SDK?" is: **`Exponential()` with its own defaults** (see below) for regular `async` functions, and **`Never()`** for generator functions.

See [TypeScript SDK Defaults](/develop/typescript#defaults) for surface-scoped framing.

### Python

The Python `Options` dataclass:

| Field | Default | Source |
|---|---|---|
| `durable` | `True` | `resonate-sdk-py/resonate/options.py:18` |
| `encoder` | `None` | `resonate-sdk-py/resonate/options.py:19` |
| `id` | `None` (auto-generated) | `resonate-sdk-py/resonate/options.py:20` |
| `idempotency_key` | `lambda id: id` (identity) | `resonate-sdk-py/resonate/options.py:21` |
| `non_retryable_exceptions` | `()` | `resonate-sdk-py/resonate/options.py:22` |
| `retry_policy` | `lambda f: Never() if isgeneratorfunction(f) else Exponential()` | `resonate-sdk-py/resonate/options.py:23` |
| `target` | `"default"` | `resonate-sdk-py/resonate/options.py:24` |
| `tags` | `{}` | `resonate-sdk-py/resonate/options.py:25` |
| `timeout` | `31_536_000` = **1 year, in seconds** | `resonate-sdk-py/resonate/options.py:26` |
| `version` | `0` | `resonate-sdk-py/resonate/options.py:27` |

See [Python SDK Defaults](/develop/python#defaults) for surface-scoped framing.

### Rust

The Rust `Options` struct currently exposes only structural fields:

| Field | Default | Source |
|---|---|---|
| `tags` | `HashMap::new()` (empty) | `resonate-sdk-rs/resonate/src/options.rs:20` |
| `target` | `"default"` | `resonate-sdk-rs/resonate/src/options.rs:21` |
| `timeout` | `Duration::from_secs(86_400)` = **24 h** | `resonate-sdk-rs/resonate/src/options.rs:22` |
| `version` | `0` | `resonate-sdk-rs/resonate/src/options.rs:23` |


The Rust SDK `Options` struct does **not** carry a `retry_policy` field — retry behaviour is governed by the server's task-retry contract, not by a per-invocation policy. This is a known asymmetry with the TypeScript and Python SDKs and is tracked separately.


See [Rust SDK Defaults](/develop/rust#defaults) for surface-scoped framing.

---

## Retry policies

Retry policies are constructible by users and supplied via the per-call options. The four built-in policies share the same shape across TypeScript and Python with one important difference: **TypeScript times are in milliseconds, Python times are in seconds.**

### Exponential

| Parameter | TypeScript default | Python default |
|---|---|---|
| `delay` | `1000` (ms) — `resonate-sdk-ts/src/retries.ts:53` | `1` (sec) — `resonate-sdk-py/resonate/retry_policies/exponential.py:11` |
| `factor` | `2` — `resonate-sdk-ts/src/retries.ts:54` | `2` — `resonate-sdk-py/resonate/retry_policies/exponential.py:13` |
| `maxRetries` / `max_retries` | `Number.MAX_SAFE_INTEGER` — `resonate-sdk-ts/src/retries.ts:55` | `sys.maxsize` — `resonate-sdk-py/resonate/retry_policies/exponential.py:12` |
| `maxDelay` / `max_delay` | `30000` (ms) — `resonate-sdk-ts/src/retries.ts:56` | `30` (sec) — `resonate-sdk-py/resonate/retry_policies/exponential.py:14` |

Both SDKs use the formula `min(delay * factor^attempt, maxDelay)` for the n-th retry, with attempt 0 returning 0.

### Constant

| Parameter | TypeScript default | Python default |
|---|---|---|
| `delay` | `1000` (ms) — `resonate-sdk-ts/src/retries.ts:16` | `1` (sec) — `resonate-sdk-py/resonate/retry_policies/constant.py:11` |
| `maxRetries` / `max_retries` | `Number.MAX_SAFE_INTEGER` — `resonate-sdk-ts/src/retries.ts:16` | `sys.maxsize` — `resonate-sdk-py/resonate/retry_policies/constant.py:12` |

### Linear

| Parameter | TypeScript default | Python default |
|---|---|---|
| `delay` | `1000` (ms) — `resonate-sdk-ts/src/retries.ts:93` | `1` (sec) — `resonate-sdk-py/resonate/retry_policies/linear.py:11` |
| `maxRetries` / `max_retries` | `Number.MAX_SAFE_INTEGER` — `resonate-sdk-ts/src/retries.ts:93` | `sys.maxsize` — `resonate-sdk-py/resonate/retry_policies/linear.py:12` |

The n-th retry delay is `delay * attempt` in both SDKs.

### Never

`Never` takes no parameters in either SDK. It returns `0` on attempt 0 and `null` / `None` for all later attempts.

- TypeScript — `resonate-sdk-ts/src/retries.ts:118-135`
- Python — `resonate-sdk-py/resonate/retry_policies/never.py`

### Rust

The Rust SDK does not yet ship `Exponential` / `Constant` / `Linear` / `Never` retry-policy types — there is no per-invocation retry policy on the Rust `Options` struct (see the callout above). Retry behaviour for Rust workers is determined server-side via `--tasks-retry-timeout`.

---

## Cross-SDK parity

| Concept | TypeScript | Python | Rust |
|---|---|---|---|
| Init `group` | `"default"` | `"default"` | `"default"` |
| Init `ttl` | `60_000` ms | `10` sec | `60_000` ms (remote) / `u64::MAX` (local) |
| Init time unit | milliseconds | seconds | milliseconds (ttl) / `Duration` (timeout) |
| Per-call `timeout` | 24 h | 1 year | 24 h |
| Per-call `target` | `"default"` | `"default"` | `"default"` |
| Per-call `tags` | `{}` | `{}` | empty `HashMap` |
| Per-call `version` | `0` | `0` | `0` |
| Default retry policy (regular fn) | `Exponential()` | `Exponential()` | not configurable per-call |
| Default retry policy (generator fn) | `Never()` | `Never()` | n/a |
| Retry-policy time unit | milliseconds | seconds | n/a |
| `Exponential` `maxDelay` | `30_000` ms | `30` sec | n/a |
| Concurrency cap | none | `min(32, workers or os.cpu_count() or 1)` | none (Tokio runtime) |

**Asymmetries to call out:**

- **Per-call `timeout`.** TypeScript and Rust default to **24 h**; Python defaults to **1 year**. Same field, very different envelope.
- **`ttl`.** TypeScript and Rust use **milliseconds**; Python uses **seconds**. Same name, different unit.
- **Retry-policy time units.** TypeScript retry policies are configured in **milliseconds**; Python retry policies are configured in **seconds**. The behaviour curve is identical; the numbers are not.
- **Per-call retry policy.** Available in TypeScript and Python; **not yet on the Rust `Options` struct**. Rust retries are governed by the server's `--tasks-retry-timeout` flag.
- **Worker concurrency cap.** Only Python imposes one (`min(32, ...)`). TypeScript and Rust lean on the host event-loop / runtime.

---

## Environment variables

The SDKs share a common set of `RESONATE_*` environment variables. Defaults below are the fallbacks applied when both the constructor argument and the env var are unset.

| Env var | Default | Sources |
|---|---|---|
| `RESONATE_URL` | unset → local in-memory mode | TS: `resonate-sdk-ts/src/resonate.ts:147`; Py: `resonate-sdk-py/resonate/resonate.py:175`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:165` |
| `RESONATE_HOST` | unset | TS: not consumed; Py: `resonate-sdk-py/resonate/resonate.py:177`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:167` |
| `RESONATE_SCHEME` | `"http"` | Py: `resonate-sdk-py/resonate/resonate.py:179`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:168` |
| `RESONATE_PORT` | `"8001"` | Py: `resonate-sdk-py/resonate/resonate.py:180`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:169` |
| `RESONATE_TOKEN` | unset | TS: `resonate-sdk-ts/src/network/http.ts:67`; Py: `resonate-sdk-py/resonate/resonate.py:184`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:175` |
| `RESONATE_USERNAME` | unset (Python only) | Py: `resonate-sdk-py/resonate/resonate.py:187` |
| `RESONATE_PASSWORD` | `""` (Python only) | Py: `resonate-sdk-py/resonate/resonate.py:189` |
| `RESONATE_PREFIX` | unset → empty prefix | TS: `resonate-sdk-ts/src/resonate.ts:132`; Rs: `resonate-sdk-rs/resonate/src/resonate.rs:155` |
| `RESONATE_TIMEOUT` | `10000` ms (TS HTTP only) | TS: `resonate-sdk-ts/src/network/http.ts:60-62` |
| `RESONATE_URL` HTTP fallback | `"http://localhost:8001"` (TS `HttpNetwork` constructor) | `resonate-sdk-ts/src/network/http.ts:58` |

Server-side `RESONATE_*` environment variables (storage, auth, transports) follow the `RESONATE_<SECTION>__<FIELD>` convention. See [Run a server › Environment variables](/deploy/run-server#environment-variables) for the complete list — those defaults track the server flag table above.

---

---
url: https://docs.resonatehq.io/reference
title: Reference
---

<img src="/images/banner-reference-dark.png" alt="Reference section" className="hidden dark:block" />
<img src="/images/banner-reference-light.png" alt="Reference section" className="block dark:hidden" />

The reference section is the **single source of truth** for the facts that don't change with the page you're reading — default values across the server and SDKs, the surface of the `resonate` CLI, and how schedules and cron expressions behave.

Every page cites every value back to a specific file and line in the canonical source repositories. If a default or a flag changes in source, the page is wrong until it is updated.

## What's here

### [Defaults reference](/reference/defaults)

Every default value, in one place, cited file:line:

- **Server defaults** — every flag of `resonate serve` / `resonate dev`, sourced from [`resonatehq/resonate`](https://github.com/resonatehq/resonate) `src/config.rs`
- **SDK init defaults** — TypeScript, Python, Rust constructor defaults (`url`, `group`, `pid`, `ttl`, `logLevel`, workers)
- **`ctx.run` / per-call options** — default `timeout`, `target`, `version`, `tags`, retry policy resolution
- **Retry policies** — `Exponential`, `Constant`, `Linear`, `Never` — defaults per SDK
- **Cross-SDK parity table** — where TS, Python, and Rust agree and where they don't (timeouts, ttls, retry-policy time units)
- **Environment variables** — every `RESONATE_*` variable the SDKs read

Use it when you need to know "what does X default to?" and want a citation, not a paraphrase.

### [CLI reference](/reference/cli)

Every `resonate` subcommand, with scenarios and worked examples:

- **`resonate dev` / `resonate serve`** — start the server (in-memory vs persistent)
- **`resonate invoke`** — trigger a registered function from the shell
- **`resonate promises`** — direct CRUD + search on durable promises
- **`resonate tasks`** — task lifecycle for custom workers and operator recovery
- **`resonate schedules`** — cron-driven recurring jobs
- **`resonate tree`** — call-graph visualisation rooted at a promise ID (debugging)
- **`resonate mcp`** — start the MCP server (stdio) so Claude Code or any MCP client can drive Resonate directly
- **Common scenarios** — start a dev server and invoke a function, inspect a stuck workflow, cancel in flight, register a recurring job, wire into Claude Code

Use it when you need to know "what command do I run for X?" and want a working example.

### [Schedules & cron reference](/reference/schedules)

How schedules behave on the server, independent of SDK or CLI:

- **Cron expression format** — 5/6/7-field layouts, with examples
- **Day-of-week convention** — Quartz numbering (`1` = Sunday), why day names like `MON-FRI` are the safe form
- **Timezone** — expressions evaluate in UTC only; there is no timezone option
- **The `resonate:target` requirement** — the routing tag every schedule must carry, and the exact error when it's missing
- **Promise-ID templates** — the two substituted variables (`{{.id}}`, `{{.timestamp}}`) and why templates need `{{.timestamp}}`
- **Tags on fired promises** — what the server injects at fire time, and how to search fired promises

Use it when a schedule fires at the wrong time, fires and nothing runs, or won't create.

## How to use the reference pages

The pages are sister surfaces:

- **Defaults** answers "*what* is the default for X?" — read it when you need a value.
- **CLI** answers "*how* do I run X?" — read it when you need a command.
- **Schedules & cron** answers "*why* did my schedule do that?" — read it when cron behavior surprises you.

If a CLI flag's default surprises you, the CLI page links to the matching row on the defaults page. If a default value's owner isn't obvious, the defaults page links to the command that exposes it.

## For agents

Both pages are designed to be Echo-indexed and MCP-friendly:

- Every value and command is cited file:line, so a follow-up "show me the source" question resolves cleanly
- Scenarios are written as runnable commands, so an agent that finishes reading can hand the user a working example
- Cross-references between sibling pages are explicit, so a question about "the default `--tasks-retry-timeout`" routes correctly even if it lands on the wrong page first

If you're building an agent against a Resonate server, the [`resonate mcp`](/reference/cli#resonate-mcp) subcommand is the entry point: it exposes the most-used promise operations as MCP tools that wrap the same surface this section documents.

---

---
url: https://docs.resonatehq.io/reference/schedules
title: Schedules & cron reference
---

This page is the **single source of truth** for how Resonate schedules behave, independent of which SDK (or the CLI) you create them with. Every fact below is sourced from a specific file and line in [`resonatehq/resonate`](https://github.com/resonatehq/resonate); if the server changes, this page is wrong until it is updated.

For the CLI commands that operate on schedules, see [CLI reference › `resonate schedules`](/reference/cli#resonate-schedules).

## What a schedule is

A schedule is a server-side cron rule that creates a new durable promise on every tick. The schedule stores a **promise-ID template**, a **promise timeout**, an optional **promise param** (the payload workers decode to know what to run), and **promise tags** (copied onto every fired promise). Workers never poll the schedule itself — they receive the fired promises, routed by the `resonate:target` tag.

## Cron expression format

The server parses cron expressions with the [`cron` crate](https://docs.rs/cron) ([`resonate/Cargo.toml:34`](https://github.com/resonatehq/resonate/blob/main/Cargo.toml#L34)), which accepts 5, 6, or 7 fields:

| Fields | Layout | Example | Meaning |
|---|---|---|---|
| 5 | `min hour dom month dow` | `0 2 * * *` | Daily at 02:00 |
| 6 | `sec min hour dom month dow` | `*/30 * * * * *` | Every 30 seconds |
| 7 | `sec min hour dom month dow year` | `0 0 9 * * MON-FRI 2027` | Weekday mornings in 2027 only |

### Day-of-week: use names, not numbers

The day-of-week field follows the **Quartz convention**: `1` = Sunday through `7` = Saturday. This silently differs from POSIX cron (`0`–`6` = Sunday–Saturday), so numeric day-of-week expressions copied from a crontab do not mean what they meant there:

- `1-5` means **Sunday through Thursday**, not Monday through Friday
- `0` is not a valid day — the create fails with `Invalid cron expression`

Day **names** are unambiguous and always mean the same thing. Prefer them:

```text
0 9 * * MON-FRI    # 09:00 on weekdays — says what it means
0 9 * * 2-6        # the same thing in Quartz numbering — avoid
```

### Timezone: UTC only

Cron expressions are evaluated in **UTC**. There is no per-schedule or per-server timezone option — no config field exists for it. `0 9 * * MON-FRI` fires at 09:00 UTC, which is 02:00 in Los Angeles (PDT) and 10:00 in Berlin (CEST). Convert your local time to UTC when writing the expression, and remember the UTC offset of a civil time changes across daylight-saving transitions.

## The `resonate:target` requirement

Every fired promise needs a routing target, or no worker group will ever receive it. Starting with the server release after v0.9.8, the server therefore **rejects** `schedule.create` when `promiseTags` lacks a `resonate:target` tag ([`resonate/src/types.rs:641-643`](https://github.com/resonatehq/resonate/blob/main/src/types.rs#L641-L643)):

```text
400 promiseTags must include a resonate:target tag
```


On v0.9.8 (the current release) and earlier, the server **accepts** an untagged `schedule.create` — the schedule fires, but its promises are never dispatched to any worker. SDK releases that carry the schedule fixes (Python `resonate-sdk` ≥0.7.4, Rust `resonate-sdk` ≥0.6.0) enforce the rejection above in their in-process (local) networks regardless of server version.


The value is an address like `poll://any@default` — the same convention as `resonate invoke --target` and the SDKs' `target` option. The high-level `schedule()` APIs that inject this tag for you take the target from the same option surface as `run`/`rpc`; the low-level schedule sub-clients and the CLI require you to pass it explicitly:

```shell
resonate schedules create nightly-rollup \
  --cron "0 2 * * *" \
  --promise-id "nightly-{{.timestamp}}" \
  --promise-timeout 1h \
  --promise-tags '{"resonate:target": "poll://any@default"}'
```

## Promise-ID templates

The schedule's `promiseId` is a template. The server substitutes **exactly two** variables at fire time ([`resonate/src/oracle.rs:1875-1877`](https://github.com/resonatehq/resonate/blob/main/src/oracle.rs#L1875-L1877)):

| Variable | Substituted with |
|---|---|
| `{{.id}}` | The schedule's ID |
| `{{.timestamp}}` | The tick's fire time, as a Unix epoch timestamp in **milliseconds** |

Anything else in the template is literal text. A template of `report.{{.id}}.{{.timestamp}}` on a schedule named `nightly` produces promise IDs like `report.nightly.1783978446000`.

Include `{{.timestamp}}` in every template: promise creation is idempotent by ID, so a template without it produces the **same** promise ID on every tick — the first tick creates the promise and every later tick is a no-op against it.

## Tags on fired promises

Each fired promise carries the schedule's `promiseTags` (including your `resonate:target`) plus five tags the server injects at fire time ([`resonate/src/oracle.rs:1874-1881`](https://github.com/resonatehq/resonate/blob/main/src/oracle.rs#L1874-L1881)):

| Tag | Value |
|---|---|
| `resonate:schedule` | The schedule's ID |
| `resonate:origin` | The fired promise's own ID |
| `resonate:branch` | The fired promise's own ID |
| `resonate:parent` | The fired promise's own ID |
| `resonate:prefix` | The fired promise's own ID |

Each fired promise is the **root** of its own call graph — origin, branch, parent, and prefix all point at itself, exactly like a top-level `run`/`rpc` promise. Two useful consequences:

- `resonate tree <fired-promise-id>` shows the full call graph of that one tick
- `resonate promises search --tags '{"resonate:schedule": "<schedule-id>"}'` lists every promise a schedule has ever fired

## Delete and search

Deleting a schedule stops future ticks; promises already fired are unaffected and settle (or time out) on their own:

```shell
resonate schedules delete nightly-rollup
```

Schedules are searchable with cursor pagination. The `--tags` filter matches against each schedule's **promise tags** ([`resonate/src/oracle.rs:1581-1587`](https://github.com/resonatehq/resonate/blob/main/src/oracle.rs#L1581-L1587)) — a schedule has no separate tag set of its own:

```shell
resonate schedules search --limit 100
resonate schedules search --tags '{"resonate:target": "poll://any@default"}' --limit 100
```

The equivalent operations exist on every SDK's `schedules` sub-client.