Metadata-Version: 2.4
Name: sidekick-agent-cli
Version: 0.1.0
Summary: CLI for the Sidekick Agent Orchestrator
Project-URL: Homepage, https://github.com/datex-labs/sidekick
Project-URL: Repository, https://github.com/datex-labs/sidekick
Project-URL: Bug Tracker, https://github.com/datex-labs/sidekick/issues
Author-email: Datex <bbatchelder@datexcorp.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agent,llm,runtime,sidekick
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: httpx-sse<0.5,>=0.4.0
Requires-Dist: httpx<0.28,>=0.27.0
Requires-Dist: pydantic<3.0,>=2.0.0
Requires-Dist: rich<14.0,>=13.0
Requires-Dist: websockets<15.0,>=14.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sidekick Agent Runtime

Portable agent execution engine for [Sidekick](https://github.com/datex/sidekick). Runs on user machines (laptops, VMs, self-hosted runners) and communicates with a Sidekick backend via HTTP and WebSocket.

## Installation

```bash
pip install sidekick-agent-runtime
```

## Quick Start

```bash
sidekick serve --url https://sidekick.example.com --token <your-runner-token>
```

Or using environment variables:

```bash
export SIDEKICK_URL=https://sidekick.example.com
export RUNNER_TOKEN=<your-runner-token>
sidekick serve
```

## Configuration

| Flag | Env Var | Default | Description |
|------|---------|---------|-------------|
| `--url` | `SIDEKICK_URL` | `http://localhost:8000` | Sidekick backend URL |
| `--token` | `RUNNER_TOKEN` | *(required)* | Runner authentication token |
| `--name` | `RUNNER_NAME` | hostname | Display name for this runner |
| `--workspace` | `RUNNER_WORKSPACE` | `~/.sidekick/<name>/workspace` | Override working directory |
| `--log-level` | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
| `--allow-insecure` | `SIDEKICK_ALLOW_INSECURE` | `false` | Allow unencrypted HTTP to non-localhost backends |
| `--allow-env-passthrough` | `SIDEKICK_ALLOW_ENV_PASSTHROUGH` | `false` | Pass all server-provided env vars to CLI tools |

> **Note:** The `--url` flag defaults to `http://localhost:8000` for local development.
> In production, always set this to your Sidekick instance URL (e.g. `https://sidekick.example.com`).

## How It Works

The agent runtime connects to your Sidekick instance and executes agent turns:

1. **Connects** via WebSocket for real-time notifications
2. **Receives** turn assignments from Sidekick
3. **Calls LLM** through Sidekick's proxy (SSE streaming)
4. **Executes tools** locally (shell commands, file I/O) or remotely (via Sidekick)
5. **Reports results** back to Sidekick

## Local Tools

The runtime can execute these tools directly on the host machine:

- **RunCommand** — Execute shell commands
- **ReadFile** — Read file contents
- **WriteFile** — Write files
- **ListFiles** — List directory contents
- **CLI Tools** — Execute Python-based CLI tools defined in Sidekick

## Requirements

- Python 3.11+
- A running [Sidekick](https://github.com/datex-labs/sidekick) backend instance
- Network access from the runner to the Sidekick backend (HTTP + WebSocket)
- A runner token (generated in Sidekick's admin UI)

## Security Considerations

The agent runtime **executes commands on behalf of the connected Sidekick backend**. Only connect to Sidekick instances you trust.

Key security features:

- **HTTPS enforced by default** — Connections to non-localhost backends over plain HTTP are blocked. Use `--allow-insecure` to override (not recommended).
- **Sensitive env-var stripping** — Environment variables containing credentials, proxy settings, and path-injection vectors are stripped from CLI tool subprocesses by default. Use `--allow-env-passthrough` to override.
- **Atomic credential writes** — Token cache (`~/.sidekick/credentials.json`) is written atomically with `0600` permissions.
- **Token verification** — After browser-based authentication, the received token is verified against the backend before caching.

See [SECURITY.md](SECURITY.md) for the full trust model and vulnerability reporting instructions.

## Compatibility

| Agent Runtime | Sidekick Backend |
|---------------|------------------|
| 0.1.x         | >= 0.1.0         |

The runtime communicates via the `/api/runtime/v1` API. Breaking changes to this API will be reflected in the compatibility table above.

## License

MIT
