Skip to main content

Rivet Integration Getting Started

Welcome to the starting guide for integrating Rivet into your application! Currently, we only support integration via Node.js using the @ironclad/rivet-node package.


Install using your preferred package manager:

Install using Yarn:

yarn add @ironclad/rivet-node

Getting Started

Once Rivet is installed, you can import it into your application:

import * as Rivet from '@ironclad/rivet-node';

Using runGraphInFile

The simplest way to get started with Rivet is by using the runGraphInFile function. This function allows you to execute a graph defined in a Rivet project file.

runGraphInFile Parameters

The runGraphInFile function takes two parameters:

  1. path: A string representing the path to your Rivet project file.
  2. options: An object of type RunGraphOptions.


The RunGraphOptions type is used to pass various parameters to the runGraphInFile function. Here is what it looks like:

export type RunGraphOptions = {
graph: string;
inputs?: Record<string, LooseDataValue>;
context?: Record<string, LooseDataValue>;
remoteDebugger?: RivetDebuggerServer;
nativeApi?: NativeApi;
externalFunctions?: {
[key: string]: ExternalFunction;
onUserEvent?: {
[key: string]: (data: DataValue | undefined) => void;
abortSignal?: AbortSignal;
} & {
[P in keyof ProcessEvents as `on${PascalCase<P>}`]?: (params: ProcessEvents[P]) => void;
} & Settings;

Let's break down the important fields:

  • graph: Specifies the graph you're running. This can either be the ID or the display name of the graph.
  • inputs: Specifies the input values to the graph. These can either be plain JavaScript values like "foo", or {type: 'string', value: 'foo'} objects.
  • context: Similar to inputs, but these values are available to every graph and subgraph.
  • externalFunctions: This is how you define integration points that you can call from inside Rivet graphs.
  • openAiKey: Your OpenAI API key. This is required if you're using any Chat nodes in your graph.
  • openAiOrganization: If you are using a non-default OpenAI organization, you may specify your organization here.

Example Code

Here's a basic example of using runGraphInFile:

import { runGraphInFile, DataValue } from '@ironclad/rivet-node';

await runGraphInFile('./myProject.rivet', {
graph: 'My Graph Name',
inputs: {
myInput: 'hello world',
context: {
myContext: 'global value',
externalFunctions: {
helloWorld: async (...args: unknown[]): Promise<DataValue> => {
return {
type: 'string',
value: 'hello world',
onUserEvent: {
myEvent: (data: DataValue): Promise<void> => {
openAiKey: 'my-openai-key',
openAiOrganization: 'my-organization',

Remote Debugging

See the Remote Debugging page for more information on how to set up the remote debugger.

See Also