Platform architecture
hlix is a hosted platform that runs AI agents on your software projects from request to reviewed change. A project manager decides what to do, bounded workflows carry out each piece of work, every agent works in an isolated sandbox of its own, and finished work collects on a review branch. Nothing reaches your default branch until you merge it.
This page describes the shape of the system in the terms you work with. It does not cover how each part is built.
When this matters to you
Section titled “When this matters to you”- You are explaining to a client where their code lives and what can touch it.
- You want to know what keeps running when you close the browser.
- A cycle is taking longer than you expected and you want to know which part of the system decides its next step.
- You are choosing between the dashboard, the CLI and the API.
The four parts
Section titled “The four parts”| Part | What it is | What it holds |
|---|---|---|
| The dashboard | The web app at app.hlix.ai | Nothing of its own. It uses the same API as the CLI and SDKs and shows work as it happens. |
| hlix’s control plane | The API, the project manager, the workflows, model access and integrations | Decisions. It plans the work and judges the results. It never runs your code. |
| Your Workspace data | Projects, cycles, tasks, conversations, memory, encrypted secrets and the audit log | Isolated per Workspace and stored in the EU. |
| Coding Workspaces | One per project: a saved environment, and a short-lived sandbox started from it for every job | A working copy of your code at an exact commit, its dependencies, and credentials scoped to that one job. |
The dashboard, the CLI and the SDKs use the same API and the same access checks, so they never disagree about what you can see or do. The dashboard adds visual tools such as line-by-line diff review.
How work flows
Section titled “How work flows”The project manager decides
Section titled “The project manager decides”Every project has one project manager: an agent that keeps the project’s plan and decides what happens next. It wakes whenever something happens to the project — a request arrives from chat, the board, an integration or the API, a cycle finishes, or a review keeps finding problems.
For each new request it decides whether the request repeats work the project already has, builds on it, or is new, and how urgent and risky it is. It then plans the work, chooses which coder runs each task, and decides the next step when results come back. It never edits code itself.
A project does not fail. A failed step becomes context for the next decision, and the project manager tries a different approach. A project stops only when a person stops it, and it pauses when it reaches its spending cap until you raise the cap.
Workflows run each piece of work
Section titled “Workflows run each piece of work”The project manager starts work as cycles: bounded workflows that each deliver one coherent change. See Cycle lifecycle.
plan ──▶ build ──▶ review ──▶ merge ──▶ preview ▲ │ └──────────┘ not approved: same task, same branch, with comments- Plan. A planning agent reads the repository and breaks the cycle into tasks, with the files each task is expected to touch and the order they depend on.
- Build. Each ready task runs in its own sandbox. Its coder works on the task’s own branch and pushes the result.
- Review. A reviewer agent checks the change at the exact commit under review, alongside the project’s own checks and its end-to-end tests. Work that is not approved goes back to the same task with the review comments.
- Merge. Approved work merges into the project’s preview branch, and only a checked commit moves that branch. A conflict goes back to a coder to resolve; work is never discarded.
- Preview. Each merge builds a private preview of the project that your team can open.
Every agent works in its own sandbox
Section titled “Every agent works in its own sandbox”Every agent that reads or changes code — the coder, the planner, the reviewer — runs in an isolated sandbox started for that one job and deleted when the job ends. Two tasks never share a checkout, so parallel work cannot overwrite itself.
You choose the coder per task, project or Workspace: Hlix Code is the default, and Claude Code, Codex, Cursor Agent and other coding agents run through the same pipeline. See Connect your agents.
You approve the final merge
Section titled “You approve the final merge”hlix opens a single pull request from the preview branch into your default branch, and hlix never merges it. Reviewing and merging that pull request is the one decision that stays with you. Everything before it runs without waiting for a person.
The branch is the record
Section titled “The branch is the record”A task is done when its branch carries the change, the project’s checks pass on that commit, and the review approved that same commit. If a sandbox stops mid-task, the task continues from what is already on its branch.
Isolation and security
Section titled “Isolation and security”- Agent code never runs on hlix’s servers. It runs only in short-lived, isolated sandboxes.
- Your Workspaces are isolated from each other. Every request and every query is scoped to one Workspace, and a client you invite sees only the project you invited them to. See Tenancy & isolation.
- Secrets stay out of your code. Secrets are encrypted at rest, delivered to a sandbox only for the job that needs them, and excluded from every commit. See Secrets & protected files.
- Models are reached through hlix. Agents in a sandbox call models through hlix on a short-lived key issued for that job, so your provider keys never enter a sandbox. Every call is metered to the task that made it and counts toward your spending cap.
- Every action is recorded. The audit log records who did what, to what and when, and it cannot be edited. See Audit log.
What you see
Section titled “What you see”- Live progress on the project page: the conversation with the project manager, each cycle’s stage, and each task’s coder as it works.
- Review evidence for every task: the diff, the check results and the review comments.
- A private preview of the project after each merge.
- Usage and cost per task, cycle and project, against your Workspace’s limits.
What runs without you
Section titled “What runs without you”Closing the dashboard does not stop dispatched work. Planning, coding, verification, review and preview builds continue on hlix. Regular maintenance also runs on its own: projects with outstanding work that have gone quiet are woken, and sandboxes and saved environments for deleted projects are removed. See Reliability & maintenance.
If something looks stuck
Section titled “If something looks stuck”- A project has drafts and nothing is running. Check the project’s activity for a spending-cap pause or an access problem, such as a disconnected repository. A quiet project with outstanding work is woken again within a few minutes.
- A cycle stays in
review. Open its checks and review comments. Review is carried out by agents, not a queue waiting for a person. - A live update did not appear. Reload the task. Its history is stored and shown again in full.
Where to go next
Section titled “Where to go next”| If you want to… | Read |
|---|---|
| See who does the work inside a project | Agents & orchestration |
| Follow a cycle from start to finish | Cycle lifecycle |
| Understand the sandbox layer | The Coding Workspace |
| Know the hostnames and API prefix | Environments & endpoints |