3.2.0-beta.10). Features may change before the next stable release.Switch to stable →remote
ak secrets remote run
Run a program on one of your online relay devices with vault secrets in its environment and print its redacted output; nothing runs locally (preview).
Use ak secrets remote run on a machine that must not hold secrets, such as a
cloud agent sandbox. The command calls the vault's secrets_run tool, and one
of your online relay devices runs the program with the secrets in its
environment. The output comes back with every released value redacted. Sign in
first with ak secrets remote login.
Preview
The remote vault endpoint is pre-release and may not be available for every account yet.
Usage
ak secrets remote run --env VAR=REF... [flags] -- PROGRAM [ARGS...]ak secrets remote run --env GH_TOKEN=GITHUB_TOKEN -- gh release list
ak secrets remote run --project my-app --env DATABASE_URL=PROD_DB -- ./scripts/migrate-status.shThe program and its arguments must follow --; otherwise the command exits
2.
Options
| Flag | Default | Description |
|---|---|---|
--env VAR=REF | Required | Give secret REF to the program as VAR. Repeat it, 1 to 16 times. |
--project string | None | Registered project on the relay device to run in. |
--vault-id string | None | Vault to use when the online devices hold several. |
--timeout int | Chosen by the device | Seconds the device lets the program run, 1 to 110. |
--issuer string | https://agentkit.best, or AGENTKIT_OAUTH_ISSUER | Authorization server origin. |
--vault-origin string | https://vault.agentkit.best | Vault origin. |
Shared flags are described in CLI conventions.
The command checks these limits before it sends anything, and exits 2 when
one fails:
- 1 to 64 program arguments after
--. - 1 to 16
--envpairs. EachVARmatches[A-Z_][A-Z0-9_]*, is at most 128 bytes, and appears once. Each pair names a secret. --projectis at most 128 characters.--timeout, when set, is 1 to 110 seconds.
What it does
The command runs nothing locally. It renews the sign-in in
AGENTKIT_HOME/state/vault-remote.json when needed, then asks the vault to
relay the run to a device that holds a relay connection open with
ak secrets sync now --watch --relay.
The relay device runs the program only when an exec grant it holds for this
client covers every VAR=REF pair. It never prompts. Otherwise it files a
request in its approval inbox and this command exits 8. Approve the request
on that device with ak secrets approve or the AgentKit Desktop approvals
inbox, then run the command again. Approve every scope a task needs before the
task starts.
The program, its arguments, and --project are resolved on the relay device,
not on this machine.
Output
The program's stdout and stderr are printed to this command's stdout and stderr, with released values redacted by the device. Redaction removes exact values only; output that prints a value encoded, split, or in part is not caught.
Before printing, the command removes what a terminal would act on: ANSI escape sequences, control characters other than tab, newline, and carriage return, bytes that are not valid UTF-8, and bidirectional overrides and isolates.
If the device cut the output to fit its answer, the command adds
secrets remote run: the device cut the output to fit its answer on stderr.
There is no JSON success output, even with --json. With --json, a failure
prints the standard error envelope on stderr.
Exit behavior
The command exits with the program's status. When the program exits nonzero,
the command first prints secrets remote run: the program exited N on stderr,
so a program status of 5, 6, or 8 is not mistaken for a refusal. A status
above 255 is capped at 255.
When the vault or the relay device refuses the run or cannot complete it, the command exits:
| Exit | Meaning |
|---|---|
2 | Invalid flags or arguments, or the vault found them invalid, or --vault-id is needed or unknown. |
3 | The relay device has no secret by a ref given. |
5 | No sign-in, no relay device online, the device did not answer in time (the outcome is then unknown), or the vault could not serve the run. For no device online, the message says to start ak secrets sync now --watch --relay on a device that holds the vault. |
6 | The relay device refused the run, for example the program was not found or is not allowed. |
8 | No exec grant covers the run; a request waits for ak secrets approve on the relay device. |
9 | Too many calls; retry later. The message gives the wait in seconds when the vault sends one. |