Runback
Docs menuQuickstart: TypeScript

    ↑↓ move ↵ open esc close

    Docs Start

    Quickstart: TypeScript

    Record one OpenAI call from a Node.js script as a Runback run, then open it in the app. About five minutes.

    Before you begin

    • A Runback account. Create one free.
    • Node.js 20 or later. Check with node --version.
    • An OpenAI API key, set as OPENAI_API_KEY. No OpenAI key? Step 4 has a test command that needs none.

    Steps

    1. Get a Runback key

      A key tells Runback which workspace a run belongs to. Use a Send only key: it can send runs and nothing else.In the app, open Settings › Keys and access › API key, keep Send only selected, select Generate API key and copy it. It is shown once, and starts rb_cloud_. Creating keys needs a workspace admin; whoever created the workspace is one.

      Checking your session…

    2. Install the SDK

      In your project folder (or a new one), install Runback's SDK and the OpenAI client it wraps.

      terminalShell
      npm install @runback/sdk openai
      Expected output

      npm finishes with a line such as added 2 packages and no errors.

    3. Put your key in your shell

      Runback's SDKs and the test script read the key from the RUNBACK_API_KEY environment variable. Replace the placeholder with the key from step 1. If you signed in, step 1 has already filled it in.

      terminalShell
      export RUNBACK_API_KEY="<RUNBACK_API_KEY>"
      Expected output

      Nothing is printed. To check it is set, run echo $RUNBACK_API_KEY; it should print your key, starting rb_cloud_.

    4. Record a model call

      Save this as agent.mjs and run it with OPENAI_API_KEY set. It makes one OpenAI call through the wrapped client, so the call is recorded as a run named quickstart-agent.

      agent.mjsJavaScript
      // agent.mjs: run with OPENAI_API_KEY=sk-... node agent.mjs
import OpenAI from "openai";
import { startRun } from "@runback/sdk/core";
import { wrapOpenAI } from "@runback/sdk/openai";

const task = "Say hello in three words.";
const run = startRun({ runName: "quickstart-agent", input: task });
const openai = wrapOpenAI(new OpenAI(), run);

const res = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: task }],
});
const answer = res.choices[0].message.content;

await run.finish({ output: answer, status: "success" });
console.log(answer);
      terminalShell
      OPENAI_API_KEY=sk-... node agent.mjs
      Expected output

      The model's short reply, for example Hello there, friend. and nothing else. A line starting [runback] means the run was not sent: see Troubleshooting below.

      No OpenAI key? Skip this step and send a test run instead. It uses the RUNBACK_API_KEY you exported and installs nothing.

      terminalShell
      curl -fsSL https://runback.dev/api/quickstart | bash

    5. Check the run arrived

      Open Runs in the app. Your run is at the top, named quickstart-agent. Open it to step through what the agent did.

    Troubleshooting

    You seeWhat it meansFix
    [runback] no RUNBACK_API_KEY set — dropped 3 eventsThe key is not set in the terminal you ran the agent from.Run step 3 again in the same terminal (a new terminal tab starts without it), then run the agent again.
    [runback] ingest failed 401 {"error":"Invalid API key"}Runback rejected the key: mistyped, revoked or expired.Copy the whole key again, or create a new one in Settings › Keys and access › API key.
    OpenAIError: Missing credentialsOPENAI_API_KEY is not set.Run the agent as OPENAI_API_KEY=sk-... node agent.mjs, or use the test-run command under step 4.
    AuthenticationError: 401 Incorrect API key providedOpenAI rejected your OpenAI key (not your Runback key).Check the key at platform.openai.com.
    Failed to load the ES module (Node 22+) or SyntaxError: Cannot use import statement outside a module (Node 20)The file is not treated as an ES module.Name it agent.mjs (not .js), or add "type": "module" to package.json.
    The agent printed its reply but the run is not in RunsThe key belongs to a different workspace, or you are looking at the shared demo.Check the workspace name in the top right of the app is the one the key came from.

    Your agent never fails because of Runback: if recording fails, the model call still returns and Runback prints one [runback] line saying why.

    What the wrapper records

    wrapOpenAI records every chat.completions and responses call: messages, system prompt, tools, parameters, the response, tool calls, tokens and latency, streamed or not. Your model call itself is unchanged, and nothing is stopped unless you add a policy. Emails, card numbers and keys are redacted inside your process before anything is sent; pass redact: false to startRun to turn that off.

    Next steps

    • Using the Vercel AI SDK, Anthropic or LangGraph? See Integrations.
    • See what the run you sent contains: Capture.
    • Stop a risky tool call before it runs: Control.
    • Self-hosting Runback? Keys that do not start rb_cloud_ send to http://localhost:3000 unless you set RUNBACK_INGEST_URL to your server.
    Last updated 2 Nov 2026.