Skip to main content

Installation

Installing the CLI can be done in different ways depending on your operating environment.

info

Polykey Core Overview​

The Polykey CLI and core primarily use TypeScript for service logic, domain business operations, and persistence layers. While the main codebase is in TypeScript, some supporting libraries incorporate native C++ or Rust for platform‐specific functionality. This approach combines cross‐platform convenience with native performance optimizations. Polykey-CLI has only been tested on Linux and macOS. We are working on supporting other platforms. There's minor teething problems when it comes supporting other platforms. Help us by reporting any issues with the CLI tool in our Github Repo here or by dropping a message to the developers in our discord server here

Linux​

Polykey-CLI code is compiled, bundled and wrapped into a single file executable. You just have to download the executable, give it executable permissions and run it. The executable is not statically linked. It requires a subset of the system libraries that Node.js requires.

  • libdl.so.2
  • libstdc++.so.6
  • libm.so.6
  • libgcc_s.so.1
  • libpthread.so.0
  • libc.so.6

Manually​

Using the Polykey CLI via the terminal​

If you prefer not to use a package manager or Docker, you can install Polykey directly via the terminal using a prebuilt binary.

  1. Download the executable from the GitHub releases page and rename it to polykey.

  2. Make it executable:

chmod u+x ./polykey
  1. Add the executable to your PATH

To run polykey from anywhere, you need to add the directory containing it to your PATH. You can either:

  • Move polykey into an existing directory already in your PATH (e.g., /usr/local/bin), or
  • Add the polykey directory to your PATH, either temporarily or permanently:

Temporarily (until terminal closes):

export PATH="$HOME/Downloads:$PATH"

Permanently:

To permanently add polykey to PATH on zsh, run the following command.

echo 'export PATH="$HOME/Downloads:$PATH"' >> ~/.zshrc && source ~/.zshrc
Setting PATH across operating systems

Where you place the polykey binary — and how you add it to your PATH — depends on your OS:

  • Linux: Preferred location is ~/.local/bin (you may need to create it using mkdir -p ~/.local/bin). Make sure this directory is included in your $PATH — often via ~/.bashrc, ~/.bash_profile, or ~/.profile.

  • macOS: Same as Linux — use ~/.local/bin or ~/bin. Update your $PATH in ~/.zshrc (ZSH is default on macOS since Catalina) or ~/.bash_profile if using Bash.

  • Windows: Place polykey.exe into:

%USERPROFILE%\AppData\Local\Microsoft\WindowsApps

This location is typically already included in the system PATH.

To verify it’s working, run:

which polykey
polykey --version
  1. Confirm the installation with:
polykey --version

If it returns the version, you’re ready to use the CLI.

Important

Once you start a long‑lived command like polykey agent start, that process monopolizes the current terminal window. To issue any further Polykey commands (for example, polykey vaults create) you must open a new terminal window.

If the machine reboots or the agent exits, simply rerun polykey agent start in a terminal to restart it.

Tip

If you see an error like:

WARN:polykey.PolykeyAgent:Failed Creating PolykeyAgent — another agent may already be running

This means the Polykey agent is already running. To manage this, you can:

Check the agent status:

polykey agent status

If the agent returns something like this:

status DEAD

Then the agent is inactive and needs to be restarted. If it returns something other than this, then it is still active.

Stop the running agent:

polykey agent stop

You must stop the current agent or use a different terminal before starting a new one. The currently running agent must be stopped before it can be re-run.

NixOS​

We have not yet published a Nix package for Polykey. When we do, you will be able to just install polykey-cli from Nixpkgs.

However, it is easy enough to install it from source.

Clone the repository:

git clone https://github.com/MatrixAI/Polykey-CLI.git

Enter the nix-shell:

nix-shell

Build the application and install it into the user profile:

nix-env -f ./release.nix --install --attr application --argstr npmDepsHash "$(prefetch-npm-deps ./package-lock.json)"

Other​

We are working on other distribution methods. Check back soon.