How to connect to services on from your local system


Access services from a local computer, over a secure SSH tunnel.


  • The CLI is installed locally.
  • Whatever additional software is needed (local web server, local mysql client, etc.) is already installed locally.


By default the CLI will use the current environment. However, when using a 3rd party integration from GitHub or GitLab the desired environment will likely be a PR environment, not the environment that the user is working on directly. That will require extra commands as shown below.


1. Open an SSH tunnel

Run the following command locally:

platform tunnel:open

That will open an SSH tunnel to the current environment and map all services defined on the application to local ports. Accessing those ports locally with the appropriate tool (mysql command line, Redis CLI client, etc.) will connect to the service on the environment.

2. Export relationships

Run the following command locally:

export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

That will create a PLATFORM_RELATIONSHIPS environment variable locally that provides user/password/host/port credentials to connect to the current environment. A local application that checks that environment variable in order to connect to services on will work just the same as if it were on (It will not, however, make any other environment variables available.)

It is also possible to combine both commands into a single line, like so:

platform tunnel:open && export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode)"

3. Disconnect from the tunnel

When done, clean up the open connections by running:

platform tunnel:close

Alternative: Connect to a Pull Request environment

Both commands above will, by default, use the current branch name/environment. However, the environment created by a Pull Request from GitHub, Bitbucket, or GitLab will be different and thus the above commands will not connect to them. To access a Pull Request environment modify both commands to specify the environment name.

For example, a GitHub Pull Request #42 will have an environment name on of pr-42, so run:

platform tunnel:open -e pr-42 && export PLATFORM_RELATIONSHIPS="$(platform tunnel:info --encode -e pr-42)"

The -e pr-42 (or equivalently --environment pr-42) tells the CLI to connect to the pr-42 environment rather than the environment that corresponds to the branch currently checked out.


With access to the remote services, customers can take whatever action they need. That includes running code locally against a remote service, accessing the service using a management tool appropriate for that service, or any other task. Just remember the caveat about Pull Request environments.