Setup: sign-ins, regions, and remote access
This chapter explains the separate sign-ins for HB Code and each agent, when the agent sign-in comes, and where limits and usage show. It also explains optional API keys, one region per account, the remote-access switch, and the connected preview before HB Code Pro.
Checked against the source on 5 October 2026
On this page
Sign-ins and optional keys
- HB Code accountAuth0 · PKCE
Each device signs in by itself, to the same account in the same region, and the desktop needs it only for remote access. If a phone can’t find the desktop, check this sign-in and the region.
- ChatGPT accountaccount/login/start
The Codex child signs in through your browser and runs every turn on it, including turns sent from a phone. If the agent won’t start a turn, check this sign-in and its usage limits.
- Claude accountclaude auth login --claudeai
Claude runs its own browser sign-in and keeps the credential, and HB Code never reads it. You can add more accounts, each with its own sign-in. If a Claude turn won’t start, check this sign-in and its usage limits.
- Personal API keyopenai_api_key · gemini_api_key
Kept in the desktop keychain for desktop dictation and, with a Gemini key, the speech and video tools. Phone dictation doesn’t use it, so check it only when desktop dictation fails.
Codex sessions run on a ChatGPT sign-in. The desktop gets the sign-in address from the Codex child and opens it in your browser. The Codex child keeps the credential in the home folder of its profile. Claude sessions run on a Claude sign-in. The desktop runs Claude’s own command claude auth login --claudeai, and Claude opens the browser and keeps the credential. HB Code reads neither token. The default Claude account is the Claude sign-in that already exists on the computer.
| Claude sign-in step | Rule |
|---|---|
| Sign in | One sign-in runs at a time. A second start fails with “Claude sign-in is already running.” The desktop ends the command after 600 seconds. |
| Cancel | The desktop stops the claude process. The account stays signed out. |
| Status and sign out | claude auth status --json and claude auth logout each have a limit of 15 seconds. |
| Remove an account | The desktop deletes the folder of an added account. If that account was active, the default account becomes active. The default account cannot be removed. |
Each added Claude account is a folder under claude/accounts in the HB Code application data, named with a UUID. Five entries stay private in that folder: .claude.json, .claude.json.lock, .credentials.json, backups, and statsig. Every other entry of the main Claude folder is a link, and the projects folder with the transcripts is always shared. The main folder is ~/.claude, or the folder in CLAUDE_CONFIG_DIR when that variable is set. So every account reads the same sessions and the same settings, and a switch changes only which account pays for the next run. A run keeps the account that was active when it started.
Agent sign-in at the first session
The desktop opens without an agent sign-in. The sign-in comes when you create a new session. If the chosen agent is signed out, a sign-in dialog for that agent opens, and the session starts after the sign-in. If you close the dialog, no session is created. A continued conversation opens without a sign-in.
| Agent state | Result |
|---|---|
| The agent is signed in | The session starts at once. |
| Codex is signed out | The dialog asks for the Chat |
| Claude is signed out | The dialog asks for the Claude sign-in. The desktop keeps a confirmed Claude sign-in until a Claude account changes on this desktop. |
The preselected agent is the value plantocode:new-session-agent:v1 in the local storage of the desktop window. Without a stored value the choice is Codex. An HB Code account is not part of this sign-in.
Limits, usage, and switching accounts
On the desktop, Settings → Agents shows both agents side by side. Each agent has its account rows, the limit meters of the active account, a usage detail view, and charts of usage over time. Claude reports a rolling five-hour window and weekly windows. Codex reports a primary and a secondary window. The desktop saves each fresh reading of the all-model windows and keeps it for 35 days.
| Task from a phone | Method |
|---|---|
| List the Codex profiles | system. |
| List the Claude accounts | system. |
| Switch the Codex profile | system. |
| Switch the Claude account | system. |
| Read the Codex limits | system. |
| Read usage over time | system. |
The desktop stores the active Codex profile in the setting agent.chat.codex_profile_id and the active Claude account in agent.chat.claude_account_id. Without a Claude value the default account is active.
A phone can read and switch. It cannot add an account, sign in, sign out, or remove an account. Those actions exist only on the desktop.
One region per account
An HB Code account lives in one of two regions, United States or European Union, each with its own API host, relay process, PostgreSQL, and Redis. Device discovery is scoped to one account in one region, so both devices have to select the same one, and changing the region on a device signs it out first. The phones default to the United States when nothing is stored.
Remote access and the device list
- On the desktop, open Settings → Connections.
- In the Mobile Connection card, set Allow Remote Access to on.
- If the desktop asks for a server location, select the region of your HB Code account.
- If the desktop asks you to sign in, sign in with your HB Code account in the browser.
- Record the server location that the card shows.
- On the phone, select the same region.
- Sign in with the same HB Code account.
- Select your desktop in the device list.
- Select a project and a session.
- Device rowPOST /api/devices/register
Created with X-Client-Type: desktop the first time remote access is on, in the region the desktop chose. Sleep and the switch leave it in place, so the desktop stays listed.
- Desktop socket/ws/device-link
The desktop dials out to the relay, and phones never connect to the computer directly. A silent socket is dropped after about 3 minutes and counts as reconnecting for 90 s, while turning the switch off closes it at once.
- Pingsystem.ping
The phone opens its own socket for this desktop and pings through the relay. Only an answer lets it load projects, sessions, and the timeline.
The WebSocket register’s device UUID must match the row’s owner and role. The switch needs a chosen server location and an HB Code sign-in. That sign-in exists only for remote access, and every other desktop feature works without an account. A degraded saved session pauses the mobile connection.
The connected preview and HB Code Pro
The first phone on an account to reach a desktop starts a 10-day connected preview for the whole account. After that each phone needs HB Code Pro, bought through the App Store or Google Play for its platform. The subscription covers the phone only. Coding on the desktop needs nothing beyond the agent’s own sign-in, and an iPhone subscription does not unlock Android or the other way round.
- Preview recordaccount_workspace_previews
Written the first time any phone on the account gets an answer from a desktop, with started_at from the database clock and expires_at 10 days later. Later phones get the same record, and the server can’t update or delete it.
- Identity keysHMAC-SHA256
The record is stored under keyed hashes of the Auth0 subject and the verified email, linked to each other. A lookup follows the links and takes the earliest start.
- HB Code ProStoreKit · Google Play
Bought per platform. The iPhone checks StoreKit on the device, and Android sends the purchase to the regional server to verify. Neither unlocks the other.
The server stores the preview under keyed hashes of the Auth0 subject and the verified email and counts the 10 days from database time.