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:
-
Register an app in your Entra (Azure AD) tenant (App registrations → New registration).
-
Authentication → "Allow public client flows" → Yes — device-code login needs this.
-
API permissions → Microsoft Graph → Delegated: add
User.Read,Mail.Read,Chat.Read,Calendars.Read,Files.Read.All, then grant consent. -
Copy the Application (client) ID and Directory (tenant) ID.
-
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. -
Run
graph-loginonce (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)
pip install "runspec-console[copilot]" # GitHub Copilot (your Copilot plan)
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.adaptersgroup;pip installit 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.419.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| runspec_console-0.419.0-py3-none-any.whl | Python 3 | none | any | Details for runspec_console-0.419.0-py3-none-any.whl |
Release files / runspec_console-0.419.0-py3-none-any.whl
| Download URL | runspec_console-0.419.0-py3-none-any.whl |
|---|---|
| Size | 3.9 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
83c18230750d7107bfbd4c979e156f9459286e2257e9527daeeb59f79909dff9
|
|
BLAKE2b-256 checksum How to use checksums |
57796d9b27c0f28cfdf0601533eae1e06ec80421e325816728c18bd5852caa5b
|
| 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 13, 2026.
Transparency logSecurity for runspec-console 0.419.0
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.419.0-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 13, 2026.
Transparency logA 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.