First run

The first run takes about a minute of your attention. Halbert starts, hands your browser a one-time link, asks four short questions, scans the machine, and then tells you what it found — in its own voice, which is the first sign that this is not a settings wizard.

This page assumes you have finished Install.

Start it

halbert

That serves on http://127.0.0.1:8000. --port and --host move it, and --find-port walks forward until it finds a free one.

Start the dashboard with halbert, not through the command line

Install explains that the halbert command runs the dashboard and takes no subcommands, while the command line lives at python Halbert/main.py. First run is the place that distinction bites. python Halbert/main.py dashboard does start a server, but it never prints the authentication link below — the page loads and every request behind it comes back 401, with nothing on screen to explain why. Checked on 2026-09-21. Use halbert.

Let your browser in, once

Among the startup lines is one addressed to you:

Open this once to authenticate your browser:
http://127.0.0.1:8000/auth/enter?ticket=1789980517.cn-BL0uXeJXkKW6J.m1-MvCknQ…

Open that URL. It redirects to the dashboard and leaves a session behind that lasts twelve hours; you will not need the link again on that browser until it expires.

Three things about it are worth knowing before they surprise you:

• It is single use. Opening it a second time returns 403. That is correct behaviour, not a failure — the first open already worked.
• It expires in five minutes. A stale link also returns 403. Stop the server and start it again; every start prints a fresh one.
• It is a credential. It is printed instead of the token itself so that a terminal scrollback does not become a permanent key, but treat the line as a password while it is live.

The token behind it lives at ~/.local/state/halbert/api-token, created on first start with mode 0600 inside a 0700 directory. Set HALBERT_API_TOKEN instead and Halbert uses that and prints no link at all, which is how a supervised service hands the credential to its own process.

What it asks

Open the link and the machine introduces itself before asking anything:

Welcome to Halbert Let me introduce myself. This will only take a moment.

It names the four things it is about to look at — hardware, storage, network, security — and says the scan runs entirely on your machine. There is also a Restore from a backup instead link, for a machine you have set up before.

The next screen asks four things, and only the first is unavoidable typing:

What’s your name?	What it will call you.
What should I call this computer?	Prefilled with the hostname. The hint updates live as you type: This is how the computer refers to itself (“I am Atlas”).
What is this computer for?	Workstation, Server, or Home Hub. Pick as many as fit.
Anything else I should know about this machine?	Optional free text.

The third question is already answered when you arrive, because the machine probed itself while the welcome screen was up and shows its reasoning underneath the choices:

I found a display and a graphical session, editors installed (vim, nano, atom), development tools (cargo, cmake, docker, git). I look like a workstation.

You are correcting a guess rather than filling in a form, and the guess is auditable. The last question is the one worth answering even though it is optional — whatever you write becomes the machine’s stated purpose and is part of how it reads its own situation afterwards.

The name is not cosmetic

It is what the machine calls itself in every answer it gives you from here on, so pick the name you want to hear. The raw hostname is offered as a default, not as a recommendation.

The scan

Scan System & Complete Setup runs the full profiler. The screen says 30 to 60 seconds; on the 20-core Mac Studio below it finished well inside that both times it was measured. It reports back in the first person:

=== I AM ATLAS ===
I run macOS 26.5.1 with kernel 25.5.0.
I serve as a workstation.
I use homebrew for package management.
I have been running for 11 days, 20:01.

--- My Hardware ---
I have a Apple M1 Ultra with 20 cores.
I have 128.0 GB of RAM (47.6 GB currently available).
I have a Apple M1 Ultra GPU.

--- My Storage ---
I have 7 storage devices with 111 filesystems.
I use APFS for advanced storage management.

That summary is the machine’s self-knowledge, not a report about it, and the switch in grammar is deliberate — see The computer speaks for itself.

Finish Setup closes the dialog onto the working interface.

What it wrote

Setup itself writes four things:

Path	What it holds
<config>/onboarding_complete	Two lines: the computer’s name, then yours. A marker that setup ran.
<config>/preferences.yml	ai_name, user_name, roles.
<config>/being.yml	The machine’s own settings, with your free-text answer as purpose.
<scan>/system_profile.json	The scan. Around 50 KB on the machine above.

<config> is the configuration directory from the Install table — ~/.config/halbert on Linux, ~/Library/Application Support/Halbert on macOS.

The scan lands in the data directory that table names, ~/.local/share/halbert/system_profile.json, on Linux and macOS alike. Before 2026-09-23 a Mac kept it in ~/Library/Application Support/Halbert/Data instead. That copy is no longer read, so on an older install the wizard comes back once unless the file is copied across.

Setup marks itself complete only when the marker and the profile are both present, so deleting either one brings the wizard back.

What is not set up yet

A model. Setup asks nothing about one, and does not need to: the machine can describe itself without it. The first thing you say will fail plainly until a connection exists — Your first conversation shows exactly how it fails, and Connect a local model is the fix.

The interface you land on

Three panels. On the left a rail of the machine’s own pages — Services, Storage, Backups, Terminal, Containers, GPU, Apps, Network, Sharing, Development, MCP, Findings, Approvals, Settings — headed by the name you chose and the roles you picked. In the middle the dashboard, with what it has found so far. On the right one continuous conversation with the machine. Cmd+D hides the dashboard panel and Cmd+J the conversation, so either one can have the width.

Next

Your first conversation.