> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rewind.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Register a toolset, serve a host tool, run a script and read its result.

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`](https://github.com/planchon/rewind.codes/tree/main/examples/quickstart).

**1. Get an API key**

Sign in to the dashboard at [app.rewind.codes](https://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](https://mintcdn.com/rewind/WThuBH7lRjVmKt9-/images/dashboard/organization-api-key-created-light.webp?fit=max\&auto=format\&n=WThuBH7lRjVmKt9-\&q=85\&s=b2ee573098b3f17adaf2719985623f78)

Running your own server instead? See [Self-hosting](https://docs.rewind.codes/self-hosting.md): the steps below are the same with its URL.

**2. Install the SDK**

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

```bash npm theme={null}
npm install @rewind.codes/sdk
```

```bash pnpm theme={null}
pnpm add @rewind.codes/sdk
```

The client reads its server and key from the environment:

```bash theme={null}
export REWIND_URL=https://api.rewind.codes
export REWIND_API_KEY=rewind_sk_...
```

**3. Register a toolset**

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.

```ts index.ts theme={null}
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:

```text theme={null}
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`.
```

**4. 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.

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

**5. Run a script**

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

```ts scripts/repo-report.ts theme={null}
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:

```ts index.ts theme={null}
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();
```

**6. Read the result**

```text theme={null}
[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.

**7. 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](https://mintcdn.com/rewind/WThuBH7lRjVmKt9-/images/dashboard/run-debugger-light.webp?fit=max\&auto=format\&n=WThuBH7lRjVmKt9-\&q=85\&s=47cfc7abf8d9fab2885fdf19abcf0ef3)

## Next steps

> [card] [Give it to your model](https://docs.rewind.codes/sdk/agent-tools.md)
>
> Plug `run_script` and the other agent tools into Claude or an OpenAI model.

> [card] [Wait for a human](https://docs.rewind.codes/sdk/human-in-the-loop.md)
>
> Signals, approvals, and runs that wait for days.

> [card] [Connect your MCP servers](https://docs.rewind.codes/sdk/toolsets.md)
>
> Toolsets, policies and credentials.

> [card] [All the examples](https://docs.rewind.codes/sdk/examples.md)
>
> Runnable programs for every part of the SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.