Glob
Log in
Menu
Skip to the guide

Account and sync

Run a data relay

Let an external tool use a scoped Data API key against your Linux CLI store, and keep that store in sync.

glob relay-node lets this Linux device answer Data API requests from an external tool using a scoped key. It reads or changes the selected CLI store within that key's access. Keep the command running while you want the device to answer requests.

The macOS CLI does not include this command. On Linux, network access requires a build with HTTPS support; check installation.

Prepare this device

Use the CLI to set your server and sign in. Create the Data API key on this device so the CLI saves its associated agent identity. For example:

glob keys create "Research helper" --agent-nickname Research --reach account

Save the displayed token for the external tool. See API keys to choose the reach, permissions, expiry, and store.

Make the sync passphrase available through GLOB_SYNC_PASSPHRASE or --passphrase-stdin. The relay needs both your signed-in account session and the distinct Data API key. The API key does not replace the account session or sync passphrase.

Run a sync so this store has the records you expect, then start the relay:

glob sync now
glob relay-node --label "My Linux device"

The relay uses the most recently saved local key when you omit explicit key inputs. To select a particular stored key:

glob relay-node --key-id <key-uuid> --label "Research device"

If you created the key in another store directory, pass the same --store <directory> here.

Every relay option

Option Meaning
--store <directory> Select the CLI store and its saved relay identity. Defaults to GLOB_STORE_DIR, then ~/.glob/store.
--server <url> Override the server for this run. Otherwise GLOB_SERVER_URL takes priority over the saved server.
--api-key <token> Supply a raw Data API key. Otherwise use GLOB_RELAY_API_KEY, then a stored local key. Prefer the stored form so you do not need to type a secret in the command line.
--key-id <uuid> Select the stored key when no raw key is supplied. It does not override --api-key or the environment key.
--scope-json '<object>' Select the relay's local maximum scope. Otherwise use GLOB_RELAY_SCOPE_JSON, then the stored scope for the selected key.
--device-id <uuid> Explicit relay-device identity for this run. Must be a UUID.
--label <text> A name for this relay device. Defaults to this machine's hostname.
--passphrase-stdin Read one non-empty sync-passphrase line from stdin if GLOB_SYNC_PASSPHRASE is not set to a non-empty value.
--once Exit after handling one request, including a request answered with an error.
--poll-max <count> Stop after this positive number of attempts to wait for a request. Default: keep running.

There is no --json option. Use glob relay-node --help for command help.

The scope JSON uses the same version 2 format as key creation. A narrower local scope can deny work that the key otherwise permits. A wider local scope does not grant extra permissions to the key.

An explicitly supplied token still needs a matching saved agent identity on this device. Copying only a token into --api-key is not enough to set up an unknown relay key. Create the key through this CLI and use that saved entry.

Keep the records current

The relay serves this device's selected store. It does not run a full sync loop for you. Run glob sync watch separately with the same store and sync passphrase, or run glob sync now when you need to update it. The same applies after an external tool writes a record: sync transfers that change to your other devices.

The available Data API actions on this relay are reading, querying, creating, and updating records, subject to the key's scope. It does not expose hosted AI through a Data API operation. See the account API key guide for broader external-tool access.

Output and stopping

Progress goes to stderr and begins relay-node:. You will see registered when startup succeeds and a handling … request … line for each request. The command continues waiting after it responds.

Press Ctrl+C to request a stop. It can finish the work already in progress before leaving.

For a bounded run:

glob relay-node --once --poll-max 3

After one handled request, --once prints a plain JSON object on stdout containing handled: true and request_id, then exits. This is not the CLI's usual schema_version and data envelope. handled: true means the relay answered the request; it does not guarantee that the requested operation succeeded.

With no incoming request, --once continues waiting unless you also use --poll-max or stop it. If the poll limit is reached first, stderr reports no relay job handled before polling stopped; no handled-result object is printed.

Without --device-id, the command reuses a saved device identity in the selected store and creates one if needed. Reusing that store keeps the same identity. An explicit --device-id applies to that run and does not replace the saved default.

The relay cannot perform first encryption setup: complete interactive glob sync now and recovery enrollment first. Existing accounts without recovery remain usable; add recovery later with glob keys recovery.

Troubleshooting

Message or symptom What to check
no local relay API key is stored Create the key through this CLI using the same store.
more than one local relay API key is stored; pass --key-id Select the intended stored key explicitly.
relay API key is not a valid glob_key token Check the supplied value. A session token is a different credential.
provide --scope-json, GLOB_RELAY_SCOPE_JSON, or create the key with this CLI Use the saved key's scope or supply valid scope JSON. Empty values are not usable.
--scope-json is not valid canonical scope JSON Check the version 2 format and reach object.
--device-id must be a UUID Supply the complete UUID, or omit the option to reuse the default.
--poll-max must be positive Use an integer of at least one.
AUTHENTICATION_REQUIRED Sign in with the account again, then restart the relay.
identity_mismatch in a tool's response The selected local key identity does not match the request. Check which key the tool and relay are using.
The tool receives scope_denied Check both the key's scope and any narrower relay scope.
The tool sees old records Sync the selected store and confirm that the relay uses that store.
Requests stop working after key rotation Update the external tool and restart the relay with the replacement key.

When reporting a failure to support, share the error message and relevant key ID rather than the raw token or sync passphrase.