Get Started

Dashboard

The local web console: how to serve it, and what each page does.

ant ui serves a local web console over the same ant.yaml files and client config the CLI uses. Every edit it makes writes the file with comments preserved, so the two stay on the same page, a domain you add in the dashboard is a domains: entry the CLI sees, and vice versa.

Run it

ant ui                      # serve in the foreground until interrupted
ant ui run                  # the same, as an explicit subcommand
ant ui passwd               # set a password before leaving loopback (--clear, --password-stdin)

The dashboard is local-only by design: one dashboard per operator, on their own laptop, reading their own ~/.ant and ant.yaml files. It is not meant to be hosted on a server or shared between users. The machines it manages are reached through your account and each machine's colony roles, so your dashboard shows exactly the machines your account can access and nothing else.

As a background service (a systemd user unit on Linux, a launchd agent on macOS):

ant ui install              # install, enable, and start the service (--host, --port, --force)
ant ui status               # installed / enabled / running? (--json)
ant ui logs -f              # follow its logs (--lines N)
ant ui stop | start | restart
ant ui recreate             # reinstall (picks up a new host/port) and restart
ant ui uninstall            # stop and remove it

It binds where ui.host / ui.port in ~/.ant/config.json say, loopback by default, and that is the supported mode. Binding to a non-loopback address (for example, to open your own dashboard from another device on your LAN) is refused unless a password is set (ant ui passwd), and is then wrapped in HTTP Basic auth behind a signed session cookie; put TLS in front. That is a safety net for your own access, not a multi-user hosting mode. See Security.

Pages

Page	What it shows
Dashboard	A fleet overview: project and machine counts, recent activity, and machine metrics.
Projects	Every discovered project. A project page has tabs: General, Environments, Domains, Deployments, Monitoring, Volumes, Advanced.
Groups	A group page with tabs: Projects, Environments (shared env and secrets), Network & domains (the shared docker network and the group's base domains).
Deployments	The deploy history shared with `ant trail history`, filterable by project and machine.
Activity	The operations log across the fleet.
Nest	The machines ant knows about. A machine page has tabs: General (host facts, the opt-in machine-wide network, and the colony users on that machine, roles, linked system accounts, and ownership election), Docker (containers with a log tail, volumes, and a prune dialog), Tools (inspect and install Caddy, builders, and their versions; per-tool detail), Audit (the tamper-evident action log), and Setup (the NodeID, bootstrap plan, re-provision, and state backup/restore) on a remote machine. A remote machine also offers Run image (`ant trail deploy --image`).
Logs	Live container and build logs.
Settings	The dashboard service, your account, notifications, project directories, the config file, and this machine.

Environments

The environment picker on a project page scopes the whole page to the selected deployment: the run-state badge, the run/build/machine badges, the image the General tab reports, and the Monitoring tab (containers, logs, and the disk usage of that environment's machine). A server:/machine: deployment reads its containers from that machine over iroh, so a remote environment never borrows the local one's "running" state. Live log streaming is local-only; for a remote environment the container picker fetches the last 500 lines instead.

Domains

Adding a domain on a project's Domains tab mirrors ant nest edit domain add. Pick a subdomain (plus a path, or a group base domain) and the port it routes to; the base defaults to localhost for a local project, or to the group's base domains when the project belongs to a group. Domains are opt-in: ant never adds a hostname for you.

CLI vs. dashboard

The dashboard is a convenience over the CLI, not a separate control plane. Create your Ant account and restore it from a bundle on Settings → Ant account. Lifecycle work is on both surfaces: deploy, build, stop, restart, rollback, destroy, prune, run a prebuilt image, container logs, domains, the machine's audit log, and its state backup. A few actions are still CLI-only:

Swarm (ant nest swarm …) has no dashboard surface yet.
Teardown and identity: ant nest machines decommission and ant nest identity generate.
Account portability: ant colony export, colony join, and colony recover (signup, login, profile, and logout are in Settings).
Installing a tool from the Tools tab works, but --dry-run and the generic ant nest tools allow-ports (for tools other than Caddy) stay in the CLI, since they need host package managers and sudo.
The dashboard service itself is managed with ant ui (install, passwd, logs, recreate, uninstall).

For everything else, either surface works, and both write the same files.

Tunnels are on both surfaces: ant nest tunnel, or the Tunnel action on a running container's row on a remote machine's page. Either way the forwarding listener is created on the host running it, so the local URL only resolves from that machine; the dashboard deliberately does not expose the port to other devices. See Tunnels.

Project structure

ant.yaml, the state under ~/.ant, and what Ant writes where.

Architecture

The pillars, the process model, and what runs where.