> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useharmonia.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Inspect Harmonia locally, then choose whether to configure authenticated Google execution.

## Prerequisites

* Node.js 20+
* Python 3.12+ (a 3.14 venv works)
* `gcloud` CLI with the Firestore and Pub/Sub emulators (use a currently supported JRE)
* `ffmpeg` and `ffprobe` on PATH
* `yt-dlp` on PATH (for YouTube ingestion)

## Choose a run mode

Local inspection and authenticated execution are different claims:

| Mode                         | Purpose                                                                                | What it proves                                   |
| ---------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------ |
| Persisted fixture inspection | Review the studio, state transitions, approvals, assets, and failure presentation      | UI and local data-contract behavior only         |
| Authenticated cognitive job  | Invoke configured Google identity, Agent Engine, Gemini, and managed memory boundaries | Only the providers captured in that specific run |

Fixtures are never submission evidence for a provider invocation or deployment. Authenticated execution can incur provider charges; inspect pricing and quota before enabling it.

## Start the local services

```bash theme={"system"}
./scripts/dev.sh
```

This single script starts everything:

| Service              | Port |
| -------------------- | ---- |
| Firestore emulator   | 8081 |
| Pub/Sub emulator     | 8082 |
| Next.js dashboard    | 3000 |
| ADK worker (FastAPI) | 8080 |

The script sources `.env.local` if present. The web and worker must share a non-empty internal token:

```bash theme={"system"}
INTERNAL_API_TOKEN=local-dev-token
```

## Inspect persisted fixtures

With the stack running:

```bash theme={"system"}
node scripts/seed-demo.mjs
```

This populates clearly labeled fixture jobs in several states, content items, chat history, and locally rendered ffmpeg assets. Everything lives only in the emulator. The records demonstrate rendering and UI contracts; they are not evidence that Gemini, Agent Engine, Memory Bank, Pub/Sub in Google Cloud, or an external publishing API ran.

> **Note:** re-seeding wipes existing `content_items` and `notifications` in the emulator.

## Run an authenticated cognitive job

Before this path can succeed, configure the values documented in [Configuration](/configuration), including Google Identity Platform, application credentials, `AGENT_SERVICE_URL`, the shared `INTERNAL_API_TOKEN`, `AGENT_ENGINE_RESOURCE`, and the exact regional model and memory resources used by the worker. There is no in-process ADK fallback.

Open [http://localhost:3000](http://localhost:3000) and send the console:

```
turn https://www.youtube.com/watch?v=jNQXAC9IVRw into clips
```

Watch the job progress through ingest → transcribe → understand → strategize and stop for digest-bound strategy approval. After approval, Temi plans and the production team drafts before the separate effect-approval boundary. In chat, an approval phrase opens the same deterministic confirmation; model-parsed text cannot authorize strategy or an effect by itself.

After approval, only configured actions can execute. An export can be verified by digest; X requires authorized credentials and is verified by a fresh provider read. A failed or unavailable integration stays visible as an unresolved failure rather than becoming simulated success.

## Run checks

```bash theme={"system"}
npm run lint && npx tsc --noEmit && npm test
cd agent && ./.venv/bin/python -m pytest tests -q
```

Next: read [Development](/development) to work fully offline, or jump to [Configuration](/configuration) for the full environment variable reference.