Morfeus

A desired-state control plane for autonomous workloads.

Move beyond prompt chains and fixed multi-agent graphs. Declare the outcome, budget, worker contract, and acceptance evidence; let the controller reconcile the workload until the state is verified.

Quick start · How it works · Roadmap · Contributing · Discussions

Warning

Morfeus 0.0.1 is an experimental, trusted-local-worker proof of concept. It does not yet sandbox workers or provide capability isolation, secret isolation, or a general exactly-once side-effect guarantee. Read the security policy before using it.

Why Morfeus?

Most agent systems are designed around conversations, prompt chains, or a graph of agents. Those abstractions help describe execution, but they do not by themselves solve workload lifecycle problems:

• How do you know the requested outcome actually exists?
• Who may perform which external action, against which resource, and for how long?
• What happens after a crash between an external effect and a state commit?
• How do you resume work on another runtime without replaying side effects?
• How do you bound retries, memory, time, cost, energy, and blast radius?

Morfeus starts from a different premise:

A worker is not the authority on success. A workload succeeds only when the control plane verifies its declared acceptance criteria.

The long-term design takes the useful ideas behind controllers, admission control, workload isolation, snapshots, placement, and fault domains—without making Kubernetes, a model provider, or another agent framework a dependency.

What works today

• Declarative TOML workloads: goal, worker protocol, budget, and acceptance.
• Framework-neutral json-stdio/v1 worker protocol.
• SQLite-backed task, attempt, lease, and event lifecycle.
• Deterministic file_exists, file_contains, and command_exit checks.
• Retry and per-attempt wall/output budgets.
• Expired-lease recovery for the local single-controller prototype.
• Machine-readable JSON output.
• Interactive terminal control plane with a live, keyboard-navigable slash-command palette.
• Finite ANSI boot animation with a static fallback and no graphics dependency.
• Zero third-party runtime dependencies.
• Network-free, user-scoped installer with atomic upgrades.

The limitations are intentional and documented. The next milestone hardens state integrity, process supervision, resource limits, and verifier purity before adding more agent features.

Quick start

Requirements: macOS or Linux, Python 3.11+, and Git.

git clone https://github.com/ta2jam/morfeus.git
cd morfeus
./install.sh
morfeus

An interactive workspace opens when stdin and stdout are attached to a terminal:

╭──────────────────────────────────────────────────────────────────────╮
│             MORFEUS  ·  desired-state control plane                 │
├────────────────────┬─────────────────────────────────────────────────┤
│      ▄▓██▓▄        │ version   0.0.1                                │
│    ▄█▀░  ░▀█▄      │ workspace /path/to/project                     │
│   ▓█  ◇M◇  █▓     │ state     /path/to/project/.morfeus/state.db    │
│    ▀█▄░  ░▄█▀      │ runtime   trusted process · unsandboxed         │
│      ▀▓██▓▀        │ mode      desired-state lifecycle              │
╰────────────────────┴─────────────────────────────────────────────────╯

/ command palette  ↑↓ select/history  Enter run  Ctrl-C ×2 exit

› /run examples/hello.toml

Typing / opens the command palette immediately. Each additional character narrows the visible commands. Use ↑ and ↓ to select and Enter to run. Commands with required arguments remain open for the argument before execution. Ctrl-C clears the current input; a second consecutive Ctrl-C exits. Ctrl-D is deliberately disabled. Set MORFEUS_NO_ANIMATION=1 to disable the finite startup animation.

Pipes and CI remain non-interactive: bare morfeus prints command help instead of waiting for input.

The installer:

• never uses sudo;
• never accesses the network;
• creates a minimal isolated Python environment without pip;
• installs under ${XDG_DATA_HOME:-$HOME/.local/share}/morfeus;
• creates ~/.local/bin/morfeus;
• refuses to overwrite an unmanaged launcher;
• performs an atomic upgrade after verifying the staged CLI.

Custom locations are supported:

MORFEUS_HOME="$HOME/Applications/morfeus" \
MORFEUS_BIN_DIR="$HOME/bin" \
PYTHON=python3.13 \
./install.sh

Upgrade from a fresh checkout:

git pull --ff-only
./install.sh

Managed uninstall:

./install.sh --uninstall

Run without installing:

PYTHONPATH=src python3 -m morfeus

Try the example workload

morfeus run examples/hello.toml
morfeus status

Expected terminal state:

<task-id>  succeeded  1/2  prove-desired-outcome

Inspect the evidence-oriented lifecycle:

morfeus events <task-id>
morfeus verify examples/hello.toml

verify exits with code 2 when the workload specification is valid but the desired state is not yet satisfied. Invalid input and operational errors use a different error path.

Workload example

schema_version = "morfeus/v0.0.1"
name = "build-artifact"
goal = "Create dist/result.txt and make the contract test pass."
workdir = "."

[budget]
max_attempts = 3
max_seconds_per_attempt = 300
max_output_bytes = 1000000

[worker]
protocol = "json-stdio/v1"
command = ["my-worker", "--stdio"]

[[acceptance]]
name = "artifact"
kind = "file_contains"
path = "dist/result.txt"
expected = "accepted"

[[acceptance]]
name = "contract-test"
kind = "command_exit"
command = ["python3", "-m", "unittest", "tests.test_contract"]
timeout_seconds = 30

The worker receives one JSON object on stdin and returns one JSON object on stdout. Its completion claim is informational; the controller evaluates the acceptance checks independently.

{
  "summary": "what changed",
  "observations": ["evidence or limitation"]
}

How it works

flowchart LR
    S["Workload spec"] --> A["Admission"]
    A --> D["Durable state"]
    D --> C["Reconciliation controller"]
    C --> O["Observe current state"]
    O -->|not satisfied| W["Worker process"]
    W --> V["Independent checks"]
    O -->|already satisfied| V
    V -->|all pass| X["Succeeded"]
    V -->|checks fail, budget remains| R["Retrying"]
    V -->|budget exhausted| F["Failed"]
    R --> C

Loading

The current implementation is deliberately small. The target architecture adds a restricted runtime, typed action intents, a capability broker, a fenced effect ledger, independent evidence, semantic checkpoints, and security-constrained green placement. See the technical roadmap.

CLI

Command	Purpose
morfeus	Open the interactive control-plane shell in a TTY
morfeus init	Initialize the SQLite state store
morfeus verify SPEC	Validate a spec and evaluate acceptance
morfeus admit SPEC	Persist an admitted workload snapshot
morfeus reconcile ID	Execute one reconciliation cycle
morfeus run SPEC	Admit and reconcile until terminal
morfeus status [ID]	Show one task or list recent tasks
morfeus events ID	Print the append-only application event stream

Use --json for machine-readable output and --state PATH for an explicit SQLite location.

Security model

The current security boundary is narrow and explicit:

Property	0.0.1 status
Trusted local workload	Supported
Untrusted worker sandbox	Not supported
Capability-enforced tools	Not supported
Secret isolation	Not supported
General effectively-once effects	Not supported
Multi-tenant isolation	Not supported
Deterministic acceptance checks	Prototype supported

Do not report a vulnerability in a public issue. Follow SECURITY.md.

Roadmap

The roadmap is capability-gated rather than marketing-driven:

1. 0.0.2 — bounded local engine, state integrity, sanitized environment.
2. 0.0.3 — restricted supervisor and side-effect firewall.
3. 0.1.0 — durable single-node control plane and evidence graph.
4. 0.2.0 — policy, identity, approvals, and secret handles.
5. 0.3.0 — outcome receipts, observability, and audit separation.
6. 0.4.0 — measured green control plane using verified workloads as the functional unit.
7. 0.5.0+ — semantic migration, placement, multi-tenancy, and high assurance.

Read the detailed security and green engineering roadmap.

Contributing

Contributors are welcome—especially for security hardening, fault injection, resource measurement, protocol tests, and documentation.

• Start with good first issue or help wanted.
• Read CONTRIBUTING.md before opening a pull request.
• Use Discussions for architecture questions.
• Follow the Code of Conduct.

No CLA is required. Every released version is an explicit commit and annotated tag; the procedure is documented in the contribution guide.

If the control-plane direction is useful to you, starring the repository helps other engineers discover it. Concrete issues, failing test cases, and small focused pull requests help more than generic feature requests.

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v
sh -n install.sh

Runtime dependencies: none. Build backend: Hatchling. Tests use unittest from the Python standard library.

License

Morfeus is licensed under the Apache License 2.0, including an explicit patent grant for contributors and users.