»Install Waypoint

Waypoint uses both a client and a server to build, deploy, and release applications. This functionality is all available from a single binary.

»Download the Binary

To install Waypoint, find the appropriate package on the releases site for your system and download it as a zip archive.

After downloading Waypoint, unzip the package. Waypoint runs as a single binary named waypoint. Any other files in the package can be safely removed and Waypoint will still function.

To make the binary available from anywhere on your system, you can either copy it into /usr/local/bin or add it to a different directory in your PATH. For instructions on how to do that, see Editing your Path.

$ cp ~/Downloads/waypoint /usr/local/bin

Validate the installation by running the waypoint command.

$ waypoint
Usage: waypoint [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    release      Release a deployment.
    up           Perform the build, deploy, and release steps for the app.
    build        Build a new versioned artifact from source.

»Pull the Latest Waypoint Server Image

First, configure Docker authentication for accessing GitHub packages by following these steps.

Next, create a new Personal Access Token on GitHub, save it to a file, and then login to Docker.

$ cat ~/TOKEN.txt | docker login https://docker.pkg.github.com -u GITHUBUSERNAME --password-stdin

When you run waypoint install, Waypoint will uses an image hosted on the GitHub Docker registry by default, and this secret will be used to authenticate to that registry.

Now you need to download the image so that we can start a container with it:

$ docker pull docker.pkg.github.com/hashicorp/waypoint/alpha:latest

»Install the Waypoint Server

Install the Waypoint server to Docker Desktop on your computer. This allows you to view the user interface, collaborate on deployments, and more.

Run the following command to install the Waypoint server.

 $ waypoint install -platform=docker

You may also install the server to a Kubernetes cluster or a Nomad cluster. To learn more about Kubernetes, see the getting started guide for deploying an app to Kubernetes. The walkthrough shows you how to deploy the server and an example app to Kubernetes.


One of the functions of install is that it creates a context automatically that points to the newly created server with authentication. This is how Waypoint knows the address of the server when you run later Waypoint commands.

»About the Server Workflow

When you deploy your app with Waypoint, your computer (the Waypoint client) connects to the Waypoint server to initiate the Waypoint workflow. The client then registers itself as a runner, allowing Waypoint to run builds on it.

When the build is completed, the Waypoint server sends the build artifacts, such as a container image, to the artifact registry of your choice. Multiple Waypoint clients can concurrently connect to a single server to deploy and release applications.

»Editing your Path (Optional)

If you do not want to copy Waypoint into a file already in your path, you can edit your PATH to include a directory that contains the Waypoint binary. This allows you to use the waypoint command without having to include the full directory path to the binary.

See what is in your current $PATH definition.

$ echo $PATH

If you do not have an entry for the Waypoint binary, add the following line to your shell profile:

export PATH=$PATH:my-directory-path-to-waypoint-binary

For example: export PATH=$PATH:~/enlistments/waypoint

  • To determine your shell, run echo $SHELL
  • If using Bash, use nano ~/.bash_profile to edit your Bash profile.
  • If using ZSH, use nano ~/.zshrc to edit your ZSH profile.

»Next Step

Getting Started: Initialize Waypoint