Skip to main content
The SPIN Runtime executes notebook code within your infrastructure. It is built on a Python-based Jupyter server with Docker containerization, featuring custom cell processors for each integration. You can deploy it on Docker, Kubernetes, or cloud instances.

​
Communication with the Runtime

Communication with the spin runtime is done via a websocket connection from the browser. The runtime does not need to be reachable by the SPIN’s cloud hosted control plane. For more information see our architecture docs. When adding a new runtime via the SPIN UI, you have to specify the URL of the runtime. When sharing a runtime across your team, you will need to host the runtime in a way that is reachable by all those members. Making it accessible from the internet via a public URL is an option. Constraining access to the runtime via a VPN (such as Tailscale) or an SSH tunnel is another option that can enhance security.
Note that for runtimes not running on the users machine directly require a secure connection via HTTPS with a valid certificate. This is because the browser will not allow the runtime to connect to a non-secure origin unless the origin is localhost. See Enabling HTTPS for the Runtime for detailed instructions on how to configure SSL certificates.

​
Deploy in Your Own Infrastructure

A Docker image is available for deployment in your own environment: 
ghcr.io/siftd/spin-runtime:latest-prod

​
Docker

Run the runtime as a standalone container: 
docker run -d --name spin-runtime -p 8888:8888 \
           -v spin-runtime-data:/opt/spin/var \
           -e SPIN_TOKEN=your-secure-token \
           ghcr.io/siftd/spin-runtime:latest-prod

​
Docker Compose

Example configuration for Docker Compose:
compose.yml
services:
  spin-runtime:
    image: ghcr.io/siftd/spin-runtime:latest-prod
    environment:
      - SPIN_TOKEN=your-secure-token
    ports:
      - "8888:8888"
    volumes:
      - spin-runtime-data:/opt/spin/var
    restart: unless-stopped

volumes:
  spin-runtime-data:
    driver: local

Set up with Tailscale

With Tailscale you can access the SPIN runtime without exposing it to the public internet. See how to configure SPIN runtime with Tailscale sidecar in Docker Compose.

Set up with Cloudflare Tunnels

With Cloudflare Tunnels you can access the SPIN runtime without exposing it to the public internet. See how to configure SPIN runtime with Cloudflare Tunnels in Docker Compose.

​
Kubernetes

TODO: Add instructions for deploying in Kubernetes.

​
Upgrading the Runtime

When new versions of the SPIN runtime are released, you’ll need to update your deployment to use the latest image.

​
Docker

For standalone Docker containers: 
# Stop and remove the existing container
docker stop spin-runtime
docker rm spin-runtime

# Pull the latest image
docker pull ghcr.io/siftd/spin-runtime:latest-prod

# Start a new container with the same configuration
docker run -d --name spin-runtime -p 8888:8888 \
           -v spin-runtime-data:/opt/spin/var \
           -e SPIN_TOKEN=your-secure-token \
           ghcr.io/siftd/spin-runtime:latest-prod

​
Docker Compose

For Docker Compose deployments, upgrading is simpler: 
# Pull the latest image and recreate the container
docker compose up -d --pull always
This command will:
  • Pull the latest version of the image
  • Recreate containers if the image has changed
  • Preserve your volumes and configuration

​
Cloud-Hosted Runtime

For testing, you can spin up a cloud-hosted runtime with a few clicks. This is great for experimentation, but for production use, we recommend self-hosting.

​
Configuration

Configure the SPIN runtime using these environment variables:
VariableDescription
SPIN_TOKENRequired. Secure token for authenticating connections to the runtime. Must match the token provided when adding the runtime to your workspace.
SPIN_HOMEOptional. Base directory for SPIN runtime files. Defaults to /opt/spin.
REQUESTS_CA_BUNDLEOptional. Path to a CA certificate bundle file or directory for SSL verification. When not set, SSL certificate validation is disabled for outbound requests from the runtime. Set this to enforce SSL verification.
<your-env-var-name>Optional. Any other environment variable can be passed to the runtime. Refer to them using the {{runtime_env:<your-env-var-name>}} syntax.

​
Enabling HTTPS for the Runtime

By default, the SPIN runtime serves connections over HTTP. For production deployments where the runtime is accessed over the network (not localhost), you’ll need to serve it over HTTPS. There are several ways to achieve this:
  • Enable HTTPS directly on the runtime (covered in this section)
  • Use a reverse proxy (like nginx or Apache) that terminates SSL
  • Use a gateway or load balancer that handles SSL termination
  • Use a tunnel solution like Cloudflare Tunnels or Tailscale
This section covers how to enable HTTPS directly on the runtime. If you prefer to handle SSL termination elsewhere in your infrastructure, you can continue running the runtime over HTTP and configure your proxy/gateway accordingly.

​
What You’ll Need

To enable HTTPS, you need:
  1. SSL Certificate (cert.pem): This is your public certificate file that proves the identity of your server
  2. Private Key (key.pem): This is the private key that corresponds to your certificate
These files work together to encrypt the connection between browsers and your SPIN runtime. Without HTTPS, browsers will block connections to non-localhost addresses for security reasons.

​
Docker

To run the runtime with HTTPS enabled: 
docker run -d --name spin-runtime -p 8888:8888 \
           -v spin-runtime-data:/opt/spin/var \
           -v ./path/to/key.pem:/ssl/key.pem:ro \
           -v ./path/to/cert.pem:/ssl/cert.pem:ro \
           -e SPIN_TOKEN=<YOUR-GENERATED-TOKEN> \
           -e SSL_KEY_FILE=/ssl/key.pem \
           -e SSL_CERT_FILE=/ssl/cert.pem \
           ghcr.io/siftd/spin-runtime:latest-prod
Replace:
  • ./path/to/key.pem and ./path/to/cert.pem with the actual paths to your SSL files
  • <YOUR-GENERATED-TOKEN> with the actual SPIN_TOKEN from UI Add Runtime flow

​
Docker Compose

For Docker Compose, add the SSL configuration to your service:
compose.yml
services:
  spin-runtime:
    image: ghcr.io/siftd/spin-runtime:latest-prod
    environment:
      - SPIN_TOKEN=<YOUR-GENERATED-TOKEN>
      - SSL_KEY_FILE=/ssl/key.pem
      - SSL_CERT_FILE=/ssl/cert.pem
    ports:
      - "8888:8888"
    volumes:
      - spin-runtime-data:/opt/spin/var
      - ./path/to/key.pem:/ssl/key.pem:ro
      - ./path/to/cert.pem:/ssl/cert.pem:ro
    restart: unless-stopped

volumes:
  spin-runtime-data:
    driver: local
When HTTPS is enabled, the runtime will serve connections using TLS encryption. Make sure to update your runtime URL in the SPIN UI to use https:// instead of http://.
  • The :ro suffix on volume mounts makes the certificates read-only, which is a security best practice
  • Keep your private key (key.pem) secure and never commit it to version control
  • Never share or commit your SPIN_TOKEN - treat it like a password
  • Ensure your certificate is valid for the domain/hostname you’re using to access the runtime

​
SSL Certificate Validation

By default, the SPIN runtime disables SSL certificate validation for outbound HTTPS requests to external services (e.g., APIs, data sources). This behavior helps avoid issues with self-signed certificates or internal certificate authorities in enterprise environments. To enable SSL certificate validation, set the REQUESTS_CA_BUNDLE environment variable. This can point to either:
  • A single certificate bundle file (e.g., /etc/ssl/certs/ca-bundle.crt)
  • A directory containing multiple certificates (e.g., /etc/ssl/certs/)
When using a directory, it must be prepared using the c_rehash utility supplied with OpenSSL. This creates symbolic links with hashed filenames that allow efficient certificate lookup.Example of preparing a certificate directory:
# Copy your certificates to a directory
mkdir ./certs
cp /path/to/your/*.crt ./certs/

# Process the directory with c_rehash
c_rehash ./certs
To enable SSL certificate validation:
  1. For Docker: Mount your CA certificates and set the environment variable. Using a certificate bundle file: 
    docker run -d --name spin-runtime -p 8888:8888 \
           -v spin-runtime-data:/opt/spin/var \
           -v /path/to/ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt:ro \
           -e SPIN_TOKEN=your-secure-token \
           -e REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt \
           ghcr.io/siftd/spin-runtime:latest-prod
    Using a certificate directory (must be processed with c_rehash): 
    docker run -d --name spin-runtime -p 8888:8888 \
           -v spin-runtime-data:/opt/spin/var \
           -v /path/to/certs:/etc/ssl/certs:ro \
           -e SPIN_TOKEN=your-secure-token \
           -e REQUESTS_CA_BUNDLE=/etc/ssl/certs \
           ghcr.io/siftd/spin-runtime:latest-prod
  2. For Docker Compose: Add the certificate volume and environment variable. Using a certificate bundle file:
    compose.yml
    services:
  spin-runtime:
    image: ghcr.io/siftd/spin-runtime:latest-prod
    environment:
      - SPIN_TOKEN=your-secure-token
      - REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-bundle.crt
    ports:
      - "8888:8888"
    volumes:
      - spin-runtime-data:/opt/spin/var
      - ./ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt:ro
    restart: unless-stopped
    Using a certificate directory:
    compose.yml
    services:
  spin-runtime:
    image: ghcr.io/siftd/spin-runtime:latest-prod
    environment:
      - SPIN_TOKEN=your-secure-token
      - REQUESTS_CA_BUNDLE=/etc/ssl/certs
    ports:
      - "8888:8888"
    volumes:
      - spin-runtime-data:/opt/spin/var
      - ./certs:/etc/ssl/certs:ro  # Directory must be processed with c_rehash
    restart: unless-stopped
When REQUESTS_CA_BUNDLE is not set, the runtime will accept any SSL certificate. This may pose security risks in production environments. Consider enabling SSL verification for production deployments.