Agentknock

Developer secrets on your phone, provided only to approved commands.

Agentknock lets command-line tools use secrets without storing long-lived credentials in agent configuration or project files. A paired mobile device authorizes each request and sends the requested secrets to the command.

[!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:

   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:

curl -fsSL https://github.com/agentknock/agentknock-cli/releases/latest/download/install.sh | bash

Run the same command again to update Agentknock.

Use mise

Use the GitHub release through mise:

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:

npx agentknock --help

To make the command persistently available, install it globally:

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:

nix run github:agentknock/agentknock-cli -- --help

To make the command persistently available, install it in your Nix profile:

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:

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, then download and verify the latest x86-64 Linux archive:

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:

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.

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:

   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:

   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:

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.

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:

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:

agentknock secret list

The command writes a JSON object to standard output. It maps each secret name to its type, description, and the environment variable names that it provides. It never includes secret values. Progress and errors go to standard error, so you can process or redirect the JSON separately.

Upload an environment secret

Agentknock can migrate existing environment variables 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:

agentknock secret upload gh-token \
  --description "GitHub API access" \
  --from-env GH_TOKEN

To migrate all variables from a dotenv file:

agentknock secret upload development --from-env-file .env

To enter values without displaying them:

agentknock secret upload cloudflare --from-prompt CLOUDFLARE_API_TOKEN

To read one variable from a file:

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.

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:

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 the source environment variables 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 requesting secret use 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 and command execution design. The repository also includes reproducible symbolic analysis of the v1 cryptosystem, with claim-by-claim results, assumptions, and limitations. Report suspected vulnerabilities according to the security policy.

Supported platforms

Agentknock supports these client platforms:

Platform	Release archive
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 defines the end-to-end messages and operations exchanged by a client and paired device.
• Client-relay protocol defines the WebSocket interface used by clients.
• Cryptosystem defines the end-to-end cryptographic construction and threat model.
• Command execution defines how the Linux CLI selects, inspects, and starts an approved command.

The Rust API documentation describes the unstable interface for embedding Agentknock in applications. Direct library use is not currently recommended.

User documentation is available at agentknock.dev/doc.

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 before you open an issue or pull request.

License

Agentknock is available under your choice of the Apache License 2.0 or the MIT License.