Quickstart

This walkthrough runs a script that reads a GitHub repository through the built-in http tool and calls one function of your own. The complete program is examples/quickstart.

Get an API key

Sign in to the dashboard at app.rewind.codes, open the account menu at the bottom of the sidebar, then Organization → API keys → New key. Give it the harness role. The secret is shown once: copy it.

A new API key, shown once after its creation

Running your own server instead? See Self-hosting: the steps below are the same with its URL.

Install the SDK

Node 22.12 or later. The package is ESM only and depends on no model SDK.

npm install @rewind.codes/sdk

pnpm add @rewind.codes/sdk

The client reads its server and key from the environment:

export REWIND_URL=https://api.rewind.codes
export REWIND_API_KEY=rewind_sk_...

A toolset is what scripts may call. This one enables the http tool for api.github.com only, and declares a host tool, notify, that your own code executes.

index.ts

import { Rewind } from "@rewind.codes/sdk";

const rewind = new Rewind();

const toolset = await rewind.toolsets.create({
  http: { allow: ["api.github.com"] },
  host: [
    {
      name: "notify",
      description: "Send a short message to the user.",
      inputSchema: { type: "object", properties: { text: { type: "string" } }, required: ["text"] },
    },
  ],
});

console.log(toolset.declarations.prompt);

Rewind answers with the declarations of the toolset, in a compact form for the model’s prompt:

import { notify } from "rewind:tools";
fetch(url, { method?, headers?, body? }) → Response · The http tool, a global: HTTP requests to these hosts only: api.github.com.
notify({ text: string }) → unknown · Send a short message to the user.
webhook(name) → { url: string } · From "rewind": a URL bound to this run; what is posted to it becomes the signal `name`.

Serve the host tool

A worker long-polls the calls to your host tools, runs the handler and answers. It runs in your infrastructure: the handler can reach your database, your users, another model.

index.ts

const worker = rewind.worker({
  toolset: toolset.id,
  tools: {
    notify: async ({ text }: { text: string }, ctx) => {
      console.log(`[notify for ${ctx.namespace}] ${text}`);
      return { sent: true };
    },
  },
});

Run a script

In a harness, the model writes the script. Here it is a file:

scripts/repo-report.ts

import { notify } from "rewind:tools";

export default async function main(input: { repo: string }) {
  const res = await fetch(`https://api.github.com/repos/${input.repo}`, {
    headers: { accept: "application/vnd.github+json", "user-agent": "rewind-quickstart" },
  });
  if (!res.ok) throw new Error(`GitHub answered ${res.status} for ${input.repo}`);
  const repo = await res.json();

  const report = {
    repo: repo.full_name as string,
    stars: repo.stargazers_count as number,
    openIssues: repo.open_issues_count as number,
    pushedAt: repo.pushed_at as string,
  };
  console.log(`${report.repo}: ${report.stars} stars`);

  await notify({ text: `${report.repo} has ${report.openIssues} open issues and pull requests.` });
  return report;
}

Start it in the namespace of the end user it acts for, and wait up to 30 seconds for its result:

index.ts

import { readFile } from "node:fs/promises";

const script = await readFile(new URL("./scripts/repo-report.ts", import.meta.url), "utf8");
const run = await rewind.namespace("quickstart-user").runs.start({
  toolset: toolset.id,
  script,
  input: { repo: "nodejs/node" },
  wait: "30s",
  labels: { example: "quickstart" },
});

console.log(`run ${run.id}: ${run.status}`);
console.log(run.output?.value);
await worker.stop();

Read the result

[notify for quickstart-user] nodejs/node has 1326 open issues and pull requests.
run 01a1e12f-cd53-75ef-8e51-785602c9b0d6: completed
{ openIssues: 1326, pushedAt: '2026-11-15T19:15:27Z', repo: 'nodejs/node', stars: 123766 }

The script was type-checked against the toolset, ran in the sandbox, sent its request through the http tool and its notify call to your worker. Each of these is an entry in the run’s journal.

Look at the run

Open Observability in the dashboard and click the run. The debugger shows the script with each call next to the line that made it, a timeline, and a cursor that steps through the run’s history.

The debugger of a run: the source with each call beside its line, and the timeline

Next steps

Give it to your model

Plug run_script and the other agent tools into Claude or an OpenAI model.

Wait for a human

Signals, approvals, and runs that wait for days.

Connect your MCP servers

Toolsets, policies and credentials.

All the examples

Runnable programs for every part of the SDK.

Get started

How it works

Run Rewind

Next steps

Give it to your model

Wait for a human

Connect your MCP servers

All the examples