Cube

Cube is an open-source Python agent harness for building embeddable, tool-using, plugin-extensible agents. It provides a lightweight runtime kernel, an optional local-first application host for durable sessions and workspaces, and an optional distributed runtime layer for backend/worker deployments.

Public Surfaces

• cube.core: platform-free harness kernel for agent runs, messages, tools, hooks, LLM clients, MCP adapters, events, cancellation, and runtime state.
• cube.platform: Cube's local-first application platform, including the plugin SPI/host, agency member projections, channel, durable session, workspace, database, and runtime contracts.
• cube.cluster: distributed runtime coordination for backend/worker deployments using MySQL, Redis, and a shared POSIX workspace.
• cube.plugins: official concrete capability plugins for tools, hooks, channel types, chat, task/workflow, and sub-agents.
• apps/cli: independent official command-line application, distributed as cube-cli and installed with the cube command.
• apps/playground: official full-stack reference application, split into an independent FastAPI backend and a Next.js frontend. Neither is part of the cube wheel.

Most developers should extend Cube through plugins. Advanced users can embed cube.platform.CubeLocalApp for the batteries-included local host, or use cube.core directly when they only need the harness kernel.

Install And Run

pip install cube-cli
cube --help
cube --root-dir ./cube-data init
cube --root-dir ./cube-data db init
cube --root-dir ./cube-data user use alice --name "Alice"

The base install is intentionally lightweight:

pip install cube-agent-harness

It provides cube.core plus lightweight plugin model contracts under cube.platform.plugin. Install optional adapters only when you need them:

pip install cube-agent-harness[llm]           # LiteLLM clients, router, model catalog
pip install cube-agent-harness[mcp]           # MCP transport clients
pip install cube-agent-harness[platform]      # local-first platform and SQLite
pip install cube-agent-harness[cluster]       # distributed runtime with MySQL/Redis
pip install cube-agent-harness[all]           # every built-in SDK capability extra

The default local database path is:

<root_dir>/cube.sqlite3

Layout

cube/
├── core/              # framework kernel; must not import platform/plugins
│   ├── runtime/       # AgentRuntime, agent loop, run context, events
│   ├── tool/          # Tool protocol, ToolRuntime, ToolTask lifecycle
│   ├── hook/          # hook types, dispatcher, reducers, HookRegistry
│   ├── llm/           # LLM client contracts and LiteLLM adapters
│   ├── mcp/           # MCP adapter/client support
│   └── common/        # ids, time helpers, EventBus, CancellationToken
├── platform/
│   ├── host/          # CubeLocalApp, PlatformServices, PlatformRuntime, health
│   ├── assembly/      # manifest-driven plugin/table runtime assembly
│   ├── command/       # transport-neutral session command contracts
│   ├── event/         # live session event stream contracts
│   ├── agency/        # tenant container and member projections
│   ├── channel/       # project/room container and session definitions
│   ├── session/       # durable transcript/session container
│   ├── notification/  # central durable human inbox
│   ├── agent/         # default Agent worker implementation
│   ├── plugin/        # plugin SPI, discovery, resolver, assembly, registry
│   ├── workspace/     # local file workspace layout
│   └── database/      # SQLModel/SQLite platform persistence
├── cluster/           # distributed Gateway/Worker runtime coordination
└── plugins/
    ├── tools/         # official filesystem/chat/background tools
    ├── hooks/         # official concrete hooks
    ├── channels/
    │   ├── chat/      # dm and group_chat channel types
    │   └── project/   # project channel type and project query service
    ├── sessions/
    │   ├── chat/      # chat session capability
    │   └── task/      # multi-phase task and workflow capability
    └── subagent/      # complete sub-agent capability and tool-owned session

apps/
├── cli/               # official cube-cli terminal application
└── playground/        # official full-stack reference app
    ├── backend/       # project-owned FastAPI/auth/realtime composition
    └── frontend/      # Next.js playground UI

Architecture

cube.core is the agent harness kernel. It has no database, session, channel, web framework, CLI, agency, user, plugin loading, or provider-SDK dependency. Importing cube, cube.core, cube.core.llm, or cube.platform.plugin.PluginSpec does not load optional adapters such as LiteLLM, FastAPI, SQLModel, MCP, or Typer.

cube.platform assembles the harness into a durable local application. It does not own a global account table, credentials, passwords, or authentication. Human identity inside Cube is an agency-scoped member projection stored with the agency; embedding applications own accounts and map authenticated users to those projections. Long-lived, human-editable configuration lives in file workspaces under <root_dir>/. Runtime transcript, run state, task state, background tool state, metrics, and small app records live in SQLite.

cube.platform.plugin owns the plugin SPI, discovery, selection, dependency resolution, transactional registration, and frozen capability registry. cube.plugins contains Cube's official implementations. Official and user plugins use the same PluginSpec model and cube.plugins entry-point group to contribute tools, hooks, hook events, session kinds, channel types, and the SubAgent provider. Runtime table registration remains a separate tables.toml / TableSpec path. Session-specific message and event types are declared by the session class.

Loading and runtime ownership follow parallel boundaries:

PluginSpec -> PluginManager -> PluginRegistry
TableSpec  -> TableManager  -> TableRegistry

The plugin and table managers load declarations independently. RuntimeAssembly validates and freezes both registries, PlatformServices owns that immutable assembly, and PlatformRuntime consumes the durable service root rather than loading capabilities itself.

apps/cli and project backends such as apps/playground/backend are application-owned compositions. They use public cube.platform composition helpers, while each application owns the default plugins.toml and tables.toml it writes.

cube.cluster is the optional distributed runtime layer. Backend applications compose PlatformServices with ClusterGateway for command dispatch and live event subscription; worker processes run ClusterWorker, which owns PlatformRuntime and executes sessions. Distributed mode uses MySQL for Cube durable data, Redis for coordination, and a shared POSIX root_dir such as NAS. It does not provide a CubeApp facade or a local fallback.

Plugin Development

External plugins expose a PluginSpec through the cube.plugins entry point group:

from cube.platform.plugin import PluginSpec


def register(ctx):
    ctx.tools("finance_controls", my_tool)


plugin = PluginSpec(
    name="my.company.finance",
    version="0.1.0",
    requires_tables=("my.company.finance",),
    register=register,
)

[project.entry-points."cube.plugins"]
"my.company.finance" = "my_company_finance.plugin:plugin"

Plugins with persistence export an independent TableSpec and list its logical name in requires_tables. The host must still enable the table module in tables.toml; runtime composition reports a missing requirement before database initialization and never auto-loads plugin tables.

Plugin and table loading is manifest-driven. Run the owning host's initializer (cube init for the CLI or playground-backend init for the Playground), or write plugins.toml / tables.toml explicitly before composing the runtime.

SessionContribution.required_tools and required_hooks are session kind invariants. They describe capabilities the kind needs to run and are separate from [assembly].default_tools, which are optional agent tools filtered by agent tool-use policy. Default and required hook groups remain distinct during capability-name assembly, then runtime materialization combines their handlers into one prepared HookRuntime; sessions and agents consume that runtime rather than assembling hook extension registries themselves.

cube.core exposes a small stable convenience API. Import provider-specific clients and lower-level runtime events from their package-local modules, for example cube.core.llm.LiteLLMClient or cube.core.runtime.AgentStartEvent.

Development

For the fastest full-stack distributed Playground loop on macOS, install uv and Node.js 20.11 or newer, place the supplied deployment environment at the repository-root .env, then run:

make doctor
make local-start
make local-status
make local-logs
# Open http://localhost:3000
make local-restart
make local-shutdown

local-start runs separate ClusterWorker and distributed Playground backend processes plus the Next.js development server. It installs the pinned local SRT and ripgrep packages inside the repository, preserves existing runtime manifests, initializes/validates the MySQL schema, and waits for worker and HTTP readiness. Use ENV_FILE=config/alice.env for a non-default environment file. See deploy/README.md for prerequisites, per-developer cluster isolation, troubleshooting, Docker image validation, and Make variable overrides.

Package and test development commands:

uv sync --all-packages --all-extras --dev
uv run --all-extras pytest tests -q
uv run --package cube-cli pytest apps/cli/tests -q
uv run --package cube-playground-backend pytest apps/playground/backend/tests -q
uv run --all-extras python -m compileall cube tests
uv run --package cube-cli cube --help
uv build --package cube
uv build --package cube-cli
npm --prefix apps/playground/frontend run typecheck
npm --prefix apps/playground/frontend run build

Core boundary check:

rg -n "^\s*(from|import) cube\.(platform|plugins)" cube/core --glob '*.py'

See also:

• docs/README.md
• docs/api-stability.md
• docs/embedding.md
• docs/cluster-runtime.md
• cube/core/README.md
• cube/platform/README.md
• cube/plugins/README.md
• apps/cli/README.md
• apps/playground/README.md
• deploy/README.md