Runspace

An open-source LLM workspace — the one your team already knows how to use. Shared channels, threads, @mentions, uploads and history — except the people you tag are agents, and they have tools.

Ask one a question and the answer arrives as a chart, a sortable table or a row of KPI cards — not a paragraph describing one. Some of the work nobody has to ask for: a routine is a cron line and a prompt, so the morning read is filed before anyone opens the tab.

The whole thing is one YAML file. Below is a workspace that actually runs — Almanac, the demo, is about this size.

Answers that render

An agent emits a fenced block; the frontend renders it as a component. The model never sees the renderer, and a block with the wrong keys shows a visible error rather than failing quietly.

```chart — ten types, bar through sankey and treemap	```kpi — headline figures
```datatable — row links, expandable detail, per-row actions	```insight — the one finding worth flagging

```mermaid renders natively too, for when the answer is a process rather than a number.

Bring your own runtime

Runspace is not tied to any one agent framework. Five adapters ship, and an app picks one with a single line of config:

The four CLI adapters shell out to a binary you install, so Runspace depends on none of them — and the workspace itself never knows which one answered.

pip install "runspace[agentino,workspace,server]"

A workspace in one file

# workspace.yml
name: Acme Back Office
icon: 🗂
brand_color: '#2F5D62'

apps:
  analyst:
    name: Ada
    role: Data analyst
    soul: agents/analyst/SOUL.md
    tools: agents/analyst/tools/
    model: gpt-5.4-codex
    max_turns: 10

python -m runspace.workspace.serve workspace.yml

That gives you chat with streaming, file upload and attachment rendering, message history, a scheduler, and a settings surface — for every agent the file declares.

A complete one is in examples/grid: a single agent over the UK grid's carbon intensity API — free, keyless, updated every half hour — so it runs the moment you have a model endpoint, with no data to fetch or seed.

cd examples/grid && python -m runspace.workspace.serve workspace.yml

What you get

Swappable everything

Storage, vision, transport, embeddings and the clock all sit behind typing.Protocol definitions, selected from the environment. Tests run against in-memory and fixture implementations; production picks real ones.

from runspace.protocols import get_store, get_vision, get_file_storage

store = get_store()          # FileStore | InMemoryStore | SupabaseStore
vision = get_vision()        # CodexVision | FixtureVision
files = get_file_storage()   # LocalFileStorage | ...

Which backend you get is decided by environment variables, so the same image runs in a sandbox and in production without a code branch.

Three levels of control

Config only. Ship a workspace.yml and, if you need custom endpoints, plugin modules. No Python entry point:

plugins:
  - myapp.plugins.invoices

CMD ["python", "-m", "workspace.serve"]

A plugin module simply defines whatever it wants collected — router, cron_executors, startup_hooks, shutdown_hooks, middlewares.

A little code. Call create_app() and pass extras:

from runspace.workspace import create_app

app = create_app(
    workspace_yml="workspace.yml",
    tenant_id="acme",
    extra_routers=[my_router],
    extra_startup_hooks=[warm_caches],
)

Full control. Build your own FastAPI app and wire WorkspaceGateway and AppRegistry yourself. That is the same API the bootstrap uses.

Installing

pip install runspace                              # contracts, protocols, workspace
pip install "runspace[agentino,workspace,server]"  # runtime + FastAPI + uvicorn

The core install stays light — pydantic, pyyaml and httpx, nothing else. Everything beyond the contracts is an extra you opt into: [agentino] for the agent runtime, [workspace] for the FastAPI gateway, [server] for uvicorn, plus [redis], [documents], [scheduler] and [crawler]. [all] takes the lot.

Runspace does not require any particular agent runtime — that is why the framework is an extra and not a dependency.

Layout

src/runspace/
  contracts/   wire shapes — chat, runtime, tool, workspace.yml, scheduling
  protocols/   swappable adapters: store, vision, transport, file_storage,
               embeddings, transcriber, clock, prompt flattening
  workspace/
    backend/   gateway, app registry, runtimes, messaging, routines,
               attachments, runners, scoring
  ingestion/   inbound channels — Telegram polling, pairing, discovery
  helpers/     session, messaging and document utilities
  runspace_cli/  helper commands behind `runspace <subcommand>`
workspace/
  frontend/    React components published as @runspace/ui (an npm package,
               deliberately outside the Python tree)

Configuration

YAML values support ${VAR:-default}, expanded at load time.

Development

pip install -e ".[dev]"

PYTHONPATH=src pytest -q         # the whole suite; testpaths covers every location
ruff check . && ruff format --check .

node --experimental-strip-types workspace/frontend/shared/utils/loosePayload.test.mjs
node --experimental-strip-types --test workspace/frontend/shared/utils/describeSchedule.test.mjs

[dev] exists because the suite needs more than pytest: the protocol tests are property-based, the document tests need agentino's libraries, and the mirror tests patch a Supabase client. Installing pytest alone gives a checkout whose tests cannot collect.

See CONTRIBUTING.md.

Licence

Apache License 2.0.