Skip to main content

runspec-console

A desktop console for runspec — run, schedule, and monitor runnables from a graphical UI. Built on pywebview with a Vite/React frontend, it discovers every runnable installed in its environment (via runspec local) and can also reach runnables on remote hosts over SSH.

Install

pip install runspec-console              # add [windows] on Windows for the runnable pack
runspec-console

On Windows, pip install "runspec-console[windows]" also installs runspec-windows, so its Windows system-administration and cross-platform web/TLS runnables appear in the UI. The extra is gated to sys_platform == "win32", so it's a no-op on macOS/Linux, and it's not part of [all]. It's an extra rather than a dependency so a white-label console can ship a rebranded copy instead (see the runspec docs, "White-label runnable packages"). The Microsoft 365 runnables are not pulled in automatically — see below.

To add more runnables, just pip install the package that provides them into the same environment (e.g. runspec-linux) — the console picks them up on the next launch.

Where runnables come from

The console lists whatever runspec local can discover: any installed package that ships a runspec.toml and entry points. There's no registry and no filesystem scanning — pip install (or pip install -e .) is how a runnable becomes visible.

Microsoft 365 runnables (Outlook · Teams · Calendar · OneDrive)

These live in the separate runspec-o365 package (they used to ship in runspec-windows, but the console no longer pulls them in — so a Graph-blocked deployment isn't cluttered with unusable tools). Opt in with pip install runspec-o365 into the console's environment, then restart. They authenticate as the signed-in user via the Microsoft Graph device-code flow (no client secret). The full setup lives in the runspec-o365 README; the short version:

  1. Register an app in your Entra (Azure AD) tenant (App registrations → New registration).

  2. Authentication → "Allow public client flows" → Yes — device-code login needs this.

  3. API permissions → Microsoft Graph → Delegated: add User.Read, Mail.Read, Chat.Read, Calendars.Read, Files.Read.All, then grant consent.

  4. Copy the Application (client) ID and Directory (tenant) ID.

  5. Drop them in %APPDATA%\runspec-o365\graph.toml (the client id is not a secret):

    client_id = "00000000-0000-0000-0000-000000000000"
    tenant    = "yourcompany.onmicrosoft.com"
    

    For a personal Microsoft account (e.g. trying it at home), register the app for "personal Microsoft accounts" and set tenant = "consumers" (or "common") instead of a tenant domain.

  6. Run graph-login once (it prints a URL + code to authenticate); the token caches and refreshes silently thereafter.

In a managed tenant: Chat.Read (Teams) is typically admin-consent-required, so a tenant admin may need to grant consent on the app registration. The mail/calendar/files scopes are usually user-consentable.

AI assistant (optional)

The console can drive runnables through an LLM. Install the provider extra you want:

pip install "runspec-console[anthropic]"   # Claude
pip install "runspec-console[openai]"      # OpenAI
pip install "runspec-console[bedrock]"     # Claude via AWS Bedrock
pip install "runspec-console[langserve]"   # corporate LLM gateway (LangServe /invoke)

LangServe gateway (no Anthropic/OpenAI account)

If your only model access is a corporate LLM gateway that exposes a LangServe /invoke route (commonly Bedrock/Claude underneath), pick the langserve provider. Configure it in Settings → LLM, or hand-edit %APPDATA%\runspec-console\config.toml:

[llm]
provider = "langserve"
base_url = "https://gateway.corp/my-chain"   # /invoke is appended automatically
model    = ""                                 # the published chain usually pins its model
# Static token:
api_key  = "..."
# …or a short-lived token re-fetched on a TTL (rotating corporate creds):
# api_key_command = "aws-vend-token --print"
# api_key_ttl_ms  = 300000

Tool calling is structured — runspec tools are sent to the gateway and the model's tool calls are executed exactly as with the native providers. The two parts that vary per-gateway are knobs under [llm], adjustable once you've seen the endpoint's GET /input_schema:

key default meaning
input_messages_key "messages" key the chat history is sent under, inside input
input_tools_key "tools" key the tool schemas are sent under
tools_in_config false when true, tools move to config.configurable.<key> instead of input
auth_header "Authorization" header the token is sent in
auth_scheme "Bearer" scheme prefix; set to "" to send the raw token

Agent tool list (tool_mode)

The assistant turns each fleet runnable into an LLM tool. On a uniform fleet — many hosts running the same package set — the default tool_mode = "dedup" sends one tool per folder/runnable (named group__runnable) with a required host enum listing the hosts that have it, instead of one tool per host×runnable. This keeps the tool list — re-sent on every turn — small (an 18-host × 20-runnable fleet: 20 tools instead of 360). The agent names the host as an argument.

Set it in Settings → LLM → Tool list mode, or in the config file:

[llm]
tool_mode = "dedup"      # default — collapse identical per-host tools
# tool_mode = "per_host" # one tool per host__runnable (the original layout)
# tool_mode = "search"   # discovery meta-tools only (best for large, multi-package fleets)

Use "per_host" if you'd rather the host be encoded in the tool name than chosen as an argument.

"search" goes further for fleets that install many distinct runnables (several packages = 70–100+ tools): instead of listing every runnable, it exposes three fixed meta-tools — search_runnables (find by keyword; returns typed argument rows), run_runnable (execute by id + host, with arguments validated before dispatch), and describe_runnable (full schema on demand). The per-turn tool block stays ~3 tools regardless of fleet size. Same autonomy gate, credentials, and secret handling as the other modes. Agent-mode triggers (which scope to a curated allowlist) keep the dedup layout automatically.

So the agent still knows what exists without paying for every schema, search mode also folds a compact catalog index into each turn — one line per runnable (id — first sentence of its description, no arguments). The agent reads the menu, then calls search_runnables/describe_runnable for the details of the one it wants. The index is bounded by [llm] tool_index_limit (default 300, with an overflow note) and can be turned off with [llm] tool_index = false. Tip: lead each runnable's description with its distinguishing detail — that first sentence is what the agent scans.

Custom providers (plugins)

When a model gateway is proprietary and its adapter must stay in a private repo, ship it as a plugin instead of forking the console. A plugin implements runspec_console.ModelAdapter (dependency-free, so no SDKs leak in) and is resolved under a [llm] provider name three ways:

  • Entry point (recommended) — your wheel advertises the runspec_console.adapters group; pip install it and the provider appears (selectable in Settings → LLM).
  • register_adapter(name, factory) — call it from a module imported at startup via [plugins] modules = ["your_pkg"].
  • Dotted path — provider = "your_pkg.module:AdapterClass", no packaging.

A "LangServe-ish but not vanilla" gateway can subclass LangServeAdapter and override only _build_payload / _parse_output. See examples/console-adapter-plugin/ for a ready-to-copy template — it includes an AGENTS.md brief and a Copilot prompt file for building the adapter with an AI agent, and conformance helpers (runspec_console.adapters.testing) to validate it without a live gateway.

Usage

runspec-console              # production (bundled UI)
runspec-console --dev        # point pywebview at a running Vite dev server
runspec-console --devtools   # enable the Chromium inspector in a prod build

Version & documentation

The installed version is shown at the bottom of the host sidebar. On launch the console checks for a newer release by asking pip — running from the very venv runspec-console is installed in — what the newest available version is. Going through that venv's pip means the check honours its index configuration: an internal PyPI proxy / mirror is queried instead of public PyPI when the venv is pointed at one. It's best-effort — a blocked or offline network (or missing pip) simply shows the version with no update indicator; when a newer release exists, an ↑ <version> chip appears next to it. The toolbar's docs icon (top right) opens the documentation site in your browser.

The docs target defaults to https://runspec.app/ and is overridable per-install in %APPDATA%\runspec-console\config.toml:

[console]
docs_url = "https://docs.internal.corp/runspec/"

See the main runspec docs for the runspec format, the SSH jump-host model, and logging.

Metadata

Release files for runspec-console 0.400.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distribution (wheel)

Table of built distributions (wheels) for runspec-console 0.400.1
File Interpreter ABI Platform Actions
runspec_console-0.400.1-py3-none-any.whl Python 3 none any Details for runspec_console-0.400.1-py3-none-any.whl

Release files / runspec_console-0.400.1-py3-none-any.whl

Download URL runspec_console-0.400.1-py3-none-any.whl
Size 3.9 MB
Tags Python 3
SHA-256 checksum
How to use checksums
e29874adb55180967626ede8c251ef22a5396b819b6e57ff43ed659aafa520cc
BLAKE2b-256 checksum
How to use checksums
5e37bfad99fa457eac627831279cccf0768bdfec4a52af176a2ec917ffc8219c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for runspec-console 0.400.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for runspec_console-0.400.1-py3-none-any.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.400.1 This release

1 release file Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page