Activate your account — Glueprint Docs

The desktop app works without an account: sessions, terminals, the editor and git all run locally. Connect it to your Glueprint account when you want your plan’s features. Assistants, Channels and boards need Lite or above; live sessions in the web portal need Pro or above. You sign in or create an account in your browser, then choose or create a host for this machine. You do not need to copy a host key from the portal for this flow.

A host is a machine registered to your account. Signing in identifies you; choosing or creating a host registers this installation.

In the desktop, click Local in the status bar at the bottom of the window and choose Connect to Glueprint. The same button appears on any destination that needs an account, such as Channels, and in the account menu at the bottom of the navigation rail. The setup screen says Sign in to Glueprint; Continue locally closes it without connecting.
Choose Sign in to use an existing account, or Create account to start registration in your browser.
Complete the browser flow. For a new account, save your recovery codes and complete email verification. Return to the browser tab opened by Glueprint to continue.
Choose your organization if prompted, then return to the desktop.

If the browser is already signed in, it skips the registration form and asks you to confirm with Continue to Glueprint Desktop. Email verification may require another sign-in. See Recovery codes.

The desktop shows Waiting for browser… while you finish. If it does not return automatically, use the sign-in link fallback.

Step 2: choose or create a host

After sign-in, the desktop shows Connect this Mac (or PC, or machine on Linux) with the account you signed in as. On a new account with no hosts yet, there is nothing to choose: enter a Host name for this machine and click Create host. Otherwise, choose an existing host or create one, as below.

To use an existing host:

Select an eligible host under Available hosts. Hosts awaiting their first installation are labeled Awaiting install; one assigned to you says Created for you.
Click Use this host.

You can claim a pending desktop host assigned to you. An organization owner or admin can also claim a pending desktop host to which they have full access. Being able to see another member’s host does not give a member permission to claim it.

Claiming keeps the existing host entry and its slot. It replaces the host’s previous key, so the original key can no longer activate it.

To create a host as an owner or admin:

Select Create a new host.
Review or edit Host name. The Saved as: preview shows the normalized name.
Click Create host.

Members cannot create hosts. If none are available to you, the desktop says Ask an owner or admin to create a host for you. After an administrator prepares a host assigned to you, click Refresh hosts.

Use Sign out if the displayed account is wrong.

Finish registration

The desktop registers the selected or newly created host and shows its connection progress. On the success screen, You’re signed in, click Open Workspaces to continue with the local setup guide.

Host registration and account sign-in must both finish before this desktop is connected. Until then it keeps working locally. The success screen reports the current relay connection status; registration success does not promise that the relay is already connected.

If your host slots are full

The Host limit reached card replaces the create option. When counts are available, it says You’re using the used count of the purchased count host slots.

Owners and admins see Manage billing on the desktop limit card; it opens the portal’s billing page in their browser. After changing capacity, click Refresh hosts. A billing-role user changes capacity directly from the portal. Members never see the limit card. When no host is available to them, the desktop says Ask an owner or admin to create a host for you.

Pending host entries count against capacity when created. You can still use Use this host to claim an eligible existing entry when all slots are occupied. See Hosts and activation keys.

Continue after restarting the desktop

If you signed in but restarted before choosing a host, the desktop can remember your account while requiring a new secure browser handoff. The same applies when secure registration expires.

The host list stays read-only. Click Continue in browser, finish the browser flow, and wait for the refreshed host list before choosing or creating a host.

If the desktop instead offers Try again for a host it already created or claimed, follow activation recovery first.

If the browser does not return to the app

In the browser, click The app didn’t open?, then click Copy in the Sign-in link panel.
In the desktop, expand Use an authorization code instead.
Paste the complete link into Authorization code or sign-in link.
Click Submit.

For secure host registration, use the full sign-in link, not just the code inside it. The link expires after five minutes and can be used once. Opening the desktop paste form while it is waiting preserves the current sign-in attempt.

The browser also offers Try opening the app again. Open browser again in the desktop starts a new sign-in attempt; use the link from that new attempt.

Rollout note: deploy the hosted auth SPA before a desktop build that emits client=desktop. An older SPA still completes the automatic handoff, but its manual fallback shows a bare code instead of the full sign-in link required for secure no-host registration.

Alternative: use an existing host key

If you already have an unused key for a desktop host:

On the Sign in to Glueprint screen, choose Have a host key? Enter it instead.
Paste the key into One-time host key.
Click Register host.
Complete the following browser sign-in with an account that can access that registered host.
On success, click Open Workspaces.

A host key starts with gp_ followed by 64 hexadecimal characters. Desktop and CLI daemon keys are bound to their host type and cannot be exchanged between the two.

To prepare a Free desktop key in the portal, use the checklist on Home. You can also open Settings > Hosts and find Set up your included host. Click Download; the same button then reads Continue setup and returns you to the Home checklist. Enter Name this Desktop, then click Create one-time host key.

On Pro, Team, or Enterprise, open Settings > Hosts, click Create Host, choose the desktop Host type, enter a Label, and click Create Host to confirm.

Before registration, Back to sign in returns to the Sign in to Glueprint screen. See Hosts and activation keys for complete preparation instructions.

Activate the CLI daemon

The CLI daemon continues to use key-based activation on Pro, Team, and Enterprise. Prepare a CLI daemon host with Create Host under Settings > Hosts and use its key with the daemon’s activate command. Desktop browser registration does not replace this CLI flow. See CLI daemon.

The mobile app uses your Glueprint account and does not ask for a desktop host key. Sign in with your account credentials or your organization’s SSO flow to access your available hosts. See Sign in on mobile.

What happens during activation

Before a host is registered, browser sign-in securely hands the organization’s data encryption key to the desktop for registration.
Choosing or creating a host prepares a host key and registers this machine. Claiming an existing host replaces its previous key.
The desktop stores the host key in a protected local file under the user data directory for ongoing host authentication and encryption setup, and after activation the normal host connection obtains and unwraps the organization’s wrapped encryption key using that host key.
The temporary registration encryption key is kept only in memory and cleared after successful activation. Restarting the app loses that temporary handoff.
You can manage the host from the portal under Settings > Hosts. See Cloud relay and encryption.

If activation fails

You see	What it means	What to do
Host limit reached	Creating another host would exceed capacity. Pending entries already count.	Use Manage billing if available, or ask an owner or admin. An eligible existing host can still be claimed.
Ask an owner or admin to create a host for you	You cannot create hosts and have no eligible host to claim.	Ask an owner or admin to prepare a desktop host assigned to you, then click Refresh hosts.
Continue in browser	The temporary secure registration handoff is unavailable.	Complete a new browser handoff, then wait for the host list to refresh.
The host was created or claimed, but activation did not finish	The server already saved the host operation.	Use Try again when offered. It retries activation of that same host, with one explicit retry available. Do this before restarting or starting another browser sign-in.
Activation retry expired, failed again, or the server may have saved the registration	Another create or claim could duplicate or conflict with an existing operation.	Follow the browser renewal and host-review instructions. Use Refresh hosts to inspect the existing registration before attempting another operation.
Agent host not found or Host is not claimable	The selected host is unavailable or no longer eligible.	Click Refresh hosts and review the current entries.
This server can’t claim pending hosts yet. Create a new host instead.	The server lacks pending-host claiming support.	Create only if you are an owner or admin with capacity; otherwise ask an owner or admin for help.
A network error	A request failed; the message determines whether a host operation may already have succeeded.	Restore connectivity and follow the displayed recovery action. Retry reloads a failed host list; Try again resumes a retained activation. Do not assume a failed request left no host behind.
Invalid API key or Key already activated on the alternative key path	The supplied key is invalid, revoked, or already bound.	Check that you have the correct unused desktop host key. Do not reuse a key from another machine or a CLI daemon.

See Activation failures for recovery details.

Next step

Continue to Your first session.

Step 1: sign in or create an account