Descope Engine

The Descope Engine is a lightweight, deployable Docker image that allows Descope Connectors to reach resources that are not accessible from the public internet — for example, an internal HTTP API behind your firewall or a private database.

In order to use Descope Connectors against private resources, you must deploy and run this Engine within your own environment. Descope does not run the Engine for you in Descope's cloud.

How It Works

1. You create an Engine in the Descope Console and copy its Engine ID and Engine Key.
2. You run the Engine container in your network with those credentials. It opens a single outbound TLS connection to Descope (descope.fedstart.com:443) — no inbound ports.
3. When a flow invokes a connector assigned to that Engine, Descope sends the command over the open connection. The Engine executes it locally (for example, calling an internal API) and returns the result.

Supported Connectors on the Engine

These are a list of the connectors that are supported with the Descope Engine.

Quick Start

1. Create the Engine in the Descope Console and copy your Engine ID and Engine Key.
2. Set up and deploy the container — pull the image, configure your .env with those credentials, and run it.
3. Test the connection and assign connectors.

Step 1: Create the Engine in Descope

Create an Engine in the Descope Console and copy its credentials:

1. Open the Descope Console. Go to Connectors → Engines.

2. Create a new engine, or select an existing one if previously created.

3. Once created, you will need to copy the ID and Engine key from the Engine settings.

You will use these values when you configure and deploy the container in the next step.

Step 2: Set Up and Deploy the Engine

Configure and run

Before deploying, confirm your network allows the outbound connections described in Networking & Security.

Create an .env file with your credentials from Step 1:

# Required — from Connectors → Engines → Edit
ENGINE_ID=your-engine-id-here
ENGINE_SECRET=your-engine-key-here

# Descope Engine gRPC endpoint (FedRAMP / Gov)
SERVER_ADDRESS=descope.fedstart.com:443
USE_SSL=true

To modify the container image and change environment settings, you can review the Configuration reference section.

Then, you can get the container image from the following URL: https://hub.docker.com/r/descope/engine-client.

With that image version, you can deploy the container:

docker run -it --env-file .env descope/engine-client

For high availability, run the same image on multiple hosts or pods using the same ENGINE_ID and ENGINE_SECRET. See the Reconnect and high availability docs for more information.

Step 3: Associating the Connector with the Engine

You can associate a connector with an Engine by selecting the Engine in the connector configuration page.

1. Go to Connectors and open up the connector configuration.
2. Ensure that the connector
3. Select the Engine you created from the dropdown section called Engine.

Once you've successfully associated a connector with the Engine, you can look for gRPC stream established with server and Listening for commands in your Docker container logs:

Run an end-to-end test

1. Add the connector to a flow (or trigger the connector action you configured).
2. Run the flow and confirm the connector completes successfully.
3. Check Engine container logs for the execute command and response.

If the flow fails, see Troubleshooting.

Configuration Reference

All configuration is provided through environment variables you can set in your docker image.

Required

Connection & TLS

Timing & keepalive (optional)

Reconnection (optional)

Logging (optional)

Networking & Security

Review this section with your network and security teams before you deploy the Engine in production.

How traffic flows

The Engine runs in your environment and opens a single outbound gRPC connection to Descope over TLS. Descope never initiates inbound connections to your network. You do not need a public IP, load balancer, or inbound firewall rules for Descope to reach the Engine.

When a flow runs a connector assigned to that Engine, Descope sends the command over the existing connection. The Engine then calls resources inside your network (for example, an internal HTTP API) and returns the result to Descope over the same connection.

Firewall and egress

You will need to make sure that your network allows the FedRAMP static IPs, to be able to reach the Descope Engine.

The static IPs are documented here.

In addition, you will need to make sure that your network allows the outbound traffic to the Descope Engine:

If outbound access to descope.fedstart.com:443 is blocked, the Console shows Disconnected and connector actions cannot run. See Troubleshooting.

TLS and secrets

Runtime footprint

The Engine is stateless: it does not store customer data or require a database. Plan for container logs only; there is nothing to back up on the Engine itself.

Reconnect and High Availability

If the gRPC stream drops, the Engine retries with exponential backoff, sends Hello again, and resumes listening.

Run more than one container with the same ENGINE_ID and ENGINE_SECRET for HA. Descope dispatches each command to any connected container.

Troubleshooting

These are some of the most common issues and fixes for the Descope Engine.