Getting started

How to use CipherStash

We’ve put together this guide to demonstrate how you can deploy CipherStash with an example application for encryption-in-use.

After following these steps, you will have:

  • Installed the pre-requisites
  • Set up your development environment to use CipherStash
  • Created a CipherStash account
  • Created a dataset that defines what data you want to encrypt
  • Created a client and access key that will be used to authenticate with the CipherStash API
  • Deployed the CipherStash Tandem proxy as a Docker container and routed your database traffic through it
  • Understood how encryption and decryption works with Tandem

At the end of the guide you will have encrypted all the information in your database, but your application will still be able to read and write to the database as if it were unencrypted.

Install prerequisites

To run the application, you'll need to have Docker and Docker Compose installed. If you don't have them installed, you can follow the instructions for your platform:

If you want to query the database directly from your local machine you will need a postgres client. If you don't have this installed, you can follow the instructions for your platform:

  • [PostgreSQL Downloads] (

Setting up your environment

We focus on a developer experience that is centered around the command line. So the first thing you'll need to do is make sure your have installed the CipherStash CLI.

Install the CipherStash CLI

The CipherStash CLI is used to manage your CipherStash account, workspaces, datasets, and a variety of other operational tasks. The CLI is the main way you will interact with CipherStash as a developer.

On macOS

Install via Homebrew:

1brew install cipherstash/tap/stash

macOS prompt

If macOS asks you whether you are sure you want to open "stash", please select "Open".

On Linux

Download the binary for your platform:

  1. Make the binary executable:

    1# on x86_64
    2chmod +x $path_to/stash-x86_64-unknown-linux-gnu
    4# on ARM64
    5chmod +x $path_to/stash-aarch64-unknown-linux-gnu
  2. Rename the binary:

    1# on x86_64
    2mv stash-x86_64-unknown-linux-gnu stash
    4# on ARM64
    5mv stash-aarch64-unknown-linux-gnu stash
  3. Place the binary on your $PATH, so you can run it.

  4. Sign up for a CipherStash account if you do not already have one.

The easiest way to sign up is to login via the CLI:

1stash login

You will see a message on the screen similar to:

1Logging in to console
5Visit to complete authentication by following the below steps:
71. Verify that this code matches the code in your browser
9             +---------------------+
10             |                     |
11             |      ABCD-ZYXW      |
12             |                     |
13             +---------------------+
152. If the codes match, click on the confirm button in the browser
17Waiting for authentication...

Your default web browser will open and you will be prompted to login. If you do not have an account you can click on the link to sign up, or login with GitHub.

Preparing the example application

This guide starts with an example application that assumes you are familiar with the following:

  • Web servers
  • Docker containers
  • PostgreSQL

Start by cloning the repo:

1git clone
2cd tandem-getting-started

The application consists of a NodeJS application that uses Express.js and the native pg driver to connect to a PostgreSQL database. The application is configured to use Docker Compose to run the application and database in containers.

Running the application


Make sure you have Docker Compose installed. Docker Compose is included with the newer versions of Docker Desktop.

Once you have Docker and Docker Compose installed, you can start the application:

1docker compose up

This will start the application and database in containers. You can access the application at http://localhost:3000. The application consists of two routes:

  • / - This is the home page. It displays a welcome message indicating that the application is running.
  • /users - This route displays a list of users from the database. The database is seeded with two users by default.

You can access the database at localhost:5432 with the username postgres and password password if you want to explore the data yourself.

In the next section, we'll set up all the configuration required to deploy the CipherStash Tandem proxy.

Welcome to CipherStash