Metadata-Version: 2.4
Name: dorf
Version: 0.1.0
Summary: Control plane for durable AI workers on infrastructure you control
Project-URL: Homepage, https://github.com/aphronio/dorf
Project-URL: Repository, https://github.com/aphronio/dorf
Project-URL: Issues, https://github.com/aphronio/dorf/issues
Project-URL: Documentation, https://github.com/aphronio/dorf/tree/main/docs
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent-runtime,ai-agents,automation,codex,control-plane,incus
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: typer>=0.12.0
Requires-Dist: websockets>=15.0
Description-Content-Type: text/markdown

# Dorf

**A control plane for durable AI workers on infrastructure you control.**

Dorf gives an AI worker a durable identity, an isolated Room, and an explicit Job. Start work,
leave, reconnect, inspect what changed, steer it, or clean it up without treating one terminal or
client process as the source of truth.

Workers do Jobs in Rooms. A **Worker** is the durable harness identity, a **Room** is its isolated
execution boundary, a **Job** is a pinned goal with its own conversation and evidence, and an
**Assignment** records which Worker and Room own that Job.

> [!IMPORTANT]
> Dorf is alpha software. The current verified path is Codex in local Incus VMs on x86_64 Linux,
> with automatic host convergence reviewed on Arch Linux. No other harness or Room backend is
> supported yet. The official public Room image has not been published, so the fresh-machine
> `dorf setup` path is not complete in this release.

## Why Dorf

- **Durable work, replaceable processes.** Worker and Job identity outlive a CLI invocation,
  controller restart, or disconnected client.
- **Owned isolation.** Work runs in a private VM Room instead of sharing the host Docker socket or
  an unbounded host shell.
- **Detached by default.** Admit a message once, leave, and later inspect the same Worker or Job
  rather than babysitting a token stream.
- **Explicit lifecycle.** Recovery and cleanup operate on recorded Worker, Room, Job, and
  Assignment identity; failures remain visible and retryable.
- **A composable runtime.** The control plane owns mechanisms. Applications own workflow policy,
  acceptance, and presentation.

The product direction is broader than the first adapter pair, but the support claim is deliberately
narrow. Dorf adds another harness or Room backend only after a real implementation validates the
seam. See the
[North Star](https://github.com/aphronio/dorf/blob/main/docs/project/north-star.md) for the
destination and
[Runtime Surface](https://github.com/aphronio/dorf/blob/main/docs/project/runtime.md) for what
exists now.

## Available today

| Layer | Current support |
| --- | --- |
| Runtime | Durable Workers, Rooms, Jobs, Assignments, message admission, inspection, recovery, evidence, and cleanup |
| Agent harness | Codex app-server |
| Room backend | Local Incus virtual machines |
| Model access | Named ChatGPT-subscription and OpenAI API-key connections through the local Provider Gateway |
| Host setup | x86_64 Arch Linux convergence; other x86_64 Linux hosts may work with an already usable Incus installation |
| Dogfood application | Coding-to-PR, including isolated clones, repo-owned checks, review, follow-up, and PR proposal |

Multiple harnesses, alternative sandbox providers, remote Room backends, Worker pools, scheduling,
and cross-Worker reassignment are direction—not current capabilities.

## Install the alpha CLI

Install from PyPI with:

```bash
uv tool install dorf
dorf --version
dorf --help
```

Installing the CLI does not yet provide the complete fresh-machine Worker path described in the
North Star. Until the official Room image is published, use Dorf on a configured development host
or explore the runtime and CLI surfaces without provisioning a Worker.

To work from source:

```bash
git clone https://github.com/aphronio/dorf.git
cd dorf
uv sync --all-groups
uv run pytest
uv run ruff check .
uv run dorf --help
```

## Core loop

On a configured host, create a Worker and assign a Job with a complete goal:

```bash
dorf worker spawn ada
dorf job assign checkout-perf \
  --to ada \
  --goal "Make checkout feel instant and leave evidence"
```

Message and inspect the Worker or its Job independently:

```bash
dorf worker message ada "What can you help with?"
dorf worker wait ada
dorf worker inspect ada

dorf job message checkout-perf "Profile the API first"
dorf job wait checkout-perf
dorf job inspect checkout-perf
dorf job inspect checkout-perf --timeline
dorf job inspect checkout-perf --evidence
```

Enter the current Room when direct takeover is useful:

```bash
dorf worker attach ada
```

End the Job before ending its Worker. Cleanup is bound to the exact recorded resources:

```bash
dorf job end checkout-perf
dorf worker end ada
```

The same authority is available in process through the typed Python facade:

```python
from dorf import Dorf

with Dorf.open() as dorf:
    inspection = dorf.inspect_worker("ada")
    receipt = dorf.message_worker(
        "ada",
        "Profile the API first",
        action_id="caller-stable-action-id",
    )
```

Run `dorf worker --help` and `dorf job --help` for the complete current command surface.

## Coding-to-PR showcase

Coding-to-PR is Dorf's current dogfood application, not the runtime's identity. One coding task
composes one goal-backed Job, Assignment, isolated clone, branch, and PR proposal:

```bash
dorf start "Implement the task" --provider-connection personal-chatgpt
dorf status JOB
dorf verify JOB
dorf publish JOB
dorf complete JOB
```

Repositories declare deterministic setup, check, smoke, and review commands in `.dorf.toml`. Git
and GitHub remain authoritative for branches, commits, and PR state; the harness remains
authoritative for its native conversation history.

## Architecture boundary

```text
dorf.runtime     portable Worker, Room, Job, and Assignment mechanisms
dorf.sdk         in-process facade used by the CLI and host applications
dorf.adapters    current Codex and Incus integrations
dorf.workflows   coding-to-PR policy composed over the runtime
```

Runtime code does not import coding, GitHub, Incus, or Codex policy. Remote Rooms remain an adapter
concern; Dorf does not need to become a hosted service merely because an adapter controls remote
infrastructure.

## Documentation

- [North Star](https://github.com/aphronio/dorf/blob/main/docs/project/north-star.md) — approved product direction
- [Principles](https://github.com/aphronio/dorf/blob/main/docs/project/principles.md) — product and engineering judgment
- [Runtime Surface](https://github.com/aphronio/dorf/blob/main/docs/project/runtime.md) — current portable boundary
- [Decision Log](https://github.com/aphronio/dorf/blob/main/docs/project/decisions.md) — accepted choices and reconsideration triggers
- [Provider Gateway](https://github.com/aphronio/dorf/blob/main/docs/project/provider-gateway.md) — model connection and scoped route boundary
- [Setup support](https://github.com/aphronio/dorf/blob/main/docs/support.md) — current host support and diagnostics
- [Contributing](https://github.com/aphronio/dorf/blob/main/CONTRIBUTING.md) — development workflow and DCO sign-off
- [Security policy](https://github.com/aphronio/dorf/blob/main/SECURITY.md) — private vulnerability reporting

Dorf is licensed under the
[Apache License 2.0](https://github.com/aphronio/dorf/blob/main/LICENSE). The runtime and Python SDK
remain experimental and do not yet carry a third-party compatibility promise. Material under
`docs/research/` is archival and non-normative.
