How-to guides

Running Tandem locally

This is a step-by-step guide on how to run the cipherstash/tandem Docker container locally. We also suggest following the getting started guide to get a feel for how Tandem works, if you haven't already.


  • CipherStash CLI: You need to have the CipherStash CLI installed. If you don't have it, you can install it by following the installation guide.
  • Dataset: You need to have a dataset. If you don't have one, you can create one by following the creating datasets guide.
  • Client Key: You need to have a client key. If you don't have one, you can create one by following the creating clients guide.
  • Access key: You need to have an access key. If you don't have one, you can create one by following the creating access keys guide.
  • Docker: Ensure you have Docker installed on your local machine. If not, download and install it from Docker's official website.

Step-by-Step Guide

1. Prepare the Configuration File

  • Create a JSON file named tandem.json with the following content:

    2  "port": 5442,
    3  "passthrough": true,
    4  "database_url": "postgres://postgres:password@postgres:5432/stash",
    5  "db_pool_size": 1,
    6  "log_level": "info"
  • Save this file in a known directory (for example, ~/tandem-config/).

  • You'll need to update the database_url as this is the URL of your PostgreSQL database.

You can view the full list of configuration options and descriptions in the reference section.

2. Set Up Environment Variables

  • You need to set up the following environment variables. Replace fill_me_in with your actual values:

  • These can be set in your shell, or you can create an .env file to store them.

3. Run the Docker Container

  • Open your terminal.

  • Navigate to the directory where your .env file is located (if you created one).

  • Run the following Docker command:

    1docker run -p 5442:5442 --env-file .env -v ~/tandem-config/tandem.json:/etc/tandem/tandem.json cipherstash/tandem
  • This command does the following:

    • -p 5442:5442 maps port 5442 of the container to port 5442 on your local machine.
    • --env-file .env loads environment variables from the .env file.
    • -v ~/tandem-config/tandem.json:/etc/tandem/tandem.json mounts the configuration file into the container.
    • cipherstash/tandem specifies the Docker image to run.

4. Verify the Container is Running

  • After running the command, Docker should start the container.
  • You can verify that the container is running by executing docker ps.

5. Testing the Connection

  • To test the connection, you can try connecting to the proxy using a PostgreSQL client, targeting localhost on port 5442.
  • Ensure that your PostgreSQL database is accessible at the database_url you specified in the configuration file.

Additional Notes

  • Docker Network: If the PostgreSQL database is also running in a Docker container on the same host, you might need to set up a Docker network for the containers to communicate.
  • Security: Make sure your environment variables and config file are secured, especially since they contain sensitive information.

That's it! You should now have the cipherstash/tandem Docker container running locally, acting as a proxy to your PostgreSQL databases and can now start encrypting your data.

Creating access keys