Containers and VMs

You can deploy a Restate service in a container or on any virtual machine. The service runs as a separate process using the appropriate language runtime or as a compiled binary. By convention, it accepts HTTP connections on port 9080.

Docker

You can run your Restate service in a Docker container. Most of the Restate service templates come with a Dockerfile that you can use to build a Docker image for your service.

Connecting services with public endpoints

If your service has a public HTTPS endpoint, secure it with request identity validation so that it only accepts requests from the Restate environment you trust. First, obtain the environment’s request identity public key:

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

On macOS, install OpenSSL 3 with brew install openssl@3 and run the command with $(brew --prefix openssl@3)/bin/openssl instead.

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"

Then configure the public key in your SDK endpoint:

restate.serve({
  services: [myService],
  identityKeys: ["publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"],
});

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier;
import dev.restate.sdk.endpoint.Endpoint;
import dev.restate.sdk.http.vertx.RestateHttpServer;

class MySecureApp {
  public static void main(String[] args) {
    var endpoint =
        Endpoint.bind(new MyService())
            .withRequestIdentityVerifier(
                RestateRequestIdentityVerifier.fromKeys(
                    "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"));
    RestateHttpServer.listen(endpoint);
  }
}

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier
import dev.restate.sdk.http.vertx.RestateHttpServer
import dev.restate.sdk.kotlin.endpoint.endpoint

fun main() {
  RestateHttpServer.listen(
      endpoint {
        bind(MyService())
        requestIdentityVerifier =
            RestateRequestIdentityVerifier.fromKeys(
                "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f",
            )
      }
  )
}

app = restate.app(
    services=[my_service],
    identity_keys=["publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"],
)

if err := server.NewRestate().
  Bind(restate.Reflect(MyService{})).
  WithIdentityV1("publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f").
  Start(context.Background(), ":9080"); err != nil {
  log.Fatal(err)
}

use restate_sdk::endpoint::Endpoint;
use restate_sdk::http_server::HttpServer;

#[tokio::main]
async fn main() {
    HttpServer::new(
        Endpoint::builder()
            .bind(MyService)
            .identity_key("publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f")
            .unwrap()
            .build(),
    )
    .listen_and_serve("0.0.0.0:9080".parse().unwrap())
    .await;
}

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

restate deployments register <service-address>

Connecting private services to Restate Cloud or BYOC

Restate Cloud must be able to send discovery and invocation requests to your service. For a service in a private network, a tunnel establishes an outbound connection to Restate Cloud, so you do not need to expose an inbound endpoint. Choose your language and follow the steps to connect your service. TypeScript and Go use a tunnel client in the service process. Java, Kotlin, Python, and Rust use a standalone tunnel client container.

Use the in-process tunnel client to connect your TypeScript service directly to Restate Cloud.

Develop your service

Develop your service with the TypeScript SDK. If you are starting a new service, follow the quickstart.

Create the tunnel credentials

In the Restate Cloud UI:

Open Developers > API Keys and create an API key with the Full role.
Open Developers > Security > HTTP endpoints and copy the signing public key.
Copy the environment ID and region identifier shown in the UI.

Set the values as environment variables where you will run the service:

export RESTATE_ENVIRONMENT_ID=env_...
export RESTATE_AUTH_TOKEN=key_...
export RESTATE_TUNNEL_NAME=greeter-v1
export RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_...
export RESTATE_CLOUD_REGION=eu

Give each distinct deployment its own DNS friendly tunnel name. Replicas of the same deployment should share the same name. For a Restate managed region, use a value such as eu or us. For BYOC, use the region identifier shown in the UI.

Run the tunnel client

Install the tunnel package for your SDK:

TypeScript

npm install @restatedev/restate-sdk-tunnel

Replace the normal SDK listener with the tunnel client:

TypeScript

import { connectTunnel } from "@restatedev/restate-sdk-tunnel";
import { greeter } from "./greeter";

const connection = connectTunnel({
  region: process.env.RESTATE_CLOUD_REGION!,
  environmentId: process.env.RESTATE_ENVIRONMENT_ID!,
  authToken: process.env.RESTATE_AUTH_TOKEN!,
  signingPublicKey: process.env.RESTATE_SIGNING_PUBLIC_KEY!,
  tunnelName: process.env.RESTATE_TUNNEL_NAME!,
  services: [greeter],
});

connection.ready.then(() => {
  console.log(`Register this deployment: ${connection.deploymentUrl}`);
});

The TypeScript client exposes the deployment URL through connection.deploymentUrl.Request identity validation ensures that your service only accepts requests signed by the Restate Cloud or BYOC environment you trust. The tunnel SDK validates request identity with the signing public key. The public key is not secret, so it is safe to include it directly in your service source code or configuration files.

Copy the deployment URL printed when the tunnel connects and register it:

restate deployments register <deployment-url>

Use the in-process tunnel client to connect your Go service directly to Restate Cloud.

Develop your service

Develop your service with the Go SDK. If you are starting a new service, follow the quickstart.

Create the tunnel credentials

In the Restate Cloud UI:

Open Developers > API Keys and create an API key with the Full role.
Open Developers > Security > HTTP endpoints and copy the signing public key.
Copy the environment ID and region identifier shown in the UI.

Set the values as environment variables where you will run the service:

export RESTATE_ENVIRONMENT_ID=env_...
export RESTATE_AUTH_TOKEN=key_...
export RESTATE_TUNNEL_NAME=greeter-v1
export RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_...
export RESTATE_CLOUD_REGION=eu

Run the tunnel client

Install the tunnel package for your SDK:

go get github.com/restatedev/sdk-go/x/tunnel

Replace the normal SDK listener with the tunnel client:

package develop

import (
  "context"
  "log"
  "os"

  restate "github.com/restatedev/sdk-go"
  "github.com/restatedev/sdk-go/server"
  "github.com/restatedev/sdk-go/x/tunnel"
)

func serveWithTunnel() {
  srv := server.NewRestate().Bind(restate.Reflect(MyService{}))

  err := tunnel.NewTunnel(srv,
    tunnel.WithRegion(os.Getenv("RESTATE_CLOUD_REGION")),
    tunnel.WithEnvironment(
      os.Getenv("RESTATE_ENVIRONMENT_ID"),
      os.Getenv("RESTATE_SIGNING_PUBLIC_KEY"),
    ),
    tunnel.WithAuthToken(os.Getenv("RESTATE_AUTH_TOKEN")),
    tunnel.WithTunnelName(os.Getenv("RESTATE_TUNNEL_NAME")),
  ).Start(context.Background())
  if err != nil {
    log.Fatal(err)
  }
}

The Go client logs the deployment URL after connecting.Request identity validation ensures that your service only accepts requests signed by the Restate Cloud or BYOC environment you trust. The tunnel SDK validates request identity with the signing public key. The public key is not secret, so it is safe to include it directly in your service source code or configuration files.

Copy the deployment URL printed when the tunnel connects and register it:

restate deployments register <deployment-url>

Connect your Java service with the standalone tunnel client. It runs as a Docker container and forwards requests to your service’s HTTP endpoint.

Develop your service

Develop your service with the Java SDK. If you are starting a new service, follow the quickstart.By default, the service listens on port 9080. Make sure the tunnel container can reach it. You do not need to expose this endpoint to the public internet.

Secure your service with request identity validation

Request identity validation ensures that your service only accepts requests signed by the Restate Cloud or BYOC environment you trust.Configure the environment’s signing public key in your SDK endpoint:

Java

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier;
import dev.restate.sdk.endpoint.Endpoint;
import dev.restate.sdk.http.vertx.RestateHttpServer;

class MySecureApp {
  public static void main(String[] args) {
    var endpoint =
        Endpoint.bind(new MyService())
            .withRequestIdentityVerifier(
                RestateRequestIdentityVerifier.fromKeys(
                    "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"));
    RestateHttpServer.listen(endpoint);
  }
}

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

Run the tunnel client

Run the standalone tunnel client as a Docker container:

docker run \
  -e RESTATE_ENVIRONMENT_ID=env_... \
  -e RESTATE_AUTH_TOKEN=key_... \
  -e RESTATE_TUNNEL_NAME=greeter-v1 \
  -e RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_... \
  -e RESTATE_CLOUD_REGION=eu \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 9070:9070 \
  -it ghcr.io/restatedev/restate-cloud-tunnel-client:latest

Configure the environment variables as follows:

RESTATE_ENVIRONMENT_ID: Copy the environment ID shown in the Restate Cloud UI. It starts with env_.
RESTATE_AUTH_TOKEN: Create an API key with the Full role under Developers > API Keys. It starts with key_.
RESTATE_TUNNEL_NAME: Choose a DNS friendly name for this deployment. Replicas of the same deployment should share the same name.
RESTATE_SIGNING_PUBLIC_KEY: Copy the signing public key from Developers > Security > HTTP endpoints. It starts with publickeyv1_.
RESTATE_CLOUD_REGION: Use the region identifier shown in the UI, such as eu or us. For BYOC, use the BYOC region identifier.

The health check is available at :9090/health. The tunnel container must be able to reach your service’s HTTP endpoint.You can run the latest image tag or pin a specific version of the tunnel client, such as 0.4.0.

Local ingress and Admin API proxies

By default, the tunnel client exposes the Restate ingress on port 8080 and the Admin API on port 9070 through authenticating proxies. Restrict access to these ports because anyone who can reach them has the same access as the configured token.Set RESTATE_REMOTE_PROXY=false if you do not need these local proxies. You can then omit ports 8080 and 9070 from the Docker command.

restate deployments register \
  --tunnel-name <tunnel-name> \
  <service-address>

The tunnel client forwards discovery and invocation requests from Restate Cloud to this address.

Connect your Kotlin service with the standalone tunnel client. It runs as a Docker container and forwards requests to your service’s HTTP endpoint.

Develop your service

Develop your service with the Kotlin SDK. If you are starting a new service, follow the quickstart.By default, the service listens on port 9080. Make sure the tunnel container can reach it. You do not need to expose this endpoint to the public internet.

Secure your service with request identity validation

Kotlin

import dev.restate.sdk.auth.signing.RestateRequestIdentityVerifier
import dev.restate.sdk.http.vertx.RestateHttpServer
import dev.restate.sdk.kotlin.endpoint.endpoint

fun main() {
  RestateHttpServer.listen(
      endpoint {
        bind(MyService())
        requestIdentityVerifier =
            RestateRequestIdentityVerifier.fromKeys(
                "publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f",
            )
      }
  )
}

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

Run the tunnel client

Run the standalone tunnel client as a Docker container:

docker run \
  -e RESTATE_ENVIRONMENT_ID=env_... \
  -e RESTATE_AUTH_TOKEN=key_... \
  -e RESTATE_TUNNEL_NAME=greeter-v1 \
  -e RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_... \
  -e RESTATE_CLOUD_REGION=eu \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 9070:9070 \
  -it ghcr.io/restatedev/restate-cloud-tunnel-client:latest

Configure the environment variables as follows:

RESTATE_ENVIRONMENT_ID: Copy the environment ID shown in the Restate Cloud UI. It starts with env_.
RESTATE_AUTH_TOKEN: Create an API key with the Full role under Developers > API Keys. It starts with key_.
RESTATE_TUNNEL_NAME: Choose a DNS friendly name for this deployment. Replicas of the same deployment should share the same name.
RESTATE_SIGNING_PUBLIC_KEY: Copy the signing public key from Developers > Security > HTTP endpoints. It starts with publickeyv1_.
RESTATE_CLOUD_REGION: Use the region identifier shown in the UI, such as eu or us. For BYOC, use the BYOC region identifier.

Local ingress and Admin API proxies

restate deployments register \
  --tunnel-name <tunnel-name> \
  <service-address>

The tunnel client forwards discovery and invocation requests from Restate Cloud to this address.

Connect your Python service with the standalone tunnel client. It runs as a Docker container and forwards requests to your service’s HTTP endpoint.

Develop your service

Develop your service with the Python SDK. If you are starting a new service, follow the quickstart.By default, the service listens on port 9080. Make sure the tunnel container can reach it. You do not need to expose this endpoint to the public internet.

Secure your service with request identity validation

Python

app = restate.app(
    services=[my_service],
    identity_keys=["publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f"],
)

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

Run the tunnel client

Run the standalone tunnel client as a Docker container:

docker run \
  -e RESTATE_ENVIRONMENT_ID=env_... \
  -e RESTATE_AUTH_TOKEN=key_... \
  -e RESTATE_TUNNEL_NAME=greeter-v1 \
  -e RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_... \
  -e RESTATE_CLOUD_REGION=eu \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 9070:9070 \
  -it ghcr.io/restatedev/restate-cloud-tunnel-client:latest

Configure the environment variables as follows:

RESTATE_ENVIRONMENT_ID: Copy the environment ID shown in the Restate Cloud UI. It starts with env_.
RESTATE_AUTH_TOKEN: Create an API key with the Full role under Developers > API Keys. It starts with key_.
RESTATE_TUNNEL_NAME: Choose a DNS friendly name for this deployment. Replicas of the same deployment should share the same name.
RESTATE_SIGNING_PUBLIC_KEY: Copy the signing public key from Developers > Security > HTTP endpoints. It starts with publickeyv1_.
RESTATE_CLOUD_REGION: Use the region identifier shown in the UI, such as eu or us. For BYOC, use the BYOC region identifier.

Local ingress and Admin API proxies

restate deployments register \
  --tunnel-name <tunnel-name> \
  <service-address>

The tunnel client forwards discovery and invocation requests from Restate Cloud to this address.

Connect your Rust service with the standalone tunnel client. It runs as a Docker container and forwards requests to your service’s HTTP endpoint.

Develop your service

Develop your service with the Rust SDK. If you are starting a new service, follow the quickstart.By default, the service listens on port 9080. Make sure the tunnel container can reach it. You do not need to expose this endpoint to the public internet.

Secure your service with request identity validation

Rust

use restate_sdk::endpoint::Endpoint;
use restate_sdk::http_server::HttpServer;

#[tokio::main]
async fn main() {
    HttpServer::new(
        Endpoint::builder()
            .bind(MyService)
            .identity_key("publickeyv1_w7YHemBctH5Ck2nQRQ47iBBqhNHy4FV7t2Usbye2A6f")
            .unwrap()
            .build(),
    )
    .listen_and_serve("0.0.0.0:9080".parse().unwrap())
    .await;
}

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

Run the tunnel client

Run the standalone tunnel client as a Docker container:

docker run \
  -e RESTATE_ENVIRONMENT_ID=env_... \
  -e RESTATE_AUTH_TOKEN=key_... \
  -e RESTATE_TUNNEL_NAME=greeter-v1 \
  -e RESTATE_SIGNING_PUBLIC_KEY=publickeyv1_... \
  -e RESTATE_CLOUD_REGION=eu \
  -p 8080:8080 \
  -p 9090:9090 \
  -p 9070:9070 \
  -it ghcr.io/restatedev/restate-cloud-tunnel-client:latest

Configure the environment variables as follows:

RESTATE_ENVIRONMENT_ID: Copy the environment ID shown in the Restate Cloud UI. It starts with env_.
RESTATE_AUTH_TOKEN: Create an API key with the Full role under Developers > API Keys. It starts with key_.
RESTATE_TUNNEL_NAME: Choose a DNS friendly name for this deployment. Replicas of the same deployment should share the same name.
RESTATE_SIGNING_PUBLIC_KEY: Copy the signing public key from Developers > Security > HTTP endpoints. It starts with publickeyv1_.
RESTATE_CLOUD_REGION: Use the region identifier shown in the UI, such as eu or us. For BYOC, use the BYOC region identifier.

Local ingress and Admin API proxies

restate deployments register \
  --tunnel-name <tunnel-name> \
  <service-address>

The tunnel client forwards discovery and invocation requests from Restate Cloud to this address.

Running services behind a load balancer

To spread load across multiple instances of services and higher availability, we recommend using a load balancer. The Restate server does not currently support multiple endpoints for a single deployment. When running an L7 load balancer such AWS Application Load Balancer, be sure to configure it to support HTTP/2 as this enables Restate to use the more efficient bi-directional service invocation protocol.

Using nginx load balancer

When using nginx as the load balancer, you must use the grpc_pass directive instead of proxy_pass to forward requests to your services. The proxy_pass directive only speaks HTTP/1.1 to the upstream, which downgrades the connection and prevents Restate from using the bidirectional protocol. The grpc_pass directive keeps HTTP/2 end-to-end. You also need http2 on; on the listener so that nginx accepts HTTP/2 from Restate.

Expandable nginx.conf

events {}

http {
    server {
        # Plain HTTP + h2c (HTTP/1.1 and HTTP/2 prior knowledge)
        # In production, either remove this plain HTTP listener or redirect it
        # to HTTPS (note: HTTP/2 prior-knowledge clients won't follow redirects).
        listen 80;
        http2 on;
        server_name _;

        client_max_body_size 0;

        location / {
            grpc_pass grpc://app:9080;
            grpc_set_header   Host              $host;
            grpc_set_header   X-Real-IP         $remote_addr;
            grpc_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
            grpc_set_header   X-Forwarded-Proto $scheme;
        }
    }

    server {
        # HTTPS + HTTP/2 (HTTP/1.1 and HTTP/2 via ALPN)
        listen 443 ssl;
        http2 on;
        server_name _;

        ssl_certificate     /etc/nginx/certs/server.crt;
        ssl_certificate_key /etc/nginx/certs/server.key;

        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         HIGH:!aNULL:!MD5;

        client_max_body_size 0;

        location / {
            grpc_pass grpc://app:9080;
            grpc_set_header   Host              $host;
            grpc_set_header   X-Real-IP         $remote_addr;
            grpc_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
            grpc_set_header   X-Forwarded-Proto $scheme;
        }
    }
}

SDKs

Services

Restate Cloud / BYOC / OSS

References

Containers and VMs

Docker

Connecting services with public endpoints

Connecting private services to Restate Cloud or BYOC

Running services behind a load balancer

​Docker

​Connecting services with public endpoints

​Connecting private services to Restate Cloud or BYOC

​Running services behind a load balancer

Docker

Connecting services with public endpoints

Connecting private services to Restate Cloud or BYOC

Running services behind a load balancer