Psiphon client and server components implemented in Go. These components provides core tunnel functionality, handling all aspects of evading blocking and relaying traffic through Psiphon.

go get


Build Status Coverage Status

Psiphon 3 Tunnel Core README


A Psiphon client component implemented in Go. This component provide core tunnel functionality, handling all aspects of connecting to Psiphon servers and relaying traffic through those servers. Local proxies provide an interface for routing traffic through the tunnel.

This component does not include a UI and does not handle capturing or routing local traffic. These major aspects are handled by other parts of Psiphon client applications.


This project is in production and used as the tunneling engine in our Windows and Android clients, which are available at our Psiphon 3 repository.



  • Go 1.5 (or higher) is required.
  • This project builds and runs on recent versions of Windows, Linux, and Mac OS X.
  • Note that the psiphon package is imported using the absolute path; without further local configuration, go will use this version of the code and not the local copy in the repository.
  • In this repository, run go build in ConsoleClient to make the ConsoleClient binary, a console Psiphon client application.

    • Build versioning info may be configured as follows, and passed to go build in the -ldflags argument:

      BUILDDATE=$(date --iso-8601=seconds)
      BUILDREPO=$(git config --get remote.origin.url)
      BUILDREV=$(git rev-parse HEAD)
      -X$BUILDDATE \
      -X$BUILDREPO \
      -X$BUILDREV \


  • Configuration files are standard text files containing a valid JSON object. Example:

        "PropagationChannelId" : "<placeholder>",
        "SponsorId" : "<placeholder>",
        "LocalHttpProxyPort" : 8080,
        "LocalSocksProxyPort" : 1080

Note: The lines <!--BEGIN-SAMPLE-CONFIG--> and <--END-SAMPLE-CONFIG--> (visible in the raw Markdown) are used by the config test. Do not remove them.

  • All config file parameters are documented here.
  • Replace each <placeholder> with a value from your Psiphon server. The Psiphon server-side stack is open source and can be found in our Psiphon 3 repository.


  • Run ./ConsoleClient --config psiphon.config where psiphon.config is created as described in the Configure section above

Other Platforms

  • The project builds and runs on Android. See the AndroidLibrary README for more information about building the Go component, and the AndroidApp README for a sample Android app that uses it.


Please see the LICENSE file.


We maintain a developer mailing list at For more information about Psiphon Inc., please visit our web site at