> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftd.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell Cells

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](/guide/spin-runtime#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

<Note>
  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.
</Note>

### 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

<Warning>
  The `spinlocalsh` daemon runs commands with your local user permissions. Be cautious about what commands you execute, especially in shared notebooks.
</Warning>

### Configuration Options

| Setting          | Description                                         | Default |
| ---------------- | --------------------------------------------------- | ------- |
| **Port**         | The port `spinlocalsh` listens on                   | 8866    |
| **Init Timeout** | Time to wait for command initialization (seconds)   | 10      |
| **Idle Timeout** | Maximum 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`:

```bash theme={null}
# 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