On this page
Deployment and dashboard access
Choose the operating boundary first
For ordinary desktop use, keep the dashboard on the same machine. Blank host configuration normalizes to 127.0.0.1; the macOS/Linux desktop launcher opens a loopback URL. Loopback limits who can reach that listener; it does not make model requests local or replace provider authorization. Understand the endpoint, credentials and potential costs before Birth or messaging. Preparation covers those decisions. (D1; D2)
Before administrative action, identify the exact release/build (aii -version), OS, intended existing identity slot and its effective address. Obtain the matching released application/binary, an authorized OS account, durable storage and a supported user-session/service environment. This page does not establish hardware minima, artifact integrity or a clean-install pass. Do not create another identity to repair an uncertain existing one. (D2; D3; D4)
Launch and lifetime are separate
Opening the desktop app can create an empty slot using aii init, register/start its background process and wait for the dashboard. This is not Birth. Closing a browser is not a documented service stop. The inspected service mechanisms differ: (D2; D5; D6; D7)
| Platform | Source-defined mechanism | Operational consequence |
|---|---|---|
| macOS | Per-user LaunchAgent, id.aiii.aii-os.<slot> |
Registration bootstraps it in the GUI domain; starts again at login. |
| Linux | User systemd unit aii-os@<slot>.service |
Registration enables/starts it and attempts lingering; failure can mean stopping at logout. Requires a functioning user manager. |
| Windows | Current-user Run entry, AII OS <slot>, detached launcher |
Starts again at sign-in; not an inspected Windows system-service deployment. |
CLI source supports aii -dir <identity-directory> (foreground runtime), aii register <slot>, aii stop <slot> and aii unregister <slot>. These are consequential alternatives, not commands to run together. Do not start a second runtime against an already-running slot or guess its name. No stop/retention or cross-platform installation replay was performed here. Do not substitute deletion or uninstall for diagnosis. (D2; D3; D4; D5; D6; D7)
Exact access controls
| Control | Meaning and caution |
|---|---|
dashboard.host, dashboard.port |
Listener address and port; Settings → Dashboard exposes HOST and PORT. Slots use base port 8180 plus slot number, but configuration can differ. Confirm the effective address, not a guessed port. |
dashboard.tls |
Settings → Dashboard → HTTPS. Application normalization forces it on for non-loopback hosts. The listener's lower-level plain-HTTP warning is not permission to deploy the application remotely without TLS. |
dashboard.require_token, dashboard.access_token |
Non-loopback startup forces token authentication; missing required tokens are minted and persisted. Loopback access can be protected with Ask for an access token. |
dashboard.origin |
Advertised origin, validated as HTTP(S) scheme/host/optional port with no credentials, query or fragment (only empty/root path). Not a CORS wildcard or authorization grant. |
Settings HOST, PORT and HTTPS changes apply on the next restart, not merely on Save or configuration reload. After an authorized restart, confirm the intended listener, especially when reducing network exposure; saving a loopback address does not withdraw an already-running network listener. Token actions below have different, live semantics. Settings save notice.
These fields are source definitions, not a remote-exposure configuration example. The port utility's syntax is aii dashboard-port -dir <identity-directory> <port>; it changes configuration for the next start, not the current listener. (D4; D8; D10; D11; D12; D13; D18)
An authorized operator can use aii dashboard-token -dir <identity-directory> to print the configured credential. Treat terminal output as a secret: no screenshots, shared logs, conversation or token-bearing URLs. Settings provides Rotate access token; the CLI variant adds -rotate, persists a replacement, and requires configuration reload before the running identity applies it. Settings rotation installs the new token live and refreshes the initiating browser's access cookie: this browser stays signed in, while other browsers/devices must authenticate again. CLI rotation applies on configuration reload and has no initiating-browser cookie refresh. A retained Settings session alone does not mean rotation failed. Live policy installation; Cookie refresh. Prefer the supported control over hand-editing secrets. Never include a real token in documentation evidence. (D9; D18)
Remote access is a separate deployment decision
Changing HOST to a LAN address or wildcard expands reach. A wildcard bind makes the Host gate match the port only. The normal application requires TLS and a token off loopback, but those checks do not establish audited security or an approved internet-facing deployment. TLS startup can mint a local CA and leaf certificate; that is not automatic public certificate trust. Do not bypass certificate warnings or distribute private CA/leaf keys. (D1; D11; D13; D17)
Requests pass a Host gate; WebSocket admission also requires a nonempty Origin with the actual connection scheme and an allowed host, plus an access cookie when required. Sensitive paths additionally distinguish TLS or a loopback peer as a private connection. These are distinct checks, not interchangeable credentials. Merely loading a page is not an authenticated integration test. (D14; D15; D16)
For occasional remote viewing, retaining a loopback listener with an operator-managed SSH tunnel is an option to evaluate, not an AII OS command or tested procedure here. A tunnel still must preserve the expected browser Host, port, scheme and cookies; arbitrary port remapping can fail admission. It also makes the connection appear local to the server. No tunnel recipe is accepted by this evidence. Public-name/relay features, firewall policy, certificates, reverse proxies and unattended server hardening need their own authorized review; no guessed proxy configuration is supplied.
If access fails, preserve only sanitized build/platform/time, intended address and exact error. Determine whether failure is listener/service startup, certificate trust, Host/Origin rejection or token admission before retrying. Do not disable gates to make a connection work. Setup triage distinguishes later creation/delivery failures.