Skip to content
Simple, topic-based PUB/SUB WebSocket server.
Go Makefile Shell
Branch: master
Clone or download
Latest commit f06d0bf Feb 21, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
script Deprecated May 17, 2017
.env.sample Nicer env names May 16, 2017
.gitignore Adds make install Jun 29, 2016
.travis.yml Travis May 19, 2017 Use md Jan 20, 2016
Godeps new logger May 15, 2017
LICENSE Update LICENSE Jun 29, 2016
Makefile Default task May 18, 2017
Procfile This should work May 15, 2017 Update Feb 20, 2019
VERSION.go Use channels to avoid race conditions on websocket connection Nov 16, 2018
access_key.go Adds API access concept for access keys Aug 20, 2017
access_key_test.go Adds API access concept for access keys Aug 20, 2017
app.json Heroku origin skip May 17, 2017
config.go Adds basic system info to status API Aug 21, 2017
configure Adds make install Jun 29, 2016
errors.go Better encapsulation Jan 12, 2016
hive.go Adds basic system info to status API Aug 21, 2017
hive_test.go Accept querystring auth May 17, 2017
philote.go Use channels to avoid race conditions on websocket connection Nov 16, 2018
philote_test.go Cleanup May 15, 2017

Philote: plug-and-play websockets server Build status

Philote is a minimal solution to the websockets server problem, it implements Publish/Subscribe and has a simple authentication mechanism that accomodates browser clients securely as well as server-side or desktop applications.

Simplicity is one of the design goals for Philote, ease of deployment is another: you should be able to drop the binary in any internet-accessible server and have it operational.

For a short demonstration, check out the sample command line Philote client called Jane


Philote implements a basic topic-based Publish-subscribe pattern, messages sent over the websocket connection are classified into channels, and each connection is given read/write access to a given list of channels at authentication time.

Messages sent over a connection for a given channel (to which it has write permission) will be received by all other connections (that have read permission to the channel in question).

Deploy your own instance

You can play around with Philote by deploying it on Heroku for free, keep in mind that Heroku's free tier dynos are not suited for production Philote usage, however, as sleeping dynos will mean websocket connections are closed.


Configuration options

Philote takes configuration options from your environment and attempts to provide sensible defaults, these are the environment variables you can set to change its behaviour:

Environment Variable Default Description
SECRET Secret salt used to sign authentication tokens
PORT 6380 Port in which to serve websocket connections
LOGLEVEL info Verbosity of log output, valid options are [debug,info,warning,error,fatal,panic]
MAX_CONNECTIONS 255 Maximum amount of concurrent websocket connections allowed
READ_BUFFER_SIZE 1024 Size of the websocket read buffer, for most cases the default should be okay.
WRITE_BUFFER_SIZE 1024 Size of the websocket write buffer, for most cases the default should be okay.
CHECK_ORIGIN false Check Origin headers during WebSocket upgrade handshake.

If the defaults work for you, simply running philote will start the server with the default values, or you can just manipulate the environment and run with whatever settings you need.

$ PORT=9424 philote


There is a trivial implementation of basic Philote interaction called Jane that you can run locally, it can subscribe to a channel on a Philote server, receive and publish messages. It's useful for debugging purposes.




Clients authenticate in Philote using JSON Web Tokens, which consist on a JSON payload detailing the read/write permissions a given connection will have. The payload is hashed with a secret known to Philote so that incoming connections can be verified, this way you can generate tokens in your application backend and use them from the browser client without fear.

Clients in different language will provide methods to generate these tokens, for now, the Go client should be the reference implementation, although you'll notice that it's an extremely simple one so ports to other languages should be trivial to implement provided with a decent JWT library.

For incoming websockets connections, Philote will look to find the authentication token in the Authorization header, but since the native browser JavaScript WebSocket API does not provide a way to manipulate the request headers Philote will also look for the auth query parameter in case it fails to authenticate using the header option.


You can install Philote (and Jane) easily with homebrew.

brew install pote/philote/philote

brew install pote/philote/jane

You can also manually get the binaries from latest release or install from source

Local development

Bootstrap it

You'll need gpm for dependency management.

Set it up

$ source .env.sample # you might want to copy it to .env and source that instead if you plan on changing the settings.
$ make

Run a Philote server

$ make server

Run the test suite

$ make test

Install from source

$ make install


The first versions of Philote were powered by Redis, it was initially thought of as a websocket bridge to a Redis instance.

After a while, that design was considered inpractical: redis is a big dependency to have, publish/subscribe was easy to implement in Philote itself and the authentication mechanism was changed to use JSON Web Tokens, making Redis unnecessary.

The result should be a more robust tool that anyone can drop in any operating system and get working trivially, without external dependencies.


Released under MIT License, check LICENSE file for details.

You can’t perform that action at this time.