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 info@siftd.ai for information on enabling this feature for your workspace.

​
Limitations

Certain shell cell configurations are not supported in oneshot mode due to the ephemeral nature of the runtime container.

​
Unsupported Shell Types

​
Local Shell

Local shell cells execute commands directly on the host machine’s file system, using a file-based communication mechanism to pass arguments and receive output. In oneshot mode, the runtime runs inside an isolated Docker container without access to the host’s file system, making local shell execution impossible.

​
SSH to Runtime Host

Shell cells configured to SSH into the runtime host attempt to establish an SSH connection back to the runtime container itself. Oneshot containers are minimal, ephemeral environments that don’t run an SSH server, so these connections will fail.

​
Alternatives

If your notebook requires shell execution in oneshot mode, use one of these alternatives:
  • Standard shell cells: Execute commands directly within the runtime container
  • SSH to external hosts: Configure shell cells to SSH into external servers with proper connection credentials
The SPIN UI will display a warning in the Oneshot Config dialog if your notebook contains incompatible shell cells.

​
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