Quickstart¶

This guide gets you from an empty directory to a local MoiraWeave stack with a working demo agent, dashboard, runs, events, and artifacts.

Prerequisites¶

• Python 3.13 or newer
• uv
• Docker and Docker Compose

1. Install The CLI¶

uv tool install moiraweave-cli
moira --help

2. Create A Workspace¶

mkdir my-moiraweave-workspace
cd my-moiraweave-workspace
moira init --non-interactive

The workspace contains:

.moiraweave/
  workloads/
  artifacts/
  deploy/
moiraweave.yaml
.env
docker-compose.yml

The generated Compose stack includes API Gateway, worker, Postgres, Redis, Qdrant, and the Ops dashboard.

3. Add A Demo Agent¶

moira demo agent

This writes .moiraweave/workloads/demo-agent/workload.yaml. It uses a local mock HTTP agent, so the first run needs no OpenAI key, Hermes runtime, or OpenClaw runtime.

4. Start Everything¶

moira up

moira up initializes the workspace if needed, generates local workload Compose services, starts the platform and workloads, waits for API readiness, and registers workload/deployment records.

Open http://localhost:3000, then sign in with:

admin / demo-password

5. Use The Product Flow¶

In the dashboard:

• Workloads: create workloads from templates or inspect registered manifests.
• Operations: run preflight, view deployment plans, and sync deployment records.
• Agents: create a session, send a message, and follow the linked run status.
• Runs: inspect event timelines, payloads, results, cancellation, and artifacts.
• Artifacts: browse by workload, session, run, and content type.

The simple product loop is:

create workload -> deploy/connect runtime -> interact -> observe -> correct

Hermes And OpenClaw¶

For real agent runtimes, create them from the UI templates or CLI manifests:

moira workload new hermes \
  --type agent-service \
  --image ghcr.io/nousresearch/hermes-agent:latest \
  --service-name hermes \
  --mode session \
  --timeout-seconds 172800 \
  --adapter hermes \
  --port 8642 \
  --secret OPENAI_API_KEY \
  --secret HERMES_API_SERVER_KEY \
  --auth-token-env HERMES_API_SERVER_KEY \
  --persistence \
  --mount-path /workspace \
  --workspace-mount /workspace

MoiraWeave deploys and supervises the runtime, but Hermes/OpenClaw keep their own reasoning loop, tools, memory, and runtime-specific configuration.

CLI Boundaries¶

The UI never talks directly to Docker, Kubernetes, Redis, or the filesystem. Local execution runs through moira up, moira deploy local, and Docker Compose. Kubernetes execution should run through CLI, CI, or a deployment controller/operator.

Troubleshooting¶