# Agentknock
Developer secrets on your phone, provided only to approved commands.
[Agentknock](https://agentknock.dev/) lets command-line tools use secrets
without storing long-lived credentials in agent configuration or project
files. A paired mobile device authorizes each use. It can return environment
values or perform operations such as Git signing without releasing a private
key.
> Early release · [Share feedback](mailto:agentknock@fulldisclosure.fi)
## How Agentknock works
Agentknock delivers secrets from a paired mobile device when a command needs
them. For example:
1. Run a command with the `gh-token` secret:
```sh
agentknock -s gh-token \
--reason "GitHub token provides write access to the repository" \
-- gh pr merge 123
```
2. The paired mobile device displays the request. Approve the use of
`gh-token` for this command.
3. Agentknock runs `gh pr merge 123` with access to `gh-token`. The secret is
available only to that execution and is not printed or written to disk.
## Install the Agentknock client
Choose one of the following installation methods.
### Use the installation script
The installation script selects the latest prebuilt release for the current
platform, verifies its published SHA-256 checksum, and installs `agentknock`
in `~/.local/bin`:
```sh
Run the same command again to update Agentknock.
### Use mise
Use the GitHub release through mise:
```sh
mise use --global github:agentknock/agentknock-cli
```
mise verifies the GitHub build attestation when one is available for the
release artifact.
Run `mise upgrade github:agentknock/agentknock-cli` to update Agentknock.
### Use npm
Run Agentknock without installing it globally:
```sh
npx agentknock --help
```
To make the command persistently available, install it globally:
```sh
npm install --global agentknock
```
The npm package requires Node.js `^22.15.0` or `>=24.0.0`. Run
`npm update --global agentknock` to update Agentknock.
### Use Nix
Run Agentknock without installing it in a profile:
```sh
nix run github:agentknock/agentknock-cli -- --help
```
To make the command persistently available, install it in your Nix profile:
```sh
nix profile add github:agentknock/agentknock-cli
```
Run `nix profile upgrade agentknock-cli` to update Agentknock.
### Build from source with Cargo
Install Rust 1.89 or later, then build and install Agentknock from crates.io:
```sh
cargo install --locked agentknock
```
Run the same command again to update Agentknock.
### Verify a release
Agentknock publishes each release as an immutable GitHub release. GitHub locks
the release tag and attached files after publication and generates a release
attestation for them. The release archives also have build-provenance
attestations generated by the Agentknock release workflow.
Install the [GitHub CLI](https://cli.github.com/), then download and verify the
latest x86-64 Linux archive:
```sh
repository=agentknock/agentknock-cli
tag=$(gh release view --repo "$repository" --json tagName --jq .tagName)
target=x86_64-unknown-linux-musl
archive=agentknock-${target}.tar.gz
gh release download "$tag" --repo "$repository" \
--pattern "$archive" --pattern "$archive.sha256"
sha256sum --check "$archive.sha256"
gh release verify "$tag" --repo "$repository"
gh release verify-asset "$tag" "$archive" --repo "$repository"
gh attestation verify "$archive" --repo "$repository" \
--signer-workflow agentknock/agentknock-cli/.github/workflows/ci.yml
```
Use `aarch64-unknown-linux-musl` as `target` for an ARM64 Linux system or
`aarch64-apple-darwin` for an Apple Silicon Mac. On macOS, replace the
`sha256sum` command with `shasum -a 256 --check`. Release verification confirms
that the downloaded archive is part of the immutable release.
Build-provenance verification confirms that the Agentknock release workflow
built that archive from the identified source revision. Neither verification
determines whether the source code itself is safe.
The pinned Nix build can independently reproduce the release archive. On a
system with Nix installed, check out the release and compare the resulting
file:
```sh
git clone --branch "$tag" --depth 1 \
https://github.com/agentknock/agentknock-cli.git "agentknock-cli-$tag"
cd "agentknock-cli-$tag"
make dist DIST_TARGET="$target"
cmp "../$archive" "target/dist/$archive"
```
A successful comparison means that the local build produced the same archive
as the GitHub release.
## Install the Agentknock mobile app
### Google Play
Install the Agentknock app from
[Google Play](https://play.google.com/store/apps/details?id=dev.agentknock).
### App Store
The Agentknock app for iOS isn't available yet.
## Get started
Agentknock includes its complete command-line reference in `--help`. Run
`agentknock --help` for an overview, or use `--help` with any command for
detailed instructions.
### Choose the Agentknock directory
Agentknock stores pairing state in `$HOME/.agentknock/pairing.json`. If your
execution environment needs another location, set `AGENTKNOCK_HOME` to a
nonempty absolute UTF-8 directory path before pairing:
```sh
export AGENTKNOCK_HOME=/persist/agentknock
```
Use the same directory for pairing and subsequent commands. It must remain
writable because Agentknock updates the pairing keys during use. Selecting
another directory does not copy or move an existing pairing.
The global `--agentknock-home` option overrides the environment variable for
one command. Relative option paths are resolved against the current working
directory:
```sh
agentknock --agentknock-home /persist/agentknock \
-s gh-token --reason "GitHub token provides access to private repository issues" \
-- gh issue list
```
Neither setting changes the wrapped command's `HOME`. An existing
`AGENTKNOCK_HOME` is inherited normally; the option does not set or change it
for the wrapped command. With either override, Agentknock does not require
`HOME` and does not fall back to another directory if the selected location
is unusable.
### Pair the client
Use the pairing address that you selected when you set up the mobile app. For
example, if the address is `calm-river-lantern`:
1. Start pairing on the client:
```sh
agentknock pairing start calm-river-lantern
```
2. Confirm the full 12-digit verification code on the mobile device, then
approve the pairing. If the code doesn't match, reject the pairing and run
`agentknock pairing abort`.
3. After you approve the pairing, activate it on the client:
```sh
agentknock pairing finish
```
The client can now request secrets from the paired mobile device.
### Run a command with secrets
The `run` command requires at least one secret. Repeat `-s` when a command
needs more than one. Use `--reason` to explain why each selected secret is
needed, such as API access, SSH authentication, or a signing operation. The
command and arguments already describe the action.
You can omit `run` and put its options directly after `agentknock`. For a
release script that needs both GitHub and Cloudflare access:
```sh
agentknock -s gh-token -s cloudflare \
--reason "GitHub token for repository access; Cloudflare token for deployment access" \
-- ./release.sh
```
The explicit form is equivalent:
```sh
agentknock run -s gh-token -s cloudflare \
--reason "GitHub token for repository access; Cloudflare token for deployment access" \
-- ./release.sh
```
The `--` separator is required. Agentknock passes the command and every
argument after the separator unchanged.
Agentknock waits for the paired mobile device to authorize the request and
return the secrets before it starts the command. If the request is still
waiting after 30 seconds, Agentknock writes a progress update with the elapsed
time to standard error every 30 seconds. Press Ctrl-C to cancel the request.
#### Control environment-variable delivery
By default, an environment secret provides all its variables under their
stored names. Delivery controls name both the secret and its stored variable,
so they remain unambiguous when a command uses multiple secrets.
Use `--only-env` to select a subset, or `--omit-env` to exclude variables:
```sh
agentknock -s github \
--reason "GitHub token provides access to private repository issues" \
--only-env github GH_TOKEN \
-- gh issue list
agentknock -s development \
--reason "Development credentials authenticate the server to its database" \
--omit-env development DEBUG_TOKEN \
-- ./run-development-server
```
Repeat either option for more variables. You cannot combine `--only-env` and
`--omit-env` for the same secret.
Use `--rename-env` to give a selected variable a different name in the command
environment:
```sh
agentknock -s github \
--reason "GitHub token authenticates the command's API requests" \
--only-env github GH_TOKEN \
--rename-env github GH_TOKEN GITHUB_TOKEN \
-- ./command-expecting-github-token
```
Use `--stdin` to send one stored variable to the command's standard input:
```sh
agentknock -s service-password \
--reason "Service password is required to authenticate the service account" \
--only-env service-password PASSWORD \
--stdin service-password PASSWORD \
-- ./command-reading-a-password
```
Agentknock sends the exact value without adding a newline, closes the input,
and does not add that variable to the command environment. Other variables
from the secret remain in the environment unless you restrict them with
`--only-env`. One command can receive at most one value on standard input.
Agentknock applies these controls separately to each secret before it combines
their environment values. If multiple values have the same final name, their
values must match.
### Use SSH keys
An SSH secret keeps its private key on the paired device. Agentknock makes the
selected public key available to the command through a temporary SSH agent.
The temporary agent also makes keys from an existing SSH agent available.
When SSH uses the selected key, Agentknock sends the exact authentication
request to the device for a separate decision. Other keys continue to use the
existing agent. Agentknock authentication currently supports Ed25519 and RSA
keys.
Use the SSH secret with a direct connection:
```sh
agentknock -s production-ssh \
--reason "SSH key is required to authenticate to example.com" -- ssh example.com
```
The same setup works when Git uses an SSH remote:
```sh
agentknock -s github-ssh \
--reason "SSH key authenticates Git access to the GitHub repository" -- git push
```
The command can select at most one SSH secret. Agentknock puts that key first
in the temporary agent and then lists keys from any existing agent. Agentknock
never sends the selected private key to the client or command.
Use `--no-ssh-passthrough` when the temporary agent should not expose keys from
the existing agent:
```sh
agentknock --no-ssh-passthrough -s production-ssh \
--reason "SSH key is required to authenticate to example.com" -- ssh example.com
```
This option also makes Git SSH signing fail if Git requests a different key.
It does not prevent the command from using private-key files or another agent
selected in SSH configuration.
Use `--no-ssh-agent` when the command should receive no `SSH_AUTH_SOCK` at all.
Agentknock Git signing remains available unless you also use `--no-git-sign`.
An `IdentityAgent` setting in SSH configuration takes precedence over
`SSH_AUTH_SOCK`. Set `IdentityAgent SSH_AUTH_SOCK` for a host that should use
the Agentknock agent.
### Sign Git commits and tags
When Git requests a signature while running a command through Agentknock,
Agentknock sends Git's exact signing payload to the device so it can show the
commit or tag message for a separate decision. For commits, it also sends
available repository, branch, and changed-path context to help identify the
requested signature.
With Git configured to sign commits using SSH, wrap your usual command:
```sh
agentknock -s git-signing --reason "SSH key is required to sign the commit" -- git commit
```
Use `--no-git-sign` when Agentknock should not provide Git signing. Agentknock
then leaves the existing Git signing configuration unchanged; that
configuration can still sign commits or tags independently.
A command can select at most one SSH secret. If Git has no configured
`user.signingKey`, Agentknock offers the selected SSH key as the default. If
Git explicitly selects another key, signing proceeds through the ordinary
`ssh-keygen` command unless you use `--no-ssh-passthrough`. It can use a key
file or a key from the existing SSH agent as usual. Agentknock does not change
`gpg.format`, signing policy, or the configured signing key. Git signing can
use SSH key types that Agentknock does not yet support for SSH authentication.
### Use a network proxy
Agentknock uses `HTTPS_PROXY` for its secure WebSocket connection to the relay
and falls back to `ALL_PROXY`. The lowercase forms `https_proxy` and
`all_proxy` are also supported and take precedence over their uppercase forms.
Set `NO_PROXY` or `no_proxy` to exclude hosts from proxying. Proxy URLs can use
HTTP or HTTPS and can include HTTP Basic authentication credentials.
For example, connect through an HTTP proxy:
```sh
HTTPS_PROXY=http://proxy.example:8080 agentknock secret list
```
## Manage secrets
Manage secrets primarily in the mobile app. The commands in this section
contact the paired mobile device and wait for its response. During a long wait,
Agentknock reports progress and elapsed time every 30 seconds.
### List secrets
Request the secrets available to this client:
```sh
agentknock secret list
```
The command writes a JSON object to standard output. It maps each secret name
to its type, description, and type-specific public metadata, such as
environment variable names or an SSH public key. It never includes secret
values. Progress and errors go to standard error, so you can process or
redirect the JSON separately.
### Upload secrets
Agentknock can migrate existing environment variables and SSH private keys to
the mobile app. It reads values from the sources that you specify; the values
do not appear in the command arguments.
To migrate a variable from the current environment:
```sh
agentknock secret upload gh-token \
--description "GitHub API access" \
--from-env GH_TOKEN
```
To migrate all variables from a dotenv file:
```sh
agentknock secret upload development --from-env-file .env
```
To enter values without displaying them:
```sh
agentknock secret upload cloudflare --from-prompt CLOUDFLARE_API_TOKEN
```
To read one variable from a file:
```sh
agentknock secret upload npm --from-file NPM_TOKEN=/path/to/token
```
You can repeat and combine `--from-env`, `--from-env-file`, `--from-file`, and
`--from-prompt`. Use `--from-env-file -` to read dotenv data from standard
input, or `--from-file NAME=-` to read one value from standard input.
To upload an SSH private key in OpenSSH private-key format:
```sh
agentknock secret upload git-signing \
--description "Git signing key" \
--from-ssh-key ~/.ssh/id_ed25519
```
Use `--from-ssh-key -` to read the key from standard input. An SSH-key source
cannot be combined with environment-variable sources.
`ssh-keygen` can convert a legacy PEM key to OpenSSH format in place:
```sh
ssh-keygen -p -f ~/.ssh/id_rsa
```
Agentknock rejects an encrypted private key unless you explicitly provide its
passphrase source. To enter the passphrase without displaying it, add
`--passphrase-prompt`. For a noninteractive upload, use
`--passphrase-env NAME` to read the passphrase from an environment variable.
Agentknock removes the passphrase protection locally and sends only the
resulting passphrase-free OpenSSH key. Agentknock's end-to-end encryption
protects the key in transit, and the mobile app stores it encrypted. The
passphrase is never sent to the mobile app.
An upload is a proposal, not an immediate change to the secrets on the mobile
device. The command finishes after the mobile app confirms receipt of the
proposal. Review and accept the proposal in the mobile app before the secret
becomes available to this client.
By default, an upload proposes a new secret. Use `--update` to change the
values that you provide while retaining the other values in an existing
secret:
```sh
agentknock secret upload gh-token --update --from-prompt GH_TOKEN
```
Use `--replace` to propose a complete replacement. Values that you don't
provide are removed if you accept the proposal. When you propose a new secret,
you can change its name before you accept it in the mobile app.
Uploading does not modify or delete source environment variables, private
keys, or files. After you accept the proposal and verify the secret, remove
old local copies that you no longer need.
## Security
Agentknock uses a relay service to carry messages between the client and mobile
device. The security design treats the relay as untrusted. The client and
mobile app are both open source and protect messages with end-to-end encryption
and authentication. After you verify a pairing, the relay cannot obtain secret
values, read other protected contents, or alter an accepted protected message
without detection. It can observe routing metadata, message sizes, timing, and
traffic relationships, and it can deny service.
Starting a pairing is unauthenticated: anyone who knows the pairing address can
send a request. Confirm the full 12-digit verification code before you approve
a pairing on the mobile device. The code identifies the exact client that you
intend to trust, including when multiple pairing requests are pending. It also
detects substitution by the relay and lets the relay remain outside the trust
boundary. Reject the pairing if you cannot confirm the complete code.
Agentknock never writes delivered secret values to disk. It opens the selected
executable before asking the device to prepare the secrets, reports its path
and hash when available, and revalidates it after approval. Linux executes a
retained native executable directly. macOS must execute its path and therefore
has a small final pathname race after revalidation.
For directly executed shebang scripts at most 16 KiB, Agentknock also sends the
entire source to the device for use in AI review by supporting devices. Invalid
UTF-8 sequences become replacement characters (`�`); hashing and execution use
the original bytes. Larger scripts omit the source and retain their full-file
hash. Source is sent before approval, may contain sensitive information, and
reaches the review service when included in AI review. Only the selected script
is captured; interpreter arguments and dependencies are not followed.
Agentknock is not a sandbox or privilege boundary. The approved command
controls the secrets that it receives and can print them, write them to disk,
or otherwise disclose them. Only approve secret access for commands that you
trust to handle the values safely. Descendant commands and other processes
with sufficient same-user inspection access might also observe them.
For the complete design, threat model, and limitations, read the
[Agentknock v1 cryptosystem](docs/cryptosystem.md) and
[command execution design](docs/command-execution.md).
The repository also includes [reproducible symbolic
analysis](verification/cryptosystem/README.md) of the v1 cryptosystem, with
claim-by-claim results, assumptions, and limitations.
Report suspected vulnerabilities according to the
[security policy](https://github.com/agentknock/agentknock-cli/security/policy).
## Supported platforms
Agentknock supports these client platforms:
| x86-64 Linux | `agentknock-x86_64-unknown-linux-musl.tar.gz` |
| ARM64 Linux | `agentknock-aarch64-unknown-linux-musl.tar.gz` |
| Apple Silicon macOS | `agentknock-aarch64-apple-darwin.tar.gz` |
Each archive contains the Agentknock binary and license files. The Linux
archives contain a statically linked musl binary and do not require a system C
library. Linux command execution requires Linux 5.8 or later. SSH authentication
and Git signing also require a mounted `/proc` file system. The macOS archive
requires Apple Silicon and macOS 15 or later.
Agentknock supports WSL2 through its Linux environment. Use the archive that
matches the WSL2 architecture. Native Windows clients and Intel Macs are not
supported.
## Documentation
- [Client-device protocol](docs/client-device-protocol.md) defines the
end-to-end messages and operations exchanged by a client and paired device.
- [Client-relay protocol](docs/client-relay-protocol.md) defines the WebSocket
interface used by clients.
- [Cryptosystem](docs/cryptosystem.md) defines the end-to-end cryptographic
construction and threat model.
- [Command execution](docs/command-execution.md) defines how the CLI selects,
inspects, and starts an approved command.
The [Rust API documentation](https://docs.rs/agentknock) describes the
unstable interface for embedding Agentknock in applications. Direct library
use is not currently recommended.
User documentation is available at
[agentknock.dev/docs](https://agentknock.dev/docs/).
## Contribute
Contributions are welcome as bug reports, feature proposals, and design
discussions in GitHub issues. The maintainers write the final implementation;
pull requests can serve as prototypes or reproductions but are not merged.
Read [Contributing to Agentknock](CONTRIBUTING.md) before you open an issue or
pull request.
## License
Agentknock is available under your choice of the
[Apache License 2.0](LICENSE-APACHE) or the [MIT License](LICENSE-MIT).