# Install and bootstrap

## Package surfaces

Millrace currently ships with these public package surfaces:

- package name: `millrace-ai`
- import namespace: `millrace_ai`
- installed CLI: `millrace`
- module entrypoint: `python -m millrace_ai`

## Install

Installed environment:

```bash
pip install millrace-ai
```

Source-development module form:

```bash
uv run --extra dev python -m millrace_ai --help
```

## Workspace model

Millrace is workspace-scoped. It bootstraps its runtime tree under:

```text
<workspace>/millrace-agents/
```

The default runtime config path is:

```text
<workspace>/millrace-agents/millrace.toml
```

That tree holds the markdown work queues, runtime snapshot state, compile outputs, mailbox/control files, Arbiter artifacts, and per-run execution artifacts.

## First validation commands

Once installed, the safest first commands are:

```bash
millrace compile validate --workspace <workspace>
millrace status --workspace <workspace>
millrace queue ls --workspace <workspace>
```

Those commands validate the effective config, compile the active mode, surface runtime state, and show queue counts without forcing long-running execution.

## First execution commands

Run one bounded startup-plus-tick cycle:

```bash
millrace run once --workspace <workspace>
```

Run repeated ticks until stop or interrupt:

```bash
millrace run daemon --workspace <workspace>
```

The daemon form is for an actual long-running operator posture. `run once` is the safer choice when you want one controlled progression step.

## Baseline harness posture

The shipped canonical runtime modes are:

- `default_codex`
- `default_pi`

The compatibility alias `standard_plain` resolves to `default_codex`.

The shipped built-in runner adapters are:

- `codex_cli`
- `pi_rpc`

That means Millrace ships a real runtime layer plus built-in harness bindings, rather than shipping only prompts.

## After install: inspect rather than guess

Use these surfaces to inspect the real compiled state:

```bash
millrace compile show --workspace <workspace>
millrace modes list --workspace <workspace>
millrace modes show default_codex --workspace <workspace>
millrace config show --workspace <workspace>
```

Use these surfaces to watch or inspect runs:

```bash
millrace status watch --workspace <workspace>
millrace runs ls --workspace <workspace>
millrace runs show <run_id> --workspace <workspace>
millrace runs tail <run_id> --workspace <workspace>
```

## What gets bootstrapped

Millrace bootstraps:

- the `millrace-agents/` runtime root
- workspace entrypoints under `millrace-agents/entrypoints/`
- default state and status files under `millrace-agents/state/`
- runtime control surfaces such as mailbox and lock files

New workspaces default to the canonical Codex posture through `default_codex`, while the package also ships the Pi mode and adapter.

## What installation does not change

Installing Millrace does not turn it into a hosted service or IDE. It remains a local runtime that wraps raw harness execution with deterministic orchestration, durable state, and inspection surfaces.

See also:

- `/ai/cli-reference.md`
- `/ai/runner-architecture.md`
- `/ai/architecture.md`