# Cloud Orchestrator — calibrate & plan a repo, live

> ⚠️ **Experimental — limited preview.** Off by default. With the flags below
> unset, your Arth Intelligence install behaves exactly as it does today. Turn it
> on only to try it; interfaces may change between releases. Feedback:
> productive@getarth.ai.

> **Default (production) Arth Intelligence shows observability only — no
> Orchestrator.** The latest image *ships* all the Cloud Orchestrator components,
> but they stay **completely hidden** until you explicitly set the flags in this
> guide. Updating to the latest version changes nothing you can see: you still get
> just the normal Sessions / DAG / Story / Cost dashboard. The Orchestrator
> ("☁ Calibrate a repo", the Runs screens) appears **only** after you opt in here.
> Not interested? Do nothing — there's no orchestration to see.

Point Arth at one of your Git repos and watch it **calibrate** it (analyze the repo
→ project profile + recommendations) or **plan a feature** (→ PRD + design) —
**live**, inside the same Arth Intelligence dashboard you already run. Each run also
lands in your normal Sessions / DAG / Story views.

## Why you'd want it

- **One-click repo onboarding** — calibrate a repo to get an architecture profile,
  conventions, domain model, and recommendations without running anything by hand.
- **Plan before you build** — describe a feature, get a structured PRD + design.
- **Watch it happen** — a live control room shows each phase, plain-English
  narration, and running cost.
- **Stays on your machine** — the analysis runs in a throwaway container on **your
  own host**; results go into **your own** Arth database. Nothing goes to a
  third-party Arth service.

## How it works

```mermaid
flowchart LR
    B["Browser<br/>localhost:3100"] --> DA["Arth dashboard<br/>(arthai-intelligence)"]
    DA -- "docker run<br/>(host socket)" --> SB["Disposable sandbox<br/>arthai/cloud-sandbox<br/>clones repo · runs toolkit"]
    SB -- "OTEL → http://app:3000" --> DA
    DA --> DB[(Postgres<br/>arthai_data)]
    DB --> HUB["Sessions / DAG / Story"]
```

When you start a run, the dashboard launches a **short-lived sandbox container** on
your host's Docker. It clones the repo, runs the Arth toolkit (`/calibrate` or
`/planning`), and streams progress back. When it finishes it uploads results and
disappears. The run shows up both **live** (Orchestrator) and **afterward**
(Sessions / DAG / Story).

## Components

| Component | Role |
|---|---|
| **Arth Intelligence** (`arthai/intelligence`) | The dashboard + the Orchestrator screens + your database. Launches and supervises runs. |
| **Sandbox image** (`arthai/cloud-sandbox`) | The disposable per-run container that clones your repo and runs the toolkit. Pulled from Docker Hub. |
| **Your Docker host** | Where each sandbox runs. The dashboard needs your Docker socket to launch sandboxes. |

---

## Setup

### The two setup paths

Setup is always **two parts, in this order**: first stand up the telemetry stack, then
add the cloud keys. Pick the row that matches how you run Arth — the order never
reverses (the cloud-keys command checks that the stack is already up).

| | **First: telemetry stack** | **Then: cloud keys** |
|---|---|---|
| **With the toolkit** (in Claude Code) | `/otel-setup` → pick *Local* | `/cloud-setup` |
| **Without the toolkit** (terminal / Arth CLI) | `arth otel-setup` | `arth cloud-setup` |

Both telemetry-stack commands stand up the **same** stack — db + dashboard on :3100 +
engine on :4319 — and write the native-OTEL env globally. `arth otel-setup` just does it
without the toolkit. (See [Getting Started Step 7](getting-started.md#step-7-enable-observability-optional).)

> **Using the `arth` CLI?** Install it first — it ships through the private Arth repo and
> is gated by your GitHub access (no public package): see
> [Installing the Arth CLI](getting-started.md#installing-the-arth-cli-no-toolkit). Then
> `arth otel-setup` / `arth cloud-setup` are available in your terminal.

The rest of this guide details the **cloud-keys** part (Steps 1–3 below) — run it with
`/cloud-setup` or `arth cloud-setup`, which automate it, or follow the manual steps.

> **Set up telemetry with `arth otel-setup` first, then installed the toolkit later?**
> Running `/otel-setup` afterward **detects the existing stack** and only adds the
> toolkit's `skill.name`/agent attribution — it won't redo the stack or re-write the env.

### Prerequisites

- A working **Arth Intelligence** install — Step 1 above (the telemetry stack) done.
- **Docker** running on the host.
- **`ANTHROPIC_API_KEY`** — the sandbox runs Claude headlessly. **The orchestrator is
  Claude-only (for now)**, independent of your Explain provider: if you set Explain to a
  non-Claude provider (OpenAI/Gemini/Ollama/LM Studio), you still need a Claude key here.
  If Explain already uses Claude, that key is reused — `/cloud-setup` won't ask twice.
- **`ARTH_GITHUB_TOKEN`** with read access — **required**: the Arth toolkit marketplace
  is a private repo, so the sandbox needs it to install the toolkit (it also covers
  private target repos). Without it the toolkit install fails and `/calibrate` won't run.
  **How to create it:** github.com → **Settings → Developer settings → Fine-grained
  tokens → Generate new token** → Resource owner **`ArthTech-AI`**, Repository access →
  the toolkit repo **`ArthTech-AI/arthai-marketplace`**, Permissions → **Contents: Read-only**
  → Generate. (Classic PATs work too with `repo:read`.) Already use the `gh` CLI? `gh auth
  token` prints a usable token *if* that login can read the private toolkit repo.
- Your **`ARTH_LICENSE_KEY`** — **required**: the toolkit is license-gated. If you've
  already run `npx arthai-activate ARTH-…`, it's saved at **`~/.arthai/license`** — `/cloud-setup`
  reads it from there automatically; otherwise it's the `ARTH-XXXX-…` key from your
  activation email.

### Step 1 — Add the secrets

Put these in `~/.arthai/.env` (the compose expands `${...}` from there):

```bash
ANTHROPIC_API_KEY=sk-ant-...
ARTH_GITHUB_TOKEN=ghp_...        # required — the toolkit marketplace is private
ARTH_LICENSE_KEY=ARTH-XXXX-XXXX-XXXX-XXXX   # required — the toolkit is license-gated
```

### Step 2 — Turn on the flags + Docker access

Two easy paths write everything below for you (both also configure the Explain
summary); `/otel-setup` itself stays telemetry-only:

- **In Claude Code (toolkit):** run **`/cloud-setup`**.
- **From a terminal (no toolkit):** run **`arth cloud-setup`** (the Arth CLI ships
  the same interactive flow).

To do it by hand instead, create an **override file** next to your compose — this
keeps the base `~/.arthai/docker-compose.yml` untouched (and reversible):

```bash
cat > ~/.arthai/docker-compose.override.yml << 'YAML'
services:
  app:
    environment:
      ARTH_ORCHESTRATE_ENABLED: "1"
      ARTH_CLOUD_RUNS_ENABLED: "1"
      ARTH_CLOUD_EXECUTOR: container
      ARTH_CLOUD_SANDBOX_IMAGE: arthai/cloud-sandbox:latest
      ARTH_CLOUD_HUB_BASE: http://app:3000            # internal callback URL
      ARTH_CLOUD_DOCKER_ARGS: "--network arthai_default"
      # Marketplace the sandbox installs the toolkit from (this install's marketplace).
      ARTH_CLOUD_TOOLKIT_MARKETPLACE: ArthTech-AI/arthai-marketplace
      ARTH_GITHUB_TOKEN: ${ARTH_GITHUB_TOKEN:-}
      ARTH_LICENSE_KEY: ${ARTH_LICENSE_KEY:-}
      # ANTHROPIC_API_KEY is already set on the base service (used by Explain) — reused here.
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock     # lets the dashboard launch sandboxes
YAML
```

> **Network name:** sandboxes launch as siblings on your host's Docker and must
> reach the dashboard. The compose network is named after the directory — for
> `~/.arthai/` it's **`arthai_default`**. Confirm with `docker network ls` after
> Step 3 and adjust `ARTH_CLOUD_DOCKER_ARGS` if yours differs.

> **🔒 Security:** mounting the Docker socket grants the container host-level Docker
> access. Fine for **one person running their own trusted repos on their own
> machine** — this setup. Not for untrusted repos or shared/multi-user hosts.

### Step 3 — Bring the containers up

First pull the sandbox image (it's not a compose-managed service, so compose won't pre-pull it):

```bash
docker pull arthai/cloud-sandbox:latest
```

Then pass **both** files so the override merges in (explicit `-f` disables auto-merge):

```bash
docker compose -f ~/.arthai/docker-compose.yml \
               -f ~/.arthai/docker-compose.override.yml up -d
```

Confirm both containers are healthy:

```bash
docker ps --format '  {{.Names}}\t{{.Status}}'
#   arthai-intelligence   Up (healthy)
#   arthai-db             Up (healthy)
```

---

## Walkthrough — your first calibrate (in the browser)

1. **Open the dashboard** in Chrome: **`http://localhost:3100`**.
2. You'll now see an **Orchestrator** surface with a **Runs** area (it appears only
   because the flags are on). Click **☁ Calibrate a repo** — or go straight to
   **`http://localhost:3100/cloud/new`**.
3. Paste a GitHub repo URL, e.g. `https://github.com/your-org/your-repo`, and click
   **Calibrate in Cloud**.
4. **Watch it run.** A live control room shows the phase rail
   (Scan → Evaluate → Profile → Recommend → Install → Verify), a plain-English
   narration that updates as it goes, and a running cost.
   - Behind the scenes a sandbox container named `arth-cloud-<run-id>` spins up;
     you can see it with `docker ps` while the run is active.
   - **Answer questions in the browser.** When calibrate needs your input (e.g. the
     **install choice** — Install all / Pick items / Skip), an amber card appears in
     the run window. Single-select questions show radio-style choices; multi-select
     questions show checkboxes + a **Submit** button. Pick, and the run continues —
     the card advances through multiple questions with no page reload.
5. **When it finishes**, open the run's **Findings** page at
   **`http://localhost:3100/runs/<run-id>/findings`** — the project profile,
   domain model, and recommendations render there.
6. **Confirm it's also in your Hub:** go to **Intelligence → Sessions** (and open
   its **DAG** / **Story**). The same run appears for after-the-fact inspection, and
   the **Story** view includes an **Interactive Q&A** panel showing every question
   you answered. Use **← back to run** on the session to return to the run.

### Plan a feature

On `/cloud/new`, switch to **Plan a feature**, paste the repo URL, give a short
feature name and a brief, and click **Plan in Cloud**. Planning first asks **1–3
clarifying questions** in the browser (scope / target tier / the brief's open
points) — answer them and it generates the PRD and design spec, reflecting your
answers. The Findings page (and **Knowledge → Planning**) shows the result.

### What to check (quick sanity list)

| Check | Where | Expect |
|---|---|---|
| Feature is on | `http://localhost:3100` | A **Runs / Orchestrator** area + a **☁ Calibrate a repo** button |
| Launcher | `http://localhost:3100/cloud/new` | Calibrate / Plan tabs + a repo URL field |
| Run is live | the run page | Phase rail advancing + narration updating |
| Interactive Q&A | the run page | an amber card when input is needed (install choice; planning clarifications) → answer in-browser |
| Sandbox launched | terminal: `docker ps` | a `arth-cloud-...` container during the run |
| Findings | `/runs/<run-id>/findings` | profile + recommendations (or PRD for planning) |
| Knowledge | Knowledge → project | Calibrate + Planning tabs; LLM digest; C4 graph |
| In the Hub | Intelligence → Sessions | the run listed, with DAG / Story (+ Interactive Q&A panel) |

---

## After it runs — the Knowledge view

With the feature on, the dashboard groups into **three lenses** (the default,
flag-off install is unchanged — just your usual Observability dashboard):

- **⚡ Orchestrator** — launch & watch runs live (**+ New Run**, Runs).
- **📚 Knowledge** — what Arth learned about your repos (this is where calibrate/
  planning outputs live).
- **📊 Observability** — your existing Sessions / DAG / Story / Cost (was "Hub").

Open **Knowledge** → pick a project. Each project has **two tabs**:

- **Calibrate** — the latest calibrate, rendered visually (not raw markdown):
  - a **✨ "What Arth found in your codebase"** digest — an LLM-written summary +
    key highlights so you instantly learn the headline facts (generated with Haiku
    at run-end using your `ANTHROPIC_API_KEY`);
  - a **Latest update** strip (what changed since the last rescan);
  - **tech-debt severity** bars;
  - an **interactive C4 knowledge graph** — start at the container level
    (Conventions / Patterns / Domain / Decisions / Vocabulary) connected by
    relationship lines; **click a container to drill into its nodes**; drag/zoom;
  - the **agents tuned for this repo**, plus a scannable, navigable view of
    conventions / patterns / domain / best-practices (jump-nav + collapsible
    sections), and a **rescan history**.
- **Planning** — your plans (not nested under Calibrate). The latest plan is the main
  view (its own **"What Arth found planning this feature"** digest — what was asked,
  feasibility, key decisions, which agents took part), with an **All plans** switcher
  grouping every plan by feature + an overview line (e.g. *3 features planned · 2
  GREEN, 1 YELLOW*).

It's **incremental**: re-running calibrate updates the Calibrate tab and adds to the
rescan history; planning a new feature adds to the Planning tab. Terminal sessions on
the same repo keep using the **plain knowledge files** as before — these views are a
visual, navigable picture of them (the LLM digest is dashboard-only and never written
into your `.claude/` files).

> 🧪 Still experimental — the Knowledge views may change between releases.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| No **Runs / Calibrate a repo** in the UI | Flags not set. Ensure `ARTH_ORCHESTRATE_ENABLED` and `ARTH_CLOUD_RUNS_ENABLED` are `"1"`, then `docker compose ... up -d` to recreate the container. |
| Run starts but never progresses / looks stuck | The sandbox can't reach the dashboard. Check `ARTH_CLOUD_HUB_BASE` is `http://app:3000` **and** `ARTH_CLOUD_DOCKER_ARGS` uses your real network (`docker network ls` → `arthai_default`). |
| Sandbox never starts | Docker socket not mounted into `app`, or Docker not running on the host. |
| Private repo won't clone | `ARTH_GITHUB_TOKEN` missing or lacks read access. |
| Calibrate runs but didn't install the toolkit into my repo | Expected — by default it writes a profile **without** installing into your repo. |

## Limits (while experimental)

- **Self-host, single user.** Not for shared/multi-user hosts.
- **One repo per run**; monorepo sub-path selection isn't available yet (calibrate
  runs at the repo root).
- **Calibrate doesn't write back into your local repo by default** — it produces a
  profile + recommendations you review in the browser; installing into your working
  copy is a separate step.

## Turn it off / remove

Delete `~/.arthai/docker-compose.override.yml` and run
`docker compose -f ~/.arthai/docker-compose.yml up -d` — the screens disappear and
you're back to plain Arth Intelligence. To clean up leftover sandboxes/image, see
the [Uninstall guide](uninstall.md#step-4b--remove-cloud-orchestrator-leftovers).

## Related

- [Arth Intelligence](arth-intelligence.md) — the dashboard this builds on
- [Getting Started](getting-started.md) — install + observability
- [Uninstall](uninstall.md) — teardown