Authentication

Authentication is optional

You can build, rebuild, start, restart, stop, and manage applications without logging in - everything works locally. Logging in links your local Phelix server to your account at phelix.anophel.com so that app data, resource metrics, and events are pushed to your dashboard.

Log in

# Interactive loginphelix auth login # Non-interactive loginphelix auth login --username <user> --apiKey <key>

Login enables dashboard sync for watched apps, including apps created while offline. New apps default to watching disabled: enable an app with phelix watch <app> or watching: enablein its configuration. Events, resource metrics, and logs follow this opt-in; metrics and logs also require the monitor daemon. See Per-app watching.

Agent-scoped sessions

By default, phelix auth login issues a full-scope session, valid for the dashboard and every monitoring channel. On a server you only monitor, that is more power than the daemon needs: a compromised server would expose a token that can touch your whole account. Use the agent-scoped variant when provisioning servers (install scripts, systemd setup):

phelix auth login --username <user> --apiKey <key> --scope agent

This requests a monitoring-only token, stored separately at ~/.phelix/agent-session.json so it never displaces your interactive session. The token is accepted by the monitoring gRPC channel and nothing else: dashboards, account settings, and session management all reject it. If the server is ever compromised, the stolen token cannot be used to take over your account; revoke it from any other machine with phelix auth logout (which logs out both sessions).

Both sessions can coexist: a typical server runs --scope agent for the daemon, while you use a normal full-scope login for interactive CLI commands there. phelix auth status shows both, including each token's scope.

Session management

phelix auth status     # show current session + expiryphelix auth logout     # invalidate and remove the session

The local session is stored at ~/.phelix/session.json and is validated regularly. Authentication errors (for example, an expired session during phelix auth status) prompt you to run phelix auth login again. Build and run commands never require a session.

The backend throttles failed logins (HTTP 429 with a Retry-After window) and abusive retry patterns on the monitoring channel. The CLI honors both: a throttled login tells you when to retry instead of failing generically, and the monitor daemon backs off for the announced window. If you see a too many failed attempts message, wait for the stated window; retrying earlier only extends it.

Working offline

Want to use the CLI entirely offline, or do not need the dashboard? Skip auth login. During build/rebuild, Phelix notes that no metrics or events will be sent to the dashboard until you authenticate. All communication with the Phelix service is encrypted; when not logged in, nothing is sent at all.

Automation