Your account & agents

A small home for your connections

The owner interface at /account manages your account and agent access. CRM records are still managed through MCP. Your login password controls the browser account; each agent has a separate bearer token with view-only or view-and-edit access. Agent tokens cannot sign in to the owner interface.

Guided installation

The person deploying Orbit chooses its owner in a trusted server terminal. Public visitors cannot create or claim an account, even before installation is complete. No email service or private setup code is required.

After configuring the database, APP_KEY and APP_URL, installing dependencies and running migrations, run this once in the application's directory with PHP 8.5:

php artisan orbit:install

The installer walks through three short steps:

1. Your workspace: choose a name and timezone for a fresh installation. An existing workspace is reused without changing its data or agents.
2. Your owner account: enter your name, login email and password twice. Password entry is hidden. The email is simply your login identifier; nothing is sent to it.
3. Ready to begin: review the workspace and owner details, confirm, then follow the sign-in URL.

Use a password of at least 12 characters, up to 72 bytes. Passwords are hashed and are never displayed in the review or passed as command arguments. Setup requires an interactive terminal and refuses --no-interaction. Do not place it in recurring deployment scripts or a command runner that records interactive input.

On a new deployment, complete this trusted installation step before handing over the public URL. If a workspace already has an owner, rerunning the installer leaves it unchanged and points you to sign-in or password recovery. If there are multiple workspaces, select the intended one with php artisan orbit:install --workspace=WORKSPACE_UUID.

Cancelling or failing validation leaves the database unchanged. Workspace and owner creation commit together. Concurrent installers cannot overwrite an owner or silently claim a workspace another installer just created.

After signing in, an empty workspace displays a three-step getting-started checklist: workspace ready, connect your agent, and make the first request. A workspace supports one owner in this version; additional members and workspace switching are not available.

Upgrading from setup codes

Existing owner accounts, records and agent tokens continue to work. The old /setup address redirects to sign-in and no longer accepts account creation. Previously issued codes cannot create an owner. The retired orbit:owner-invite command points administrators to orbit:install; successful installation clears the selected workspace's pending invitation. No new migration is required beyond the existing owner-access migration.

Sign in and connect an agent

Use Your workspace on the welcome page or visit /login. From the workspace overview:

1. Choose Connect an agent and give it a recognisable name.
2. Choose View only (reader, selected by default) or View and edit (contributor).
3. Confirm your account password and create the token.
4. Copy the token immediately. Save it in your password manager and the client's secret settings.
5. Follow the connection steps for Hermes or another remote HTTP MCP client.

The token is shown on the first connection-page response only. Refreshing or leaving the page hides it. For that redirect, the secret is temporarily encrypted in the session and can be displayed for at most five minutes; authentication stores only its SHA-256 hash. Responses are not cacheable. Tokens never appear in the generated configuration: it references ORBIT_MCP_TOKEN instead.

The connection page uses this installation's configured APP_URL for the MCP endpoint. Administrators must set it to the correct HTTPS origin. Hermes configuration enables every tool allowed by the selected role; use the explicit allowlist in the Hermes guide if you want a narrower client tool list.

Check the connection

For Hermes, run hermes mcp test orbit on its host, then start a new session or use /reload-mcp. Ask it to call workspace_context and confirm the workspace and role. Copy a freshly created token before selecting Check connection, because that refreshes the page.

The overview and connection page show the last accepted authenticated MCP request for the current token. This is historical evidence of access, not a continuous online indicator or proof that a CRM operation completed. Older tokens begin with no timestamp until their next accepted request. Replacing a token clears its connection timestamp.

Complete the create, disconnect, reconnect and retrieve exercise in the Hermes guide to verify the full live journey.

Replace or revoke access

Open an agent from your overview, then expand Replace token or Revoke access. Both require your account password.

Replacing a token keeps the same agent identity and records. The old token stops authenticating immediately; copy the replacement and update the client's secret settings. Revoking an agent permanently disables that identity, while preserving records and attribution. To reconnect after revocation, create a new agent. Requests already in flight may finish, and existing task claims retain their normal expiry.

Creation, replacement and revocation record the owner ID in the audit summary. Owners can only manage agents in their own workspace. The CLI commands remain available to server administrators.

Password changes and recovery

Expand Change password under your account details. Enter your current password and the new password twice. Other signed-in sessions will be rejected on their next account request; agent tokens are unaffected.

If you cannot sign in, a server administrator can recover the account over a secure SSH terminal:

php artisan orbit:owner-password [email protected]

This command intentionally requires an interactive terminal and prompts for the new password twice without displaying it. Do not pass passwords as command arguments. Email-based recovery, email verification, MFA and OAuth are not implemented in this version. The email is a login identifier, not a verified address.

Deployment requirements

Keep ORBIT_REQUIRE_HTTPS=true in production. Set SESSION_SECURE_COOKIE=true and use a private server-side session store, such as the default file driver. Preserve APP_KEY and persistent session storage between releases. Configure only known trusted proxies if TLS terminates upstream; never disable HTTPS checks to work around proxy configuration.

Apply the owner-access migration before using these pages. It adds nullable ownership and last-request fields, plus hashed setup invitations, without modifying existing agent credentials. Rolling it back removes ownership and invitation data; use a reviewed forward fix for production.