AgentKit
DocsKitsCLI ReferenceDesktop App
BetaYou are reading docs for the beta channel (3.2.0-beta.10). Features may change before the next stable release.Switch to stable →

remote

ak secrets remote login

Sign in with a device code so this machine can run commands through the vault, or export the refresh token for a cloud sandbox's secret store (preview).

Use ak secrets remote login on a machine that runs ak secrets remote run. It runs the OAuth device authorization grant: you open a link on any device where you are signed in to agentkit.best and confirm a code.

Preview

The remote vault endpoint is pre-release and may not be available for every account yet. If the sign-in server does not offer device sign-in, the command fails with exit 5.

Usage

ak secrets remote login [flags]
ak secrets remote login
ak secrets remote login --export

Options

FlagDefaultDescription
--exportOffPrint the refresh token to stdout for a secret store instead of keeping it. Has no --json form.
--scope stringvault-mcp:useOAuth scopes to ask for.
--issuer stringhttps://agentkit.best, or AGENTKIT_OAUTH_ISSUERAuthorization server origin.
--vault-origin stringhttps://vault.agentkit.bestVault origin.

Shared flags are described in CLI conventions.

What it does

The command prints a link and a code on stderr, with the minutes left before the code expires, then waits while you confirm. The grant allows only running commands (scope vault-mcp:use) and lasts 30 days.

Without --export, the sign-in is written to AGENTKIT_HOME/state/vault-remote.json with mode 0600, replacing any earlier sign-in. The stored sign-in belongs to one issuer and vault origin; a later remote run with another issuer or vault origin asks you to sign in again.

The refresh token rotates on every use, and sending a used one again revokes the grant. So the token is kept in that one file and renewed under a lock (AGENTKIT_HOME/locks/vault-remote.lock), waiting at most 2 minutes for another ak process. If the filesystem cannot lock files, the command warns once that parallel ak secrets remote commands are not serialized; run them one at a time. If a renewal's answer is lost in transit, the next renewal can find the grant revoked; run ak secrets remote login again then.

Cloud sandboxes

With --export, the refresh token is printed once to stdout and nothing is kept on this machine. Set it as AK_VAULT_MCP_REFRESH_TOKEN in the sandbox's secret store. A machine with no stored sign-in uses that variable as a one-time seed. The seed is spent on its first use, so each sandbox that does not keep its AgentKit home needs its own sign-in. A spent seed is refused with a message to run ak secrets remote login or set a fresh token.

Output

On success the command prints Signed in. `ak secrets remote run` can now use <vault origin>. on stderr. With --export, stdout holds only the refresh token.

There is no JSON success output, even with --json. With --json, a failure prints the standard error envelope on stderr. --export with --json is refused before any network call, so the token never lands in structured logs.

Exit behavior

ExitMeaning
0Signed in, or the token was exported.
1Command failure.
2--export with --json, or an invalid --issuer or --vault-origin.
5The sign-in failed: the server offers no device sign-in, the code was denied or expired, or the sign-in could not be stored.