# Quickstart: ship your first task

This quickstart takes one local project from your machine to **agent output you can read** — an imported project, a running orchestrator, a task that changed files, and the verified diff behind it.

**Video:** A 64-second walkthrough of the five steps on this page: hlix import binds a folder to a cloud project, a POST to the start endpoint hands a brief to the orchestrator, the dashboard shows one orchestrator and six worker agents, hlix tasks watch streams queued through done, and hlix tasks review prints the evidence document with filesChanged 3 and an approved evaluator verdict.

The video is a dramatisation of the steps below — read them for the detail, and for anything the video moves past too quickly.

## Prerequisites

- The [`hlix` CLI installed](/getting-started/install/) and [authenticated](/getting-started/authentication/)
- A workspace ID and an API key from [Developer tools → API keys](https://app.hlix.ai/developer-tools/api-keys)
- Git, and a project directory you are authorized to upload
- Model access configured for the workspace — hlix calls models with your provider keys

Export the two values once; every API step below reuses them.

```bash
export HLIX_API_KEY='…'
export HLIX_WORKSPACE_ID='<workspace-id>'
export HLIX_BASE_URL='https://server.hlix.ai'
```

## The five steps

1. **Import the project.** Start with a dry run so you see exactly what leaves your machine.

   ```bash
   cd path/to/project
   hlix import . --dry-run
   hlix import .
   ```

   Expected result:

   ```text
   Imported acme-invoices
   Project ID: 6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
   Revision: 1
   ```

   Copy the project ID — the next step needs it. If the dry run reports blockers, resolve them before continuing; [Import a project](/cli/import/) lists each blocker and its fix.

   ```bash
   export PROJECT_ID='6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41'
   ```

   `hlix status` confirms the binding took, and is the command to reach for whenever you are unsure which workspace a folder actually points at:

   ```text
   folder      /Users/you/acme-invoices
   workspace   org_2p9xk4 (from project)
   api         https://server.hlix.ai (from project)
   credential  file (/Users/you/.config/hlix/credentials.json)
   project     6f1c2a9e-8f0b-4a7d-9d33-2f0b1c7e5a41
   revision    generation 1 (rev_01J8Z4)
   local       412 files, matches the last sync
   cloud       generation 1, up to date
   ```

2. **Start the run with a brief.** The brief is the whole instruction — the project orchestrator turns it into a roadmap, then into cycles and tasks. Write an outcome, not a file list.

   **In the dashboard:** open [app.hlix.ai](https://app.hlix.ai/), pick the imported project, and describe the outcome in the composer. It calls the same endpoint as the API path.

   **Over the API:**

   ```bash
   curl -sS -X POST "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/start" \
     -H "x-api-key: $HLIX_API_KEY" \
     -H "X-Organization-Id: $HLIX_WORKSPACE_ID" \
     -H 'content-type: application/json' \
     -d '{"brief":"Add a health endpoint at GET /healthz that returns 200 with the build SHA, and cover it with a test."}'
   ```

   Expected result:

   ```json
   {"started":true}
   ```

   `started: true` means the run was handed to the engine, not that it has finished. The run proceeds asynchronously from here.

3. **Find the task the orchestrator created.** Planning takes a little time; the first task usually appears within a minute or two.

   ```bash
   hlix tasks list
   ```

   Run from inside the imported folder, this needs no arguments — it defaults to the project this folder is bound to. Expected result:

   ```text
   ID                                    STATUS    TITLE
   ------------------------------------  --------  ------------------
   b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90  queued    Add GET /healthz
   ```

   `No tasks.` means planning has not produced any yet. Wait and re-run it rather than starting a second run.

   ```bash
   export TASK_ID='b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90'
   ```

4. **Watch the agent work.** `hlix tasks watch` consumes the server's status stream and exits when the task reaches a terminal status.

   ```bash
   hlix tasks watch "$TASK_ID"
   ```

   Expected result — one line per status change, ending at a terminal status:

   ```text
   queued
   building
   testing
   reviewing
   done
   ```

   Add `--json` to get one envelope per line (JSONL) instead, which is what automation should read.

5. **Read what it delivered.** This is the point of the walkthrough — the verified evidence behind the change, the same observation the QA evaluator reviewed.

   ```bash
   hlix tasks review "$TASK_ID"
   ```

   Expected result — the evidence document, abridged:

   ```json
   {
     "taskId": "b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90",
     "source": "github-compare",
     "observedAt": "2026-08-07T09:14:22.481Z",
     "baseRef": "1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d",
     "headRef": "hlix/ms-0a9b8c7d-6e5f-4a3b-8c9d-0e1f2a3b4c5d/task-b4a1f0d23c77",
     "headSha": "9f2c1b0ae4d5768a3c2f1e0d9b8a7c6d5e4f3a2b",
     "comparison": { "status": "ahead", "aheadBy": 2, "behindBy": 0 },
     "filesChanged": 3,
     "additions": 74,
     "deletions": 1,
     "commits": 2,
     "files": [
       { "path": "src/routes/healthz.ts", "status": "added", "additions": 41, "deletions": 0, "patch": "@@ -0,0 +1,41 @@\n+…" }
     ],
     "evaluator": { "verdict": "approved", "summary": "Endpoint added with a passing test.", "stale": false }
   }
   ```

   That `files[].patch` is the diff an agent produced, read back from the repository host — not a summary the agent wrote about itself. Where a change is decisive, [Reviewing output](/running/review/) explains how to comment on a line and send it back.

## What just happened

```text
hlix import .              your folder ──▶ a cloud Project (revision 1)
POST /projects/:id/start   your brief  ──▶ the project's Orchestrator

   Orchestrator
     │  plans a roadmap
     ▼
   Cycle
     │  dispatches a wave of tasks
     ▼
   Task ──── one worker agent, its own git worktree and branch
     │  commits, then reports the result back
     ▼
   QA evaluator ──▶ the review evidence you just read
```

One orchestrator ran for the project, a worker agent did the coding in its own git worktree inside the project's [Coding Workspace](/concepts/coding-workspace/), and the QA evaluator judged the result before you saw it. Nothing about that loop is per-task infrastructure: the same sandbox is reused by every task this project ever runs.

## If a step fails

- ``No credential. Run `hlix auth login`, or set HLIX_API_KEY for CI.`` — the CLI has no stored login. See [Authenticate](/getting-started/authentication/).
- ``This folder is already bound to an Hlix project. Use `hlix push`.`` — the folder was imported before. Use [`hlix push`](/cli/sync/) to send a new revision instead of importing again.
- ``Import needs approval for protected files or cloud setup. Review with `hlix import --dry-run`, then repeat with `--yes`.`` — non-interactive import refuses to approve protected data on your behalf.
- `workspace_mismatch` from any `hlix` command — a `--workspace`, `--base-url`, or `HLIX_*` value contradicts the folder's binding. Drop the override; `hlix status` shows which source decided what.
- `{"error":"Project run already in progress","status":"running"}` — a run is already going. Watch that one; a second `start` is refused rather than queued.
- `{"error":"Project not found"}` on `start` — the project ID is wrong, or belongs to another workspace. Check `X-Organization-Id`.
- `{"error":"No active organization"}` — the `X-Organization-Id` header is missing and the API key resolved no default tenant.
- `{"error":"No review evidence: this task has no branch (it was never dispatched through a cycle)"}` — the task exists but never ran. A task created on its own does not execute; see [Tasks](/running/tasks/).
- An empty task list that stays empty — read the project's activity in the dashboard. A run that failed during planning reports there, not on the task list.

## Next steps

[Tasks](/running/tasks/)
  [Reviewing output](/running/review/)
  [Move an existing project to hlix](/guides/quickstart/)
  [Agents & orchestration](/concepts/agents/)