# Agent Runtimes Control Plane

## Which CP to use

**Always use the hosted CP (`agents.oreillyit.nz`) for real agent work.** Localhost is for testing only.

| Use case | CP to use |
|---|---|
| Real implementation tasks, spec work, any multi-step agent work | `https://agents.oreillyit.nz/api` |
| Smoke-testing a new task payload format, debugging CP behaviour locally | `http://localhost:8100` |

Reason: workloads on the hosted CP are not coupled to this laptop's uptime. If the laptop sleeps or is closed, tasks on localhost stall or die. Tasks on the hosted CP keep running.

Since the M11 dashboard deployment, Traefik routes `/` to the React dashboard and `/api/*` to the CP API. Always use `https://agents.oreillyit.nz/api` as the CP_URL — not the bare hostname.

```bash
export CP_URL=https://agents.oreillyit.nz/api
scripts/dispatch-task --login ...   # first time per session — opens browser for OIDC
scripts/agent-monitor --login --filter "project=<project-name>" --filter "age<1h"
```

## Task dispatch — always use a template or workflow

**Never submit tasks via raw `curl` without explicit user approval.** Raw curl bypasses:
- Harness selection (agents start in empty containers with no credentials or context)
- `pre_actions` clone (agents have no repo to work on)
- `agent_repo` persistence (work is lost when the container exits)
- `requires_tags` validation (tasks may be picked up by incompatible dispatchers)

Default approach — always one of:
1. `scripts/dispatch-task --template <name>` for single implementation tasks
2. `scripts/dispatch-workflow` for multi-node DAG workflows
3. `/manual-workflow` skill for interactive workflows with human review gates

## Template selection

| Work type | Template |
|---|---|
| Backend/CP implementation (migrations, APIs) | `opus-code-repo` |
| Frontend implementation | `sonnet-code-repo` |
| Planning / architecture | `opus-planning` |
| Security review | `opus-security-review` |
| Spec writing | `opus-spec-writer` |
| Test writing | `opus-test-writer` |

Standard params for all code templates:
```bash
--template-param repo_url=git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes.git \
--template-param agent_repo_url=git@gitea.oreillyit.nz-ai-enablement:skynet/agent-runtimes-agents.git
```

If raw curl is genuinely needed (e.g., testing a new payload field), state the reason and get explicit user confirmation before submitting.

## Monitoring

Recommend the user run **agent-monitor** in a separate terminal:

```bash
scripts/agent-monitor --login --filter "project=<project-name>" --filter "age<1h"
```

Adjust `age` to suit the session — `1h` is a good default for hosted CP work since tasks persist across laptop sleep.

For full control plane usage (submitting tasks, checking logs, cancelling, common workflows): **`~/dev/claude/projects/agent-runtimes/readme/control-plane-operations.md`**.