Vercel

Deploy your Restate services on Vercel. This guide covers project configuration, service registration, and security setup.

Follow the quickstart to try Next.js and Restate locally.

Deploying to Vercel

Set up your project

New project
Existing Next.js project

Start from the template:

Create your Restate + Vercel repository

Create a fetch endpoint, providing the services:

import * as restate from "@restatedev/restate-sdk/fetch";
import { greeter } from "@/restate/greeter";

// Create the Restate endpoint. 
// Here you need to register your services
const endpoint = restate.createEndpointHandler({ services: [greeter] });

// Adapt it to Next.js route handlers
export const serve = () => {
  return {
    POST: (req: Request) => endpoint(req),
    GET: (req: Request) => endpoint(req),
  };
};

And expose the endpoint in a Next.js parameterized route, e.g. /restate/[[...services]]:

import { serve } from "@/restate/serve";

// This is the route that exposes the Restate services.
// You can register it to Restate using /restate subpath (check the README)
// To call it, open Restate > Overview > Greeter > Playground
export const { GET, POST } = serve();

Secure your service with request identity validation

Vercel deployments are public HTTP endpoints. Secure your service with request identity validation so that it only accepts requests from the Restate environment you trust.

Restate Cloud / BYOC
Restate OSS

Restate Cloud and BYOC environments create and manage the request identity key for you.Copy the environment’s public key from Developers > Security > HTTP endpoints in the Restate Cloud UI.

Request identity uses an ED25519 key pair. Give the private key to Restate so it can sign requests, and give the public key to your services so they can verify those signatures.Choose one of the following ways to generate the keys:

Option 1: Let Restate output the public key

Generate the private key:

openssl genpkey -algorithm ed25519 -outform pem -out private.pem

Provide its path to Restate on startup:

export RESTATE_REQUEST_IDENTITY_PRIVATE_KEY_PEM_FILE=private.pem

Start Restate and copy the corresponding public key from the startup log. Restate prints it in the compact format expected by the SDK:

INFO restate_service_client::request_identity::v1
Loaded request identity key
kid: "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"
path: private.pem

Option 2: Generate both key files beforehand

Run this script to generate private.pem and write the corresponding publickeyv1_... value to a public-key file before starting Restate:

macOS
Linux

Install OpenSSL 3 with Homebrew, then run the script:

brew install openssl@3

generate.sh

#!/usr/bin/env bash
set -euo pipefail

openssl_bin="$(brew --prefix openssl@3)/bin/openssl"

# generate private key
"$openssl_bin" genpkey -algorithm ed25519 -outform pem -out private.pem
echo "Wrote private key to private.pem"

# encode public key
encoded=$("$openssl_bin" pkey -in private.pem -pubout -outform DER 2>/dev/null |
tail -c +13 |
od -An -v -tu1 |
awk '
BEGIN {
  alphabet = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
  leading = 1
}
{
  for (i = 1; i <= NF; i++) {
    byte = $i
    if (leading && byte == 0) {
      zeroes++
      continue
    }
    leading = 0
    carry = byte
    for (j = 0; j < digit_count; j++) {
      carry += digits[j] * 256
      digits[j] = carry % 58
      carry = int(carry / 58)
    }
    while (carry > 0) {
      digits[digit_count++] = carry % 58
      carry = int(carry / 58)
    }
  }
}
END {
  for (i = 0; i < zeroes; i++) printf "1"
  for (i = digit_count - 1; i >= 0; i--) {
    printf "%s", substr(alphabet, digits[i] + 1, 1)
  }
}')

echo -n "publickeyv1_${encoded}" > public-key
echo "Wrote publickeyv1_${encoded} to public-key"

This script requires Bash, OpenSSL, awk, and GNU Coreutils:

generate.sh

#!/usr/bin/env bash
set -euo pipefail

# generate private key
openssl genpkey -algorithm ed25519 -outform pem -out private.pem
echo "Wrote private key to private.pem"

base58_chars="123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
# encode public key
encoded=$(openssl ec -in private.pem -inform pem -pubout -outform der -out /dev/stdout 2>/dev/null |
tail -c +13 |
basenc --base16 "${1:-/dev/stdin}" -w0 |
if
read
[[ $REPLY =~ ^((00)*)(([[:xdigit:]]{2})*) ]]
echo -n "${BASH_REMATCH[1]//00/1}" # leading 0s -> 1
(( ${#BASH_REMATCH[3]} > 0 ))
then
dc -e "16i0${BASH_REMATCH[3]^^} Ai[58~rd0<x]dsxx+f" | # hex bytes to indexes into the char string
while read -r
do echo -n "${base58_chars:REPLY:1}"
done
fi)

echo -n "publickeyv1_${encoded}" > public-key
echo "Wrote publickeyv1_${encoded} to public-key"

Clone the project locally and configure the key in your Restate SDK endpoint before deploying.

const handler = restate.createEndpointHandler({
  services: [myService],
  identityKeys: ["publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"],
});

The public key is not secret, so it is safe to include it directly in your service source code or configuration files.

Deploy your project to Vercel

Create and deploy the project from the Vercel dashboard.For Restate to push requests to the Vercel project, you need Vercel Generated URLs to be accessible by Restate. You have two alternatives:

Disable Vercel Authentication for the project, making its URLs publicly accessible.
Enable Protection Bypass for Automation. This makes the URLs accessible only if the x-vercel-protection-bypass header is provided with the right value.

Get your Commit URL

Go to your Vercel deployment and copy the Commit URL (highlighted in black on the screenshot).

This lets that Restate address specific Vercel deployments, and handle versioning for you.

Register the service to Restate

Restate Cloud / BYOC
Restate OSS

In the advanced options, enable HTTP1.1 and optionally, set the header for the deployment protection bypass:

Read the CICD Automation section to set up automatic service registration on push to main.

Send your first request

Restate Cloud / BYOC
Restate OSS

You’re set up! Go to the Overview page > Greeter > Playground and start sending requests to your service.

CI/CD Automation

You can set up automation to automatically register new Restate service versions every time a Vercel deployment gets promoted.

If you’ve followed the steps above, then you already have the GitHub Actions workflow set up. All you need to do is to add the secrets below to your project.

Restate Cloud / BYOC
Restate OSS

.github/workflows/deploy.yml

name: Register to Restate

on:
  repository_dispatch:
    types:
      - 'vercel.deployment.promoted'
jobs:
  deploy-to-restate:
    if: github.event_name == 'repository_dispatch'
    runs-on: ubuntu-latest
    steps:
      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}

        run: |
          npx -y @restatedev/restate deployment register -y \
            --use-http1.1 \
            ${{ secrets.VERCEL_PROTECTION_BYPASS_TOKEN && format('--extra-header x-vercel-protection-bypass={0}', secrets.VERCEL_PROTECTION_BYPASS_TOKEN) }} \
            ${{ github.event.client_payload.url }}/restate

This workflow needs the following GitHub Actions repository secrets:

RESTATE_ADMIN_URL: The Admin URL. You can find it in Developers > Admin URL
RESTATE_AUTH_TOKEN: Your Restate Cloud or BYOC auth token. To get one, go to Developers > API Keys > Create API Key, and make sure to select Admin for the role
View
VERCEL_PROTECTION_BYPASS_TOKEN: Only if you set up the Protection Bypass for Automation as described above.

.github/workflows/deploy.yml

name: Register to Restate

on:
  repository_dispatch:
    types:
      - 'vercel.deployment.promoted'
jobs:
  deploy-to-restate:
    if: github.event_name == 'repository_dispatch'
    runs-on: ubuntu-latest
    steps:
      - name: Register Restate deployment
        env:
          RESTATE_ADMIN_URL: ${{ secrets.RESTATE_ADMIN_URL }}
          RESTATE_AUTH_TOKEN: ${{ secrets.RESTATE_AUTH_TOKEN }}

        run: |
          npx -y @restatedev/restate deployment register -y \
            --use-http1.1 \
            ${{ secrets.VERCEL_PROTECTION_BYPASS_TOKEN && format('--extra-header x-vercel-protection-bypass={0}', secrets.VERCEL_PROTECTION_BYPASS_TOKEN) }} \
            ${{ github.event.client_payload.url }}/restate

This workflow needs the following GitHub Actions repository secrets:

RESTATE_ADMIN_URL: The URL through which GitHub Actions can reach your Restate Admin API
RESTATE_AUTH_TOKEN: Set this token if GitHub Actions reaches the Admin API through a reverse proxy that accepts bearer token authentication.
VERCEL_PROTECTION_BYPASS_TOKEN: Only if you set up the Protection Bypass for Automation as described above.

SDKs

Services

Restate Cloud / BYOC / OSS

References

Deploying to Vercel

Set up your project

Create your Restate + Vercel repository

Secure your service with request identity validation

Deploy your project to Vercel

Get your Commit URL

Register the service to Restate

Send your first request

CI/CD Automation

​Deploying to Vercel

Set up your project

Create your Restate + Vercel repository

Secure your service with request identity validation

Deploy your project to Vercel

Get your Commit URL

Register the service to Restate

Send your first request

​CI/CD Automation

Deploying to Vercel

CI/CD Automation