Skip to main content

Retool RPCBeta

Learn how to connect your own codebase to Retool and call server-side functions from Retool apps.

info

Retool currently supports JavaScript and Python SDKs.

Reach out to your Retool account manager to access Retool RPC on self-hosted Retool 3.38 Edge versions and earlier.

Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.

With Retool RPC, you can:

Get started​

To start using Retool RPC, you need to:

  1. Create an RPC resource on Retool so Retool apps can communicate with your server.
  2. Generate an access token to authorize your server so it can communicate with Retool.
  3. Register a server with Retool's SDK to expose server-side functions to Retool and to handle function calls.

RPC Architecture

You can register a server with the Retool command line interface (CLI) or set it up yourself with an existing project. The CLI option is recommended for initial testing.

Set up Retool RPC with Retool CLI​

info

Node.js is required to use the CLI.

The CLI is the easiest way to get started with Retool RPC. It automatically generates a resource and RPC server for you. You can use it to quickly test out Retool RPC and then migrate to a more permanent solution.

To setup Retool RPC with the CLI, run the following commands in your terminal.

# Log into your Retool organization
npx retool-cli login

# Follow the step by step instructions to create a resource and register a server
npx retool-cli rpc

Set up Retool RPC in an existing project​

If you already have a project, you can register a server with Retool's SDK. This is the recommended way to set up Retool RPC for production.

1. Create an RPC resource​

Sign in to your Retool organization and create a Retool RPC resource.

After creating the resource, Retool provides instructions and a code snippet. In the code snippet, notice the resourceId is already populated for you.

Retool RPC Resource Form

2. Generate an access token​

Create an access token with the RPC scope by navigating to your access tokens page. Save this token somewhere safe since you'll need it to register your server.

Retool RPC Access Token

3. Register a server with Retool's SDK​

Copy the code snippet from the resource form instructions into a file that can access your codebase. Be sure to populate all fields (e.g., replace the apiToken with the token you generated in the previous step) and install relevant dependencies.

warning

If you're a cloud customer and your server is running in a private network, you may need to allow outbound traffic to Retool IP addresses.

Run the file to register your server with Retool. This file serves as the entry point to your codebase and must be running for Retool to communicate with your code.

Interact with your codebase​

After registering your server with Retool, you can interact with your codebase. Define functions through your registered server, fill in the implementation, and then call the function from Retool apps.

Define server-side functions​

warning

Be sure to restart your server to pick up any changes to your registered functions.

Retool RPC allows you to customize functions with any number of arguments. Currently supported argument types are: string, number, boolean, json, and array. You can also specify whether an argument is required or optional.

// server.js

rpc.register({
  name: "randomFunction",
  arguments: {
    stringInput: {
      type: "string",
      description: "A required string input",
      required: true,
    },
    numberInput: {
      type: "number",
      description: "A required number input",
      required: true,
    },
    booleanInput: { type: "boolean", description: "An optional boolean input" },
    jsonInput: { type: "json", description: "An optional json input" },
    stringArrayInput: {
      type: "string",
      array: true,
      description: "An optional string array input",
    },
    jsonArrayInput: {
      type: "json",
      array: true,
      description: "An optional json array input",
    },
  },
  implementation: async (args, context) => {
    console.log(args.stringInput);
    console.log(context.userEmail);
    // Use parts of your codebase here
  },
});

The args parameter contains the arguments passed in from Retool, and the context parameter contains information about the user that called the function. Fill in the implementation of the function. Since this server connects to your codebase, you can use your existing infrastructure (ORM frameworks, helper functions, logging, testing, CI/CD, etc.) to enhance the developer experience.

Call server-side functions from Retool​

After registering server-side functions, you can call them from Retool apps like any other resource. Search for the RPC resource you created and select the function you want to call. Retool automatically generates a form for you to fill in the arguments.

RPC Query

Enter the arguments and click Run to execute the function. Retool automatically checks the argument passed and displays an error if the types don't match or required fields are missing.

Configure function permissions​

You can configure permissions to control access to exposed functions within your organization. Unlike private APIs that require you to build your own authentication middleware, Retool RPC makes it easy to enforce user or group-level access to functions.

rpc.register({
  name: "randomFunctionWithPermissions",
  arguments: {
    stringInput: { type: "string", description: "A string input" },
  },
  permissions: {
    userEmails: ["hello@world.com"],
    groupNames: ["Hello world group"],
  },
  implementation: async (args, context) => {
    return "Hello world!";
  },
});

By default, all functions are accessible to all users. If a userEmails or groupNames field is specified, only users with the specified email or in the specified group can call the function. If both are provided, users only need to satisfy one condition.

RPC Permissions Error

Schema versioning​

Retool RPC supports schema versioning to ensure exposed functions are always up-to-date. If you check Require explicit version on the resource form, you will have to increment the version on every server change. This is to ensure non-conflicting changes if multiple people are testing different schemas with the same resource.

Retool RPC Enable Explicit Versioning

const rpc = new RetoolRPC({
  apiToken: 'API_TOKEN',
  host: 'HOST',
  resourceId: 'RESOURCE_ID',
  version: '0.0.1', // Increment this on every server change e.g., 0.0.1 -> 0.0.2 -> 0.0.3
})

If left unchecked, Retool uses the last registered server's schema. This is useful for early development where you want to quickly iterate on your functions.

Retool prompts users to refresh their schema if they are running queries against an outdated schema. This can be done by clicking the refresh button on the Schema tab or by refreshing the page.

Retool RPC Refresh Schema

Architecture and security​

Retool RPC is an outbound-only architecture, which means the registered server only makes outbound requests to Retool and never receives inbound requests.

On every start up, the RPC server registers itself and the functions it exposes to Retool. After that completes, the RPC server continuously polls for new requests from Retool in the following flow:

RPC Architecture

Retool stores query requests and responses in a messaging queue. The direction of the arrows represents the direction of the request. The blue arrows represent Pop Query requests, which poll for Run Query requests. The black arrows are Run Query requests, which are made by calling functions in the Retool UI. When a Pop Query request detects a Run Query request, it interacts with your codebase and then initiates the red flow. This sends a Post Query Response to respond to the original Run Query request.

Only making outbound requests ensures your codebase is never exposed to the internet, and that your data is secure.

Other security measures include:

  • Retool requires a valid access token and resource access for all RPC-related requests.
  • Each resource is given a different queue to ensure isolation between resources.