Core concepts

Welcome to Kokomo, here we will describe a few core concepts about how it works so that you can fully understand the architecture of exposing a service (or application) via Kokomo.

Architecture

In Kokomo, there are a few important architectural components that it is important to understand, represented in the diagram below:

Your service

With Kokomo you can expose any service (or application) that listens over TCP or HTTP. For example, you can expose the following services via Kokomo:

• Websites
• APIs
• Databases
• Webhook servers
• Websocket servers
• Caches (like Redis)
• And more

Kokomo will support exposing TLS protected services as well, for example if you are exposing an https website or a TLS protected database. Your service will run on a local port that we will need later to configure the Kokomo CLI agent.

For example, if you are exposing Postgres by default the local port will be 5432, but any port number is supported.

Kokomo CLI Agent

The Kokomo CLI agent is a CLI application that you can download on MacOS, Windows and Linux machines that estabilishes the communication between your application running on your computer (or server) and the Kokomo tunnel.

The Kokomo CLI agent is where the magic happens:

1. When starting the agent for the first time, the agent will communicate with Kokomo to provision your Kokomo tunnel on dedicated infrastructure so that your service can be securely exposed. The provisioning process typically takes 1 minute.
2. It will then estabilish a bi-directional communication with the Kokomo infrastructure that has been provisioned just for your service, by only relying on outbound connectivity from your computer (or server). This means that Kokomo will work on machines that have no inbound connectivity, but have outbound Internet connectivity.
3. If you stop and restart the agent, it will reconnect to the already provisioned infrastructure seamlessly in just a couple of seconds.

The agent needs to be running at all times for your service to be accessible via Kokomo. Shutting down the service, will interrupt the connection.

Because the agent is a CLI application, it can also be easily integrated in CI/CD workflows and automated.

Kokomo Tunnel

The Kokomo tunnel is specifically created for every service that you are exposing via Kokomo. Even if you are exposing two different services from the same computer, Kokomo will still provision two entirely segregated and compartimentalized environments for each service.

The tunnel also runs on single-tenant infrastructure that is not shared with any other customer, or any other service.

When you run the Kokomo Agent CLI, we will provision from scratch your Kokomo tunnel infrastruture so that traffic from other clients can be properly proxied to the service on the computer that you are exposing. After the infrastructure is provisioned, you will get access to a static IP address and a public DNS, that you can use to start using your service via Kokomo.

The Kokomo tunnel can be further protected with mutual TLS and a built-in IP firewall, and it also offers the ability to map the local port where you service is running with a different remote port on Kokomo.

Client

Finally, this last part of the architecture refers to the client that will access your service via Kokomo. This can be any client, like a browser, a mobile device, another application and so on.

The client will access Kokomo Tunnel via the public Internet, we will validate the IP address and the mTLS certificate (if mTLS protection is enabled on Kokomo), then we will securely proxy the request to your local Kokomo agent (via the bi-directional communication channel estabilished by the agent) which in turn will forward the request to the local service running at the port that you have specified.

When your local application returns a response, it will be returned all the way back to the client, as if Kokomo was never there.