arthai-marketplace

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

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.)

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. 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):

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):

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):

docker pull arthai/cloud-sandbox:latest

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

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

Confirm both containers are healthy:

docker ps --format '  \t'
#   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.

Related

• Arth Intelligence — the dashboard this builds on
• Getting Started — install + observability
• Uninstall — teardown