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

Run a program with vault secrets on one of your online relay devices from a machine that must not hold secrets, such as a cloud agent sandbox (preview).

Use ak secrets remote on a machine that must not hold secrets, such as a cloud coding-agent sandbox. It asks the vault's remote MCP endpoint to run a program on one of your own online relay devices, under that device's exec grants, and prints the output with every released value redacted. The values never reach the calling machine. Running the group command itself prints help.

Preview

ak secrets remote is a preview. The remote vault endpoint it uses is pre-release and may not be available for every account yet. If the sign-in server does not offer device sign-in, ak secrets remote login fails with exit 5.

Usage

ak secrets remote <command>
ak secrets remote login
ak secrets remote run --env STRIPE_API_KEY=STRIPE_API_KEY -- stripe customers list

The group accepts no positional arguments and has no flags of its own.

Workflow

  1. On a device that holds the vault, keep a relay connection open:

    ak secrets sync now --watch --relay

    See Keep a device online.

  2. On the machine that must not hold secrets, sign in with ak secrets remote login. For a sandbox that does not keep its AgentKit home, use --export on a trusted machine and set the printed token as AK_VAULT_MCP_REFRESH_TOKEN in the sandbox's secret store.

  3. Run the program with ak secrets remote run. If no exec grant on the relay device covers the run, the command exits 8 and a request waits on that device. Approve it there with ak secrets approve, then run the command again. Approve every scope a task needs before the task starts.

What passes through where

  • The secret values reach the relay device and the program it runs, never the calling machine.
  • The vault server sees the command, the variable and secret names, and the redacted output in memory while it passes them on.
  • Redaction removes exact values only. A program that prints a value encoded, split, or in part is not caught.

Subcommands

CommandOutcomeDisk effect
ak secrets remote loginSign in with a device code, or export a refresh token for a sandbox.Writes AGENTKIT_HOME/state/vault-remote.json (0600), unless --export.
ak secrets remote runRun a program on a relay device and print its redacted output.Renews the sign-in in the same file when needed. Runs nothing locally.

No subcommand reads the local vault.

Exit behavior

ExitMeaning
0Success.
1Command failure.
2Invalid flags or arguments.

Each subcommand page lists its own exit codes.