Running the agent

To expose a service with Kokomo you need to run the Kokomo CLI agent as described in the core concepts.

The Kokomo CLI agent

To expose a service with Kokomo you need to run a CLI agent on the same computer (or server) where the service is running. The Kokomo agent is required, and it is the component that estabilishes a bi-directional communication between the Kokomo tunnel that has been provisioned specifically for your service, and the service itself.

Without the Kokomo CLI agent properly running it is not possible to expose a service via Kokomo.

The CLI agent only requires outbound connectivity in order to estabilish a bi-directional communication channel between your computer and the Kokomo tunnel (also called Kokomo infrastructure), and this is the whole point of the agent: to create a reachable ingress even when it is not possible to expose your service directly.

There are a few things that the Kokomo CLI agent does for you:

It provisions the dedicated Kokomo infrastructure so that your service can be exposed, and it configures port mappings and security settings like mutual TLS and IP firewalling.
It keeps a communication channel open between the Kokomo infrastructure and your local service.

While it may seem that the Kokomo CLI agent does a lot (and it does) it is also extremely easy to use.

Running the agent

When you create a Kokomo account and follow the wizard instructions to expose a service, we are already giving you most of the instructions you need to know to run the Kokomo CLI agent so that it's very easy to use and understandable.

The Kokomo CLI agent is available in the following distributions to maximize portability:

MacOS (Apple Silicon): download.
MacOS (x64): download.
Windows: download.
Linux: download

In the following example, we are exposing an api service running on port 8080 using the CLI agent and without any security settings:

$ kokomo \
  --service-name "api" \
  --local-port 8080 \
  --remote-port 8080 \
  --api-key [API KEY]

To authenticate the agent with Kokomo, you need to configure the correct API key.

When you run the CLI agent the first time, Kokomo will receive the request and - if it is the first time you are exposing the service - we will provision the dedicated single-tenant infrastructure to start exposing your service in a reliable and secure way. This operation will take about 60 seconds to complete.

Once running, the infrastructure is ready to accept any subsequent connection from the agent even if it is stopped and restarted. If you re-run the agent with the same configuration arguments - since the infrastruture is already running at this point - a connection is estabilished immediately and there is no need to wait for the infrastructure to be provisioned (because it is already provisioned and running).

The agent arguments can be environment variables

Every argument in the agent can also be configured via an environment variable in the format of KOKOMO_{property}. So for example the name argument can be setup with KOKOMO_NAME, the --api-key argument can be setup with KOKOMO_API_KEY, the --local-port argument with KOKOMO_LOCAL_PORT and so on.

Keeping the agent running

After provisioning the infrastructure, the agent needs to keep running because it is the component that allows for the Kokomo infrastructure to communicate with your service.

The agent only requires an outbound Internet connection to both provision the Kokomo tunnel infrastructure and also make the service available for consumption, but if it is stopped that communication channel drops and your service will be unreachable even if the Kokomo infrastructure is still running.

It is important to run the agent at all times if you want to keep exposing your service, you can run it in background on MacOS and Linux systems by using the following command:

$ nohup kokomo [ARGUMENTS] &

This will keep the command running in the background even if you close the shell.