Sidekick Agent Runtime

Portable agent execution engine for Sidekick. Runs on user machines (laptops, VMs, self-hosted runners) and communicates with a Sidekick backend via HTTP and WebSocket.

Installation

pip install sidekick-agent-runtime

Quick Start

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

Or using environment variables:

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

Configuration

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 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 for the full trust model and vulnerability reporting instructions.

Compatibility

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

License

MIT