Running CipherStash Proxy locally

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


  • CipherStash CLI: You need to have the CipherStash CLI installed. If you don't have it, follow the installation guide.
  • Access key: If you don't have an access key, create one by following the creating access keys guide.
  • Docker: Make sure you have Docker installed on your local machine. If you don't, download and install it from Docker's official website.

Step-by-step guide

1. Prepare the configuration file

  • Create a JSON file named cipherstash-proxy.toml with the following content:

    1username = "postgres"
    2password = "password"
    4workspace_id = "12345678-1234-1234-1234-123456789012"
    5client_access_key = "12345678-1234-1234-1234-123456789012"
    8name = "stash"
    9host = "localhost"
    10port = 5432
  • Save this file in a known directory (for example, ~/cipherstash-proxy-config/).

  • You'll need to update the config to match your use case.

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

2. 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 6432:6432 -v ~/cipherstash-proxy-config/cipherstash-proxy.toml:/etc/cipherstash-proxy/cipherstash-proxy.toml cipherstash/cipherstash-proxy
  • This command does the following:

    • -p 6432:6432 maps port 6432 of the container to port 6432 on your local machine.
    • -v ~/cipherstash-proxy-config/cipherstash-proxy.toml:/etc/cipherstash-proxy/cipherstash-proxy.toml mounts the configuration file into the container.
    • cipherstash/cipherstash-proxy specifies the Docker image to run.

3. 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.

4. Test the connection

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


  • 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/cipherstash-proxy Docker container running locally, acting as a proxy to your PostgreSQL databases and can now start auditing your data access logs and/or start encrypting your data.

AWS Marketplace