# Skop Runner

Run Jupyter notebooks from [Skop](https://skoplabs.com) on your own machine. Skop Runner connects your local computer to the Skop workspace, letting you execute code, manage files, and use your local Python environments — all from the browser.

## Installation

Requires Python 3.10+.

```bash
# Recommended (isolated install, no venv needed)
uv tool install skop-runner

# Alternative
pipx install skop-runner

# Inside a virtual environment
pip install skop-runner
```

`uv tool` and `pipx` install `skop-runner` in its own isolated environment and
add the CLI to your PATH. This is the recommended approach since `skop-runner`
is a system-wide tool, not a per-project dependency.

Bare `pip install` into system Python is blocked on modern macOS/Linux
(PEP 668). Use `pip` only inside an activated virtual environment.

## Quick Start

### 1. Get your device token

Go to [skoplabs.com](https://skoplabs.com), open a workspace, and click **Add Device** in the device dropdown. Copy the token.

### 2. Login

```bash
skop-runner login --token <your-device-token>
```

### 3. Start the runner

```bash
skop-runner start
```

That's it. Open your workspace in the browser and select your device — you can now browse folders, open notebooks, and execute code on your machine.

## Commands

| Command | Description |
|---------|-------------|
| `skop-runner login --token <token>` | Authenticate with Skop |
| `skop-runner start` | Start the runner |
| `skop-runner status` | Check authentication status |
| `skop-runner logout` | Remove authentication |

## How It Works

Skop Runner runs a local process that:
- Connects to the Skop relay server via WebSocket
- Manages Jupyter kernels for notebook execution
- Serves your local files to the browser workspace
- Detects Python environments (venv, conda, Poetry, Pipenv, pyenv)

Your code runs entirely on your machine. Skop only relays messages between your browser and the runner.

## Configuration

Config is stored in `~/.skop/config.json` (created by `skop-runner login`).

Environment variable overrides:
- `SKOP_API_URL` — API URL (default: https://skoplabs.com)
- `SKOP_WS_URL` — WebSocket relay URL
- `SKOP_LOG_LEVEL` — Logging level (default: INFO)

## Requirements

- Python 3.10+
- macOS or Linux (Windows support coming soon)

## License

MIT
