Skip to main content
The SPIN Runtime can operate in oneshot mode, which brings up an ephemeral runtime that executes a single notebook and then shuts down. This mode is ideal for embedding notebook executions in workflow engines like GitHub Actions, Jenkins, or any environment that supports running ephemeral Docker containers.

​
Use Cases

Oneshot mode is perfect for:
  • CI/CD Pipelines: Run notebooks as part of your continuous integration workflows
  • Scheduled Tasks: Execute notebooks on a schedule using cron or similar schedulers
  • Workflow Automation: Integrate SPIN notebooks into workflow engines like GitHub Actions, Jenkins, GitLab CI, etc.
  • One-time Execution: Run a notebook once without maintaining a persistent runtime

​
GitHub Actions

We provide an official GitHub Action for running SPIN notebooks in oneshot mode. See the spin-oneshot-action repository for complete documentation, examples, and configuration options.

​
Docker

For other workflow engines or custom automation, you can run the SPIN Runtime directly as a Docker container in oneshot mode.

​
Basic Usage


# Be sure to use actual Notebook URL and Oneshot Spin Token
###

docker run --rm \
  -e RUNTIME_MODE=oneshot \
  -e NOTEBOOK_URL=<<Notebook URL>> \
  -e SPIN_TOKEN=<<Oneshot Spin Token>> \
  -e MAX_DURATION=10m \
  ghcr.io/siftd/spin-runtime:latest-prod

​
Environment Variables

VariableRequiredDescription
RUNTIME_MODEYesMust be set to oneshot to enable oneshot mode
NOTEBOOK_URLYesThe URL of the notebook to execute (e.g., https://spin.siftd.ai/demo/default/notebooks/orr0rqr4r80dlrqqrvrqrkdg)
SPIN_TOKENYesOneshot authentication token generated from the SPIN UI (eg., i1t3G3K2Vj3N_jM0wqsWFCgIUSn9N_M3lAvsBUzhniA= )
MAX_DURATIONNoMaximum execution time for the notebook (default: 10m). Accepts values like 5m, 1h, etc.
The SPIN_TOKEN for oneshot mode is different from the token used for persistent runtimes. To create one, go to the “Runtimes” management page, click on the “Oneshot Token” button on top and follow instructions from there.

​
How It Works

When you run the SPIN Runtime in oneshot mode: The container starts up, authenticates with SPIN backend, compiles and runs the notebook. The notebook is executed cell-by-cell with a maximum total timeout of MAX_DURATION

​
Viewing Results

Logs and cell output is emitted stdout/console. IF session storage is enabled:
  • Upon completion, the session is uploaded to configured target
  • You can view session in a browser by copying/pasting the session URL emitted to the console
Session storage for oneshot executions requires additional configuration. Contact [email protected] for information on enabling this feature for your workspace.

​
Troubleshooting

Check logs for status

​
Container Exits Immediately

Ensure all required environment variables are set:
  • RUNTIME_MODE=oneshot
  • NOTEBOOK_URL (copy/paste this URL to browser and ensure it is a valid SPIN notebook)
  • SPIN_TOKEN (ensure you have a valid Oneshot Token)

​
Timeout Errors

If your notebook execution is timing out, increase the MAX_DURATION: 
-e MAX_DURATION=30m  # or 1h, 2h, etc.

​
Authentication Errors

Make sure you’re using a Oneshot Token, not a regular runtime token Remember that a specific Oneshot Token only maps to a single workspace, make sure the token you use maps to same workspace as the notebook