Create an External Package Repository

This tutorial creates a local package repository outside the Demiurge source checkout. You will add one input slot package, trust the repository, preview the install, and uninstall it again.

Package repositories distribute authored-surface files. They do not install Python dependencies and do not modify the host uv.lock.

This tutorial keeps the recipe minimal. For package YAML design and field details, use Write a Package Recipe.

1. Create the Repository Root

Choose a local path:

mkdir -p ~/demiurge-packages/packages
mkdir -p ~/demiurge-packages/input/reply_style

Create ~/demiurge-packages/repository.yaml:

schema_version: 1
id: local_examples
name: Local Demiurge Examples
summary: Local example packages for testing.

repository.yaml identifies the repository. The local alias can still be different when you add it to the host.

2. Add an Input Slot

Create ~/demiurge-packages/input/reply_style/module.py:

def process(ctx):
    ctx.input.add_context(
        "Package hint: answer with direct, concrete steps.",
        role="system",
        write_history=False,
    )

Create ~/demiurge-packages/input/reply_style/slot.yaml:

entrypoint: module:process
failure_policy: soft
history_policy: transient
capabilities: []
description: Adds a package-provided reply style hint.

Input slots run before the provider call. This example adds a low-priority system context hint for each turn.

3. Add a Package Recipe

Create ~/demiurge-packages/packages/reply_style.yaml:

schema_version: 1
id: reply_style
name: Reply Style
summary: Add a package-provided reply style hint.
tags:
  - input
  - style
components:
  - id: reply_style_input
    kind: input
    source: reply_style
    target: agent/input/reply_style
    pipeline:
      group: serial
      append: true
capabilities: []

The source value points to input/reply_style/ inside the repository. The target value is relative to the runtime core. Because this is an input slot, the recipe must include a pipeline placement.

4. Add and Trust the Repository

uv run demiurge package repo add ~/demiurge-packages --alias local --trust
uv run demiurge package repo list

Trust is required because repositories can install executable local code into host-shared Agent Core slots.

You can also use the interactive manager:

uv run demiurge package

Open Repos, add the path, review the detected repository metadata, and confirm trust.

5. Preview and Install

List packages from the new repository:

uv run demiurge package list --repo local

Preview the install:

uv run demiurge package install local/reply_style --core assistant --preview

Install:

uv run demiurge package install local/reply_style --core assistant

The install writes into the active runtime core:

~/.demiurge/agents/assistant/

It copies the input slot to:

~/.demiurge/agents/assistant/agent/input/reply_style/

It also appends reply_style to the input pipeline and records the package in:

~/.demiurge/agents/assistant/packages.yaml

6. Verify

Check installed package state:

uv run demiurge package list --core assistant

Check that the runtime core still loads:

uv run demiurge init --check

Run a fake-provider turn:

uv run demiurge --provider fake

If the package fails to load, compare the repository with Package Repository Contract and the recipe with Package Recipe Reference.

When this repository is ready to share with other users, continue with Publish a Package Repository.

7. Uninstall

Preview removal:

uv run demiurge package uninstall local/reply_style --core assistant --preview

Uninstall:

uv run demiurge package uninstall local/reply_style --core assistant

Uninstall removes agent/input/reply_style/, removes the package-owned pipeline entry, and updates packages.yaml. It does not delete files that a package created outside package-owned targets.

1. Create the Repository Root​

2. Add an Input Slot​

3. Add a Package Recipe​

4. Add and Trust the Repository​

5. Preview and Install​

6. Verify​

7. Uninstall​