Proteus Quickstart


Netifi Proteus is a next generation microservices platform that combines the functionality of an API Gateway and a Service Mesh. Unlike legacy API Gateways and Meshes, Proteus is completely async, reactive, and supports streaming. Proteus has two main components – the Proteus client, and the Proteus Router. The Proteus Router routes requests between clients either directly or via other Routers. Routers discover other routers using the SWIM protocol. This allows Routers to scale horizontally to very large clusters. The Proteus Client connects to the Router. Discovery is handled through a seed node, and then information about the different Router nodes are sent to the client. When a client connects to the router it provides a destination and group. The destination is unique to each connection to the router and used to route requests point-to-point. The group is used to route messages to a group of destinations.


You need the following items installed on your machine to run the quickstart:

Get Started

Follow the steps below to get up and running with Proteus quickly.

  1. Clone Quickstart Project

    Clone the Java Quickstart project from Github.

    git clone
  2. Build the Project

    After you have cloned the project change to the proteus-quickstart directory and build the project:

    cd proteus-quickstart
    ./gradlew build
  3. Download the Router

    Once the project is built you need to download the Proteus Router. The router is distributed as a Docker container on Docker Hub. To download the Proteus Router Docker image run the following command in a new terminal window:

    docker pull netifi/proteus
  4. Start the Router

    Now that you have downloaded the router from Docker Hub, start it by running the following command:

    docker run -p 8001:8001 -p 7001:7001 -e ROUTER_SERVER_OPTS='-Dnetifi.authentication.0.accessKey=7685465987873703191 -Dnetifi.authentication.0.accessToken=PYYgV9XHSJ/3KqgK5wYjz+73MeA= -Dnetifi.authentication.0.accountId=100' netifi/proteus
  5. Start the Example Service

    Back in the proteus-quickstart directory start up the service by running the following command:

    ./gradlew :service:run

    This will startup a simple service that connects to the router.

  6. Run the Example Client

    Open another terminal window and go the proteus-quickstart directory. This time instead of starting the service, use a client to send a message. This can be done by running the following command:

    ./gradlew :client:run

    The client will startup, connect to the router, and send a message to the service.

    The following is approximately the expected output from the client:

    $ ./gradlew :client:run
    i.n.s.Netifi [main] registering with netifi with account id 100, group quickstart.clients, and destination client1
    i.n.p.q.c.Main [main] Sending 'World' to HelloService...
    i.n.p.q.c.Main [main] message: "Hello, World! from helloservice-2782cbee-1bcd-49c9-991c-fbb88c8e26d7"

    The service logs should show that it has received the message:

    i.n.p.q.s.DefaultHelloService [reactor-tcp-nio-4] received a message -> World

    And the router should show something akin to this:

    i.n.r.a.RouterSocketAcceptor [reactor-tcp-nio-4] -4687034539111874558 - adding destination helloservice-2782cbee-1bcd-49c9-991c-fbb88c8e26d7 to group
    i.n.r.a.RouterSocketAcceptor [reactor-tcp-nio-1] -2050621438 - adding destination client1 to group 100:quickstart.clients
    i.n.r.b.RemoteLoadBalancedRSocket [reactor-tcp-nio-1] -2050621436 - creating load balancer for group
    i.n.r.a.RouterSocketAcceptor [reactor-tcp-nio-1] -2050621438 - removing destination client1 from destination map
    i.n.r.a.RouterSocketAcceptor [reactor-tcp-nio-1] -2050621438 - removing destination client1 from group 100:quickstart.clients
    i.n.r.a.RouterSocketAcceptor [reactor-tcp-nio-1] -2050621438 - removing destination client1 from group quickstart.clients load balancer


Now that you have a service, client, and router successfully running. See if you can implement a ping-pong service whereby the client repeatedly pings the service, and the service always replies with a pong.

An example implementation is in the ping-pong-solution branch.


Proteus outperforms all other RPC and service mesh offerings.

Read Our Blog