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.

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 and authenticated
A workspace ID and an API key from 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.

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

The five steps

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

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

Expected result:

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 lists each blocker and its fix.

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:

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

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.
- Dashboard
- API
In the dashboard: open 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:
Terminal window
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:
{"started":true}
started: true means the run was handed to the engine, not that it has finished. The run proceeds asynchronously from here.
Find the task the orchestrator created. Planning takes a little time; the first task usually appears within a minute or two.
Terminal window
```
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:
```
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.
Terminal window
```
export TASK_ID='b4a1f0d2-3c77-4e1a-9a2b-1d5e6f7c8a90'
```
Watch the agent work. hlix tasks watch consumes the server’s status stream and exits when the task reaches a terminal status.
Terminal window
```
hlix tasks watch "$TASK_ID"
```
Expected result — one line per status change, ending at a terminal status:
```
queued
building
testing
reviewing
done
```
Add --json to get one envelope per line (JSONL) instead, which is what automation should read.

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

hlix tasks review "$TASK_ID"

Expected result — the evidence document, abridged:

{
  "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 explains how to comment on a line and send it back.

What just happened

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, 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.
This folder is already bound to an Hlix project. Use `hlix push`. — the folder was imported before. Use hlix push 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.
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

TasksHow tasks are created, why execution comes from a cycle, and every status they pass through.

Reviewing outputVerified evidence, line-level comments, and sending a task back for a revision.

Move an existing project to hlixThe import path in full: history policy, protected files, and blockers.

Agents & orchestrationThe orchestrator and the six worker roles that delivered this task.