SPIN Runtime

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:

Variable	Description
`SPIN_TOKEN`	Required. Secure token for authenticating connections to the runtime. Must match the token provided when adding the runtime to your workspace.
`SPIN_HOME`	Optional. Base directory for SPIN runtime files. Defaults to /opt/spin.
`REQUESTS_CA_BUNDLE`	Optional. 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:

SSL Certificate (cert.pem): This is your public certificate file that proves the identity of your server
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:

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

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.

Host SSH Access

This feature allows the SPIN runtime container to SSH into its host machine, enabling you to run shell commands directly on the host system from your notebooks.

Enabling Host SSH Access

When adding or editing a SPIN Runtime in the UI, enable the Host SSH Access option
Provide the SSH username for the host machine
Provide the SSH private key for authentication (if needed, instructions to generate ssh key pair below)

Generating an SSH Key Pair

If you don’t already have an SSH key pair for this purpose, generate one:

ssh-keygen -t ed25519 -f ~/.ssh/spin_host_key -N ""

This creates:

~/.ssh/spin_host_key — your private key (provide this to SPIN)
~/.ssh/spin_host_key.pub — your public key (add this to ~/.ssh/authorized_keys)

Add the public key to your authorized keys:

cat ~/.ssh/spin_host_key.pub >> ~/.ssh/authorized_keys

For more information on SSH key generation, see GitHub’s SSH key guide or your operating system’s documentation.

Configuring SSH on the Host Machine

The SPIN runtime runs inside a Docker container, which means it doesn’t have direct access to the machine running Docker (the Docker host). Host SSH Access bridges this gap by allowing the runtime to SSH into the Docker host over localhost. This lets you run tools or scripts installed on the host, access files outside the container, or execute commands that require host-level access. To use this feature, you’ll need to enable SSH on the Docker host and optionally restrict it to localhost connections.

macOS

1. Enable SSH Enable Remote Login in System Settings: System Settings > General > Sharing > Remote Login 2. Restrict SSH to localhost only (recommended) On macOS, SSH is managed by launchd which ignores ListenAddress settings in sshd_config. Use the macOS firewall (pf) to block external SSH connections instead. Create a firewall rule:

echo "block in on ! lo0 proto tcp to any port 22" | sudo tee /etc/pf.anchors/ssh-local

Add the rule to the pf configuration by editing /etc/pf.conf:

sudo nano /etc/pf.conf

Add these lines at the end of the file:

anchor "ssh-local"
load anchor "ssh-local" from "/etc/pf.anchors/ssh-local"

Enable the firewall:

sudo pfctl -ef /etc/pf.conf

You may see warnings about “No ALTQ support” and “pf already enabled” — these are normal and can be ignored.

3. Verify SSH is local-only Verify the rule is loaded:

sudo pfctl -a ssh-local -s rules

You should see:

block in on ! lo0 proto tcp from any to any port = 22

Test by running ssh localhost (should work) and attempting SSH from another machine (should be blocked).

Ubuntu Linux

1. Install and enable SSH

sudo apt update
sudo apt install openssh-server
sudo systemctl enable ssh
sudo systemctl start ssh

2. Restrict SSH to localhost only (recommended for personal laptops/computers) Edit the SSH daemon config:

sudo nano /etc/ssh/sshd_config

Add or modify these lines:

ListenAddress 127.0.0.1
ListenAddress ::1

3. Restart sshd

sudo systemctl restart ssh

4. Verify SSH is local-only

ss -tlnp | grep :22

You should see SSH listening only on 127.0.0.1:22 and [::1]:22.

Other Linux Distributions

For other Linux distributions, the general steps are similar:

Install OpenSSH server (package name varies by distro)
Edit /etc/ssh/sshd_config to set ListenAddress to localhost
Restart the SSH service

Consult your distribution’s documentation or the OpenSSH documentation for specific instructions.

Testing Host SSH Access

Once configured, test the connection from a SPIN notebook:

Add a Shell cell to your notebook
In the cell’s type dropdown, select SSH
In the SSH Connection dropdown, select Runtime Host
Run a simple command like ls or whoami to verify the connection works

Keep your SSH private key secure and never share it
Restricting SSH to localhost is strongly recommended to prevent external access
Consider using a dedicated SSH key pair specifically for SPIN runtime access

Overview

User Guide

Integrations

Communication with the Runtime

Deploy in Your Own Infrastructure

Docker

Docker Compose

Set up with Tailscale

Set up with Cloudflare Tunnels

Kubernetes

Upgrading the Runtime

Docker

Docker Compose

Cloud-Hosted Runtime

Configuration

Enabling HTTPS for the Runtime

What You’ll Need

Docker

Docker Compose

SSL Certificate Validation

Host SSH Access

Enabling Host SSH Access

Generating an SSH Key Pair

Configuring SSH on the Host Machine

macOS

Ubuntu Linux

Other Linux Distributions

Testing Host SSH Access

Overview

User Guide

Integrations

​Communication with the Runtime

​Deploy in Your Own Infrastructure

​Docker

​Docker Compose

Set up with Tailscale

Set up with Cloudflare Tunnels

​Kubernetes

​Upgrading the Runtime

​Docker

​Docker Compose

​Cloud-Hosted Runtime

​Configuration

​Enabling HTTPS for the Runtime

​What You’ll Need

​Docker

​Docker Compose

​SSL Certificate Validation

​Host SSH Access

​Enabling Host SSH Access

​Generating an SSH Key Pair

​Configuring SSH on the Host Machine

​macOS

​Ubuntu Linux

​Other Linux Distributions

​Testing Host SSH Access

Communication with the Runtime

Deploy in Your Own Infrastructure

Docker

Docker Compose

Kubernetes

Upgrading the Runtime

Docker

Docker Compose

Cloud-Hosted Runtime

Configuration

Enabling HTTPS for the Runtime

What You’ll Need

Docker

Docker Compose

SSL Certificate Validation

Host SSH Access

Enabling Host SSH Access

Generating an SSH Key Pair

Configuring SSH on the Host Machine

macOS

Ubuntu Linux

Other Linux Distributions

Testing Host SSH Access