CDP

The Cerebel Development Platform, or CDP, is the local developer CLI for bringing up a Cerebel by booting a Cerebrum substrate, and helping the Cerebrum become a domain specialist.

This page is the working contract for the current MVP. If the implementation changes, update this page first so the team keeps the same terminology and command expectations.

For the review-first file format specification, see Domain Bundle File Formats.

Pre-v1 policy:

1. CDP schema and config contracts are allowed to break while we iterate.
2. When we adopt a standard, we switch fully instead of carrying compatibility fallbacks.

Terms

CDP : Cerebel Development Platform. The developer-facing CLI and local harness for booting and interacting with a Cerebel.

Substrate : A bootable or launchable system unit in this architecture, with its own declaration, acquisition source, launch contract, and lifecycle policy. A substrate may be a whole system or a subsystem; examples include Cerebrum, cortices, Thalamus, and future additions.

Cerebrum : The Cerebrum substrate booted by RAS and surfaced by CDP.

Domain : The logical context selected by CDP at boot time.

Domain Bundle : The folder-scoped startup configuration unit for a domain specialist. A Domain Bundle lives under config/domains/<domain_id>/ and currently includes cerebrum.md plus cortices/*.md markdown files.

Install

CDP is installed as part of the docs-and-dev workflow for the repository.

Recommended local setup

uv sync --extra dev
make activate

The first command installs dependencies into the project environment. The second command activates the virtual environment so you can run cdp directly from the shell.

Run without activation

You can also invoke the CLI through uv:

uv run cdp status

Core workflow

The MVP flow is:

1. Boot the substrate runtime with cdp up.
2. Start an interactive chat session with cdp chat.
3. Stop the runtime with cdp down.

uv run cdp comms list
uv run cdp up --domain demo
uv run cdp chat "hello"
uv run cdp down

Commands and options

cdp up

Boots the local Cerebrum substrate runtime.

Option	Meaning
--domain <domain_id>	Selects the Domain Bundle root at config/domains/<domain_id>/. If omitted, CDP falls back to the configured default domain.

CDP selects the active comms cortex id from the Domain Bundle comms-cortices list in declared order.

Example:

uv run cdp up --domain demo

cdp chat

Starts a chat session through the active comms cortex for the current booted session.

Option	Meaning
message	The message to send to the current session.

If you pass a message, CDP sends one response and exits. If you omit the message, CDP enters a simple interactive prompt in the current terminal and stays open until you type exit, quit, or press Ctrl-D.

Example:

uv run cdp chat "hello cerebrum"

Interactive example:

uv run cdp chat

cdp down

Stops the local runtime and clears the active boot session.

cdp status

Shows the current runtime state, including the active domain, comms cortex id, and boot identity.

cdp comms list

Lists the available comms cortex ids declared by the selected Domain Bundle.

cdp logs [service]

Shows log output for the current runtime or a selected service.

cdp notebook open

Prints the notebook URL for the local developer environment.

cdp metrics

Prints the metrics endpoint URL for the local developer environment.

Current MVP guarantees

The current CLI behavior is intentionally strict:

1. cdp chat only works after cdp up.
2. cdp chat uses the comms cortex id selected for the active session.
3. cdp chat stays in the current terminal unless you decide to open a second terminal.
4. cdp down ends the active session.

These rules are the shared contract for the current MVP and are the baseline for future boot and conversation work.

Working with logs while chatting

The chat session is intentionally terminal-based, not a separate window.

If you want to inspect logs while chatting, open a second terminal or split pane and run cdp logs there. That keeps the chat session alive in the first terminal while you review runtime output in the other.

Domain Bundle Format

CDP now uses a forced directory layout for each Domain Bundle:

config/domains/
  <domain_id>/
    cerebrum.md
    cortices/
      <cortex-config>.md

This format follows the same readability pattern used by Agent Skills:

1. YAML frontmatter for machine-readable fields.
2. Markdown body for human and LLM context.

Case policy for markdown config keys:

1. Markdown keys must be kebab-case.
2. Snake_case markdown keys are invalid and should fail validation.
3. Snake_case inside values is allowed (for example Python module paths, symbol names, and metadata payload values).

cerebrum.md required fields

Field	Required	Notes
kind	yes	Must be cerebrum.
name	yes	Human-readable bundle name.
description	yes	What this bundle is for and when to use it.
version	yes	Bundle version tag, such as v0.
domain-id	yes	Must match the domain folder name.
tenant-id	yes	Tenant scope used by runtime state.
lifecycle	yes	Current state label such as proposed or active.
comms-cortices	yes	List of interaction-critical comms cortex refs. Each item must include id and source.
required-cortices	yes	List of cortex refs. Each item must include id and source.
degradable-cortices	yes	Explicit list of tolerated-loss cortices, even when empty.

Example:

---
kind: cerebrum
name: demo-cerebrum
description: Single-cortex MVP Domain Bundle for local CLI chat validation.
version: v0
domain-id: demo
tenant-id: tenant-demo
lifecycle: proposed
comms-cortices:
  - id: comm.cli
    source: ./cortices/cli-comms-cortex.md
required-cortices: []
degradable-cortices: []
---

Cortex config required fields

Field	Required	Notes
kind	yes	Must be cortex.
id	yes	Cortex identifier, must match the ref in cerebrum.md.
role	yes	Runtime role such as communication.
channel	yes (for role: comms)	Transport-facing channel label such as cli.
protocol	yes (for role: comms)	Comms protocol mode such as request-response.
requires-session-id	yes (for role: comms)	Whether chat requests must include a session identifier.
description	yes	Short explanation of cortex purpose.
launch.launcher	yes	Backend type, currently inprocess for MVP.
launch.target.module-path	yes	Python module path for factory/launcher symbol.
launch.target.symbol-name	yes	Callable symbol to build the cortex runtime.

What launch.target means

The launch.target block is the import pointer for creating a substrate runtime. It does not define the whole launch contract, and it does not hold the runtime itself.

CDP uses launch.launcher to choose the execution backend, then uses launch.target to find the callable that builds the substrate.

The hierarchy is:

1. SubstrateDomain is the domain definition/configuration.
2. SubstrateDomain.launch is the launch contract for that domain.
3. SubstrateDomain.launch.target is the import target nested inside the launch contract.

The target lives inside the loaded SubstrateDomain object, so it is part of the domain in memory after CDP reads the bundle, not a separate runtime cache.

1. module-path tells CDP which Python module to import.
2. symbol-name tells CDP which callable inside that module to invoke.
3. The callable is passed the selected substrate domain and returns the instantiated runtime.

In other words, the target is the recipe for construction, while the substrate instance is the object produced by that recipe.

Example:

---
kind: cortex
id: comm.cli
role: comms
channel: cli
protocol: request-response
requires-session-id: true
description: Comms cortex used by cdp chat in the terminal.
launch:
  launcher: inprocess
  target:
    module-path: cdp.comms_cortex
    symbol-name: create_cli_comms_cortex
---

Source reference model

Each cortex entry in required-cortices and degradable-cortices uses a source field.

Current support:

1. Local relative markdown paths.

Designed next:

1. Remote URL or repository references.
2. Mixed local and remote cortex bundles in one substrate bundle.