# 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.
> [!WARNING]
> Agentknock is an early preview. This documentation describes the intended
> product, including components that are not yet publicly available. Preview
> releases provide no backward-compatibility guarantees.
## 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 exec -s gh-token -- 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. 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.
### 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 `exec` command requires at least one secret. Repeat `-s` when a command
needs more than one, and use `--reason` to add context to the request:
```sh
agentknock exec -s gh-token -s cloudflare --reason "Publish release" -- ./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.
### Sign Git commits and tags
An SSH secret keeps its private key on the paired device. 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.
Git must use SSH signing and request a signature. For example:
```sh
agentknock exec -s git-signing -- \
git -c gpg.format=ssh commit -S -m "Describe the change"
```
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 instead. Agentknock does not change `gpg.format`, signing
policy, or the configured signing key.
### 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 unencrypted 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.
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. On Linux, it opens a
native executable before asking the device to prepare the selected secrets and
executes that same filesystem object after approval. This prevents a path,
symlink, or file replacement during the wait from selecting a different
top-level native executable.
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` |
The archives contain a statically linked musl binary and the license files.
The binary does not require a system C library. Command execution requires
Linux 5.8 or later and a mounted `/proc` file system.
Agentknock supports WSL2 through its Linux environment. Use the archive that
matches the WSL2 architecture. Native Windows and macOS clients 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 Linux 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).