Skip to main content

Demiurge Manual

Demiurge is an Alpha-stage agent framework built around Agent Slots: governed extension boundaries that let an Agent Core expand capability and logic design without changing the Host harness. A file-backed Agent Core can compose agents, state, tools, skills, and MCP declarations, then evolve through Host-controlled Git change sets.

The Host owns sessions, turns, provider calls, tools, approvals, state, delivery, Git revision promotion, and rollback. Agent Cores own authored files such as agent.yaml, SOUL.md, Agent Slots, skills, tools, schedules, MCP declarations, and local libraries.

Start with Agent Slots if you want to understand how custom behavior enters the agent loop under Host governance.

The manual uses the Diataxis documentation model:

  • Tutorials guide you through a complete learning path.
  • How-to guides solve one operational task.
  • Explanation pages describe why the system is shaped this way.
  • Reference pages define exact commands, schemas, and contracts.

Reference contract pages are also intended to be readable by the evolver core when it receives project docs as read-only context.

Start Here​

If you are new to Demiurge, read these in order:

  1. Quick Start
  2. Configure a provider
  3. Choose a workspace
  4. Troubleshoot

By Role​

RoleFirst pages
First-time userQuick Start, Configure a provider, Choose a workspace
Local operatorTroubleshoot, Configure channels, Install packages
Agent Core authorHost and Agent Core, Customize an Agent Core, Write an Agent Slot, Slot Context SDK, Authored surface contract
Package authorPackage model, Write a package recipe, Create an external package repository, Publish a package repository, Package recipe reference
ContributorArchitecture, Host runtime contracts, Runner and context, Tool runtime, Package installer

Install Paths​

For normal use, run the managed installer from a checkout of this repository:

scripts/install.sh
~/.demiurge/demiurge-agent/.venv/bin/demiurge --provider fake

The installer requires git and uv, creates or reuses ~/.demiurge/demiurge-agent, runs uv sync, and initializes the runtime home.

For source checkout development, stay in the repository and use uv:

uv sync --all-groups
uv run demiurge init
uv run demiurge --provider fake

The TUI requires Node.js 20 or newer. Running demiurge without a subcommand starts the TUI. The main subcommands are init, doctor, core, package, update, setup, and gateway.

The launcher uses the tracked packaged TUI bundle by default and ignores a leftover source-checkout ui-tui/dist/entry.js. Use DEMIURGE_TUI_DEV=1 only when intentionally running local TUI build/source artifacts. The TUI and Host exchange protocol/build identity before gateway initialization and fail closed on a mismatch.

Configuration Order​

Provider resolution uses this order:

  1. CLI override such as --provider <provider-id>.
  2. The selected runtime core manifest.
  3. The global fallback manifest.
  4. The host default provider.
  5. fake.

Workspace resolution uses this order:

  1. --workspace <path>.
  2. DEMIURGE_WORKSPACE.
  3. The TUI launch directory.
  4. The selected core's runtime.workspace.
  5. ~/.demiurge/workspace.

Current Alpha Boundaries​

  • Latest release notes: 0.8.0.
  • Python dependencies are host-owned and locked by the source checkout.
  • Agent Slot code runs in the host-shared Python environment.
  • Runtime Agent Core revisions are Git commits in ~/.demiurge/.core.git.
  • Candidate evolution works in .evolve/runs/<run_id>/agents and cannot add dependencies automatically.
  • Package install and uninstall are user-triggered Git transactions against the live agents tree; package recipes do not modify the host lock file.
  • Runtime layout, authoring contracts, package behavior, and troubleshooting steps may still change before 1.0.0.