runspec

A desktop console where an AI agent runs your operations — safely.

runspec-console discovers every runnable tool on your machine and across your SSH fleet, and puts an AI agent in front of them: ask for something in plain language, approve what it proposes, and let it automate the rest with schedules, triggers, and shared runbooks. Underneath is runspec — a single TOML interface specification that turns any script into a validated CLI, a typed form, and an agent tool at once.

• Operate — install the console, connect an AI model, and drive your tooling from conversation and typed forms. Get started →

• Author — turn your own scripts into runnables the console, the forms, and the agent can use. Add a runnable →

• Distribute — package a branded, pre-configured console for your whole team. White-label walkthrough →

Versions

This documentation tracks the latest published releases: runspec-console (the desktop app), runspec (Python) and runspec-node (Node) — the core libraries — and the runnable packs below.

---

How it fits together

1. A runnable is a script or tool with its interface declared in a runspec.toml: arguments, types, validation, and an autonomy level that says how much an agent may do with it.
2. Installing a runnable's package into a Python environment makes it discoverable — no registry, no configuration.
3. The console discovers runnables locally and on remote hosts over plain SSH (nothing to install server-side beyond runspec itself), and exposes them three ways at once: typed forms, an AI agent, and automation (triggers, schedules, runbooks).
4. Every agent-driven run passes the autonomy gate — confirm-by-default, with arguments editable at approval time, and a fleet-wide denylist as the kill switch.

Batteries included

Install-and-go packs give the agent real capabilities on day one:

Package	What you get
runspec-windows	43 runnables: Windows system administration, Microsoft 365 (Outlook, Teams, Calendar, OneDrive), and web/TLS diagnostics. Installed automatically with the console on Windows.
runspec-linux	31 runnables: Linux administration, package management, Python venv bootstrap, and the same web/TLS diagnostics.
runspec-jsm	Jira Service Management: raise, comment, transition, discover request types.
runspec-snow	ServiceNow ITSM: create, comment, state changes, catalog discovery.
runspec-logops	Log triage: cluster errors into bounded digests, map traces to source.
runspec-claude	Drive the Claude Code CLI headlessly — delegate bounded coding sub-tasks.
runspec-room	Team chat rooms and helpdesk queues with a self-service request portal.

For developers

The same runspec.toml that powers the console gives any script a real CLI — generated --help, type coercion, validation, subcommands, structured logging — with zero argument-parsing code, in Python or Node. And every runnable is an agent tool for free: runspec serve exposes the whole environment over MCP to Claude Desktop, Cursor, or any MCP host.

# greet/runspec.toml
[greet]
description = "Greet someone from the command line"
autonomy    = "autonomous"

[greet.args]
name  = {type = "str"}
loud  = {default = false}
times = {default = 1}

from runspec import parse

def main():
    args = parse()
    message = f"Hello, {args.name.value}!"
    if args.loud.value:
        message = message.upper()
    for _ in range(args.times.value):
        print(message)

That's a complete, validated CLI — and a typed form and agent tool in the console. Start with the quickstart.