Edge Server is currently in preview. It is not recommended for production use.
Ditto Edge Server is a lightweight standalone server for resource-constrained edge environments, based on the core Ditto Edge SDK. With Ditto Edge Server, you can join devices as small as a Raspberry Pi to a local mesh network and synchronize data across edge environments.

​
Prerequisites

Edge Server does not currently support Windows. But it can run in a Docker container using Windows Subsystem for Linux (WSL).
  • Ditto SDK Connection Details from the Ditto Portal
  • Docker on a host that supports linux/arm64 or linux/amd64 platforms using a containerd image store.
  • A Linux Arm64 or Linux x86 host if installing native binaries.

​
Installation Methods

You can run the Ditto Edge Server as either a Docker container or a pre-built binary. Choose the method that best fits your environment.

​
Option 1: Install the Edge Server as a Docker Container

 export TARGET=x86_64-unknown-linux-gnu # For linux/amd64 platform
 export TARGET=aarch64-unknown-linux-gnu # For linux/arm64 platform
 export DATE=2025-08-20  # Use the latest available date or check with your Ditto contact
 URL="https://edge-server-nightlies.s3.us-east-1.amazonaws.com/${DATE}/ditto-edge-server-container_${TARGET}.tar"   

 curl --fail -L "$URL" -o edge-server-image.tar
 docker load -i edge-server-image.tar
 # Tag the image for convenience (replace <image-id> with the actual ID):
 docker tag <image-id> edge-server-container:latest

​
Option 2: Download the Edge Server Binary

 export TARGET=x86_64-unknown-linux-gnu
 export DATE=2025-08-20  # Use the latest available date or check with your Ditto contact
 URL="https://edge-server-nightlies.s3.us-east-1.amazonaws.com/${DATE}/ditto-edge-server_${TARGET}"   

 curl --fail -L "$URL" -o edge-server
 chmod +x edge-server

​
Configuration

To run Edge Server, you need a configuration file in YAML format. You can find a sample config in the Ditto quickstart apps repository as a starting point. This file will contain your Ditto Application ID and other settings, including http server configuration, debug level and mesh network transport configuration.

​
Running Edge Server

​
Option 1: Run the Edge Server as a Docker Container

docker run \
  -rm \
  -p 127.0.0.1:8080:8080 \
  -v ./<your_config>.yaml:/config.yaml edge-server-container:latest \
  run -c /config.yaml

​
Option 2: Run the Edge Server as a Pre-Built Binary

./edge-server -c ./<your_config>.yaml

​
Small Peers Only

Small Peers Only mode is a connection configuration type that restricts the Edge Server to only synchronize with other small peers in the mesh network over LAN, BLE, and other local transport protocols. The HTTP API is still accessible in this mode. See HTTP Server Configuration If you are using the Edge Server in a small peer only mode, you can use the following configuration: 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    auth:
      small_peers_only:
        offline_license_token: "YOUR_TOKEN_HERE"
  my_ditto_subscription:
    resource_type: DittoSubscription
    db_ids:
      - "YOUR_APP_ID"
    query: "SELECT * FROM tasks"

​
Cloud Sync

The Edge Server can authenticate with Ditto Server (either Cloud or self-hosted Operator) using a variety of methods, including API keys and OAuth tokens. You will need to provide the appropriate credentials in your configuration file. If your app is configured in Playground mode (i.e., development mode), use the following credentials:
  • db_id: Also known as “AppID”
  • access_token: Your app’s unique Playground Token
  • provider: If using Online Playground mode, use __playgroundProvider as your provider.
  • auth_url: The URL for the Ditto Playground authentication service, typically https://YOUR-AUTH-URL.dittolive.app
Replace the values with your actual Ditto AppID and Token from the Ditto Portal. 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    auth:
      server:
        access_token: "YOUR_TOKEN"
        auth_url: "https://YOUR-AUTH-URL.cloud.dittolive.app"
        provider: "__playgroundProvider"
  my_ditto_subscription:
    resource_type: DittoSubscription
    db_ids:
      - "YOUR_APP_ID"
    query: "SELECT * FROM tasks"

​
HTTP Server Configuration

To expose an HTTP Server, add the HttpServer resource to your configuration file. This resource will expose the given local database over HTTP, allowing you to query and manipulate data using standard HTTP methods. 
resources:
  my_ditto_db:
    resource_type: DittoDatabase
    db_id: "YOUR_APP_ID"
    device_name: "edge-device-1"
    auth:
      small_peers_only:
        offline_license_token: "YOUR_TOKEN_HERE"
  my_ditto_subscription:
    resource_type: DittoSubscription
    db_ids:
      - "YOUR_APP_ID"
    query: "SELECT * FROM tasks"
  my_http_server:
    resource_type: HttpServer
    db_id: "YOUR_APP_ID"
    base_path: my_server
    http_api: true
    listen_addr: "0.0.0.0:8080"

​
Authentication & Permissions

When using Small Peer Only mode or Playground mode, all reads and writes are permitted. If you need more granular control over permissions, you can use Ditto’s authentication webhook provider system, which is configurable in the Ditto Portal. Edge server is compatible with these webhook providers. You
can configure connections to your webhook provider by providing the applicable token and provider name in the edge server configuration file. To learn more about custom authentication, see the Authentication Guide.

​
Troubleshooting

Refer to the SDK Troubleshooting Guide for more help.
  • Permission denied: Make the binary executable (chmod +x edge-server).
  • Port already in use: Change the -p flag in the Docker command to use a different port.
  • Configuration errors: Double-check your YAML file for typos or missing fields.
  • Log files: See the Logging Configuration guide for details on controlling log verbosity and output.

​
Configuration Options

Edge Server offers several optional configuration settings: