Authentication
The Cmdop SDK and CLI both authenticate to a relay. On a machine that has already joined a fleet, the credential is in the OS keyring and nothing needs configuring. From anywhere else, set a relay URL and a relay token; an explicit remote URL without a token fails closed rather than falling back to a local one.
Both programmatic surfaces authenticate to a relay. Which relay and which credential depends on whether you are running on a machine that has already joined a fleet, or reaching a relay from somewhere else.
On a machine that has joined, there is nothing to configure
A machine that has run cmdop join already holds a credential for its active
relay, stored in the OS keyring. The SDK’s zero-argument client and every CLI
command reuse it:
from cmdop import Client
async with Client() as client:
snapshot = await client.machines.list()This is the normal case. Do not mint a second credential for code running on a machine that is already part of the fleet.
Targeting a remote relay explicitly
When the program runs somewhere that has not joined a fleet, point it at a relay and give it a token:
export CMDOP_BASE_URL="https://relay.example.com"
export CMDOP_TOKEN="<relay-token>"The same zero-argument client then uses them, or pass them to the constructor when configuration has to stay inside the application. An explicit remote URL without a token fails closed — it will not silently fall back to whatever local credential happens to be present.
For a single CLI invocation, the equivalent is a one-shot override:
CMDOP_SERVER_URL=https://relay.example.com \
CMDOP_GRPC_URL=relay.example.com:443 \
cmdop statusSee Configuration for the full precedence rules.
A machine may still ask for its PIN
Authenticating to the relay gets you to the relay. Attaching to a specific machine can additionally require that machine’s connection PIN, when one is armed. Supply it with the request rather than expecting a challenge:
stream = client.machines.ask(machine_id, "Report disk usage.", pin="1234")Credentials do not cross planes
The relay credential your code uses is not the relay’s browser admin password, not the fleet join key, and not your inference provider key. They are separate and rotate independently — see Joining and access issues.
Keep tokens out of source control and out of command lines that end up in shell history or CI logs.
Common questions
How does the Cmdop SDK authenticate?
On a machine that already ran cmdop join, the SDK reuses the active relay
credential from the OS keyring. From anywhere else, set an explicit relay URL
and relay token.
What happens if I set a remote relay URL without a token?
The request fails closed. Cmdop does not silently fall back to a local credential when you explicitly pointed it at a remote relay.
Is the relay token the same as a join key?
No. A relay token, fleet join key, relay admin password, connection PIN, and inference credential are separate. They rotate independently and are not substitutes for each other.
Cmdop