Skip to main content
Shell cells let you execute shell commands in your notebook. They support three execution modes:
  • Shell — Run commands on the SPIN runtime
  • SSH — Run commands on a remote host via SSH connection
  • Local Shell — Run commands on your local machine

​
Shell Mode

The default mode executes commands directly on the SPIN runtime container.

​
Executing Scripts

  • You can execute multiple commands on separate lines.
  • Commands run in the runtime’s environment with access to installed tools and packages.

​
SSH Mode

SSH mode allows you to execute commands on remote hosts using pre-configured SSH connections.
  1. Select SSH from the Type dropdown
  2. Choose an SSH connection from the dropdown (or Runtime Host if Host SSH Access is enabled)
  3. Enter your shell commands
  4. Run the cell

​
Local Shell Mode

Local Shell mode executes commands directly on your local machine, not on the SPIN runtime. This is useful when you need to:
  • Run commands that require local resources or files
  • Interact with local development tools
  • Execute scripts that need access to your local environment
Local Shell requires a small daemon (spinlocalsh) to be running on your machine. This daemon acts as a bridge between SPIN and your local shell.

​
Setting Up Local Shell

  1. Add a Shell cell to your notebook
  2. Select Local Shell from the Type dropdown
  3. Click the Settings icon (gear) next to the type selector
  4. In the settings dialog:
    • Download the spinlocalsh binary for your platform (macOS Apple Silicon or Linux x64)
    • Copy the Run Command and execute it in your terminal
    • Click Test Connection to verify the daemon is running

​
How It Works

When you run a Local Shell cell:
  1. SPIN sends the command to the spinlocalsh daemon on your machine
  2. The daemon executes the command in your local shell
  3. Output is streamed back to SPIN in real-time
  4. Results appear in the cell output just like any other shell cell

​
Security

Communication between SPIN and spinlocalsh is secured with a bearer token:
  • A unique token is automatically generated and stored in your browser
  • The same token must be provided when starting spinlocalsh
  • All requests between SPIN and the daemon require this token
The spinlocalsh daemon runs commands with your local user permissions. Be cautious about what commands you execute, especially in shared notebooks.

​
Configuration Options

SettingDescriptionDefault
PortThe port spinlocalsh listens on8866
Init TimeoutTime to wait for command initialization (seconds)10
Idle TimeoutMaximum idle time between command outputs (seconds)600

​
Troubleshooting

“spinlocalsh is not running” Make sure the daemon is running. Open the Local Shell Settings dialog, copy the Run Command, and execute it in your terminal. “Token mismatch” The running spinlocalsh process has a different authentication token than what’s stored in your browser. Copy the new Run Command from the settings dialog and restart spinlocalsh: 
# The run command will automatically kill any existing process and start fresh
pkill -f spinlocalsh || true; chmod +x ./spinlocalsh && nohup ./spinlocalsh -port 8866 -token <your-token> > /dev/null 2>&1 &
macOS Gatekeeper warning On macOS, you may see a security warning when first running the binary. The provided Run Command includes xattr -d com.apple.quarantine ./spinlocalsh to automatically clear this flag. If you still see issues:
  1. Open System Settings > Privacy & Security
  2. Look for a message about spinlocalsh being blocked
  3. Click Allow Anyway
  4. Run the command again
Connection refused
  • Verify spinlocalsh is running: ps aux | grep spinlocalsh
  • Check that the port matches what’s configured in the settings
  • Ensure no firewall is blocking localhost connections on the configured port