JumpServer KoKo: the SSH and database connector behind a JumpServer deployment

What KoKo is, and the problem it removes from JumpServer Core

JumpServer splits its access path into separate services, and KoKo is the one that speaks character protocols. The README describes it as "a connector of JumpServer for secure connections using character protocols, supporting SSH, Telnet, Kubernetes, SFTP and database protocols". The listed features are narrower than that sentence: SSH, SFTP, a web terminal and web file management.

The split matters because protocol handling is the part that changes most often. A terminal emulator, a PTY layer, an SFTP implementation and database clients carry different dependencies and different release cadences from the policy engine that decides who may log in. Keeping them in a separate binary means Core can be upgraded without rebuilding the terminal stack, and KoKo can be rebuilt without touching the authorization database.

The audience is therefore narrow and specific. KoKo is for operators running JumpServer who need to control how sessions are terminated, which protocols are exposed, and where session data lands. It is not a product you install on its own. Nothing in the README describes a standalone bastion mode, and the configuration examples all point at a Core instance. If you are shopping for a general-purpose SSH gateway, this is the wrong shelf: KoKo is a component of a larger system, and its value is inseparable from the Core it registers with.

How KoKo terminates a session: services, ports and the Core dependency

The architecture visible in the repository is a set of listeners that register with JumpServer Core. Two configuration keys define the relationship: CORE_HOST, the address of Core, and BOOTSTRAP_TOKEN, a shared secret that must match the value Core holds. The development instructions state this plainly, showing CORE_HOST: http://127.0.0.1:8080 and BOOTSTRAP_TOKEN: PleaseChangeMe with the note to change it to the same value as Core.

Inside the process, go.mod shows what each protocol costs. SSH and SFTP come in through github.com/gliderlabs/ssh and github.com/pkg/sftp. Database sessions depend on github.com/xo/usql, which the README credits in its acknowledgments, and go.mod lists drivers for MySQL, PostgreSQL, SQL Server, Oracle, ClickHouse and MongoDB. Terminal rendering uses github.com/gdamore/tcell/v2 and github.com/rivo/tview, with github.com/creack/pty for PTY allocation and go.mitchellh.com/libghostty for terminal emulation. A web layer built on gin serves the web terminal and file manager, and github.com/gorilla/websocket carries the session stream.

The Docker Compose file shows the runtime shape more clearly than the README does. KoKo is built from the local Dockerfile, runs with privileged: true, and depends on a guacd service (jumpserver/guacd:1.4.0) for graphical protocols. It publishes SSH on 2222, HTTP on 5050, and a web proxy on 5001, and it writes to ./data mounted at /opt/koko/data. A healthcheck polls http://127.0.0.1:5050/koko/health/ every 10 seconds. That health endpoint is the concrete contract between KoKo and any orchestrator you put in front of it, and it is the thing to wire into your monitoring before anything else.

Building KoKo from source and running a first session

The README gives a build path before it gives a run path, which tells you something about the intended audience: this is a component you compile.

git clone https://github.com/jumpserver/koko.git
cd koko
make

The README states that a successful build generates a build folder under the project containing compressed packages for the current branch, named like koko-[branch name]-[commit]-linux-amd64.tar.gz. The Makefile shows that the binary is compiled with CGO_ENABLED=1 and that a cipher key is generated at build time from /dev/urandom and injected through -ldflags, alongside version, commit and build timestamp. That means two builds of the same commit are not byte-identical, and the cipher key is baked into the binary rather than read from configuration.

On a Linux amd64 server, unpack the artifact and create a configuration file from the example.

tar xzvf koko-[branch name]-[commit]-linux-amd64.tar.gz
cd koko-[branch name]-[commit]-linux-amd64
touch config.yml
./koko

The README points at config_example.yml in the repository as the reference. The two values you cannot leave alone are the Core address and the bootstrap token.

CORE_HOST: http://127.0.0.1:8080
BOOTSTRAP_TOKEN: PleaseChangeMe

If you prefer containers, the Makefile exposes a Docker target and the README notes that multi-platform images require Docker 19.03 or higher with the Buildx plugin. For local testing, docker compose up --build starts KoKo against http://host.docker.internal:8080 by default. The README states that CORE_HOST, KOKO_SSH_PORT and KOKO_HTTP_PORT override the defaults, and the Compose file sets HTTPD_PORT to 5050 while mapping the host ports through those variables. Expect the container to fail its healthcheck if Core is unreachable, because registration with Core is what the service does at startup.

The privileged container and the Core version pairing

Two constraints deserve attention before you commit to a deployment.

The Compose service runs with privileged: true and passes KOKO_PRIVILEGED, defaulting to true, into the container. The README does not explain why, and the entrypoint is not shown in the files available, so the reason is not documented in the repository. What is documented is that the setting is there and that it is on by default. If your platform forbids privileged containers, this is a fork in the road you have to resolve before you get to session policy, not after. A Kubernetes cluster with a restrictive pod security policy will reject this manifest as written.

Second, KoKo tracks Core. The recent releases list shows v3.10.23 and v4.10.19 published four days apart in August 2026, which means two maintenance lines are being shipped in parallel. Nothing in the README states the compatibility rule between a KoKo build and a Core version. The bootstrap token handshake is the only visible coupling, and a token that matches does not guarantee that the session API matches. Check the release notes for the line you intend to run and confirm the Core version it pairs with before you upgrade either side independently.

Where KoKo is the wrong choice

KoKo is a poor fit if you want a self-contained SSH gateway. There is no documented mode in which it authenticates users by itself. Every path leads back to CORE_HOST, and without a reachable Core the service has no directory, no authorization decisions and no place to write session records. If Core is down, KoKo is not a degraded bastion, it is a process that cannot register.

It is also the wrong layer if your problem is Windows desktops or VNC. The Compose file pulls in guacd for that, and the README's feature list for KoKo covers SSH, SFTP, a web terminal and web file management. Graphical protocols live behind the guacd dependency, so treating KoKo as the whole remote-access stack misreads the deployment.

Finally, the build story assumes a toolchain. CGO is enabled, the Go version in go.mod is 1.26.8, and the Dockerfile builds from jumpserver/koko-base:20260910_164946, a base image maintained by the project rather than a public golang image. If you cannot build in that environment, you are dependent on released packages. The README does not describe a rollback procedure for a bad KoKo build in a running deployment, so plan that yourself.

How KoKo differs from Teleport and Apache Guacamole

Teleport is the closest comparison in intent and the furthest in architecture. Teleport ships an identity-aware proxy where the certificate authority, the SSH service and the client are one product with a shared trust model; you run one binary and it issues its own credentials. KoKo does no identity work at all. It receives a bootstrap token, registers with JumpServer Core, and Core remains the source of truth for users and permissions. That means KoKo is easier to reason about in isolation and impossible to evaluate in isolation.

Apache Guacamole is a different split. Guacamole's guacd is a protocol translation daemon for graphical sessions, and the Compose file here actually pulls jumpserver/guacd:1.4.0 as a separate service, so the two coexist rather than compete. KoKo owns the character protocols; guacd owns the pixel protocols. If your fleet is mostly Windows, KoKo is the smaller half of your deployment, not the center of it.

Against both, the practical difference is where policy lives. With Teleport, policy is in Teleport. With Guacamole, it is in the Guacamole web application. With KoKo, it is in JumpServer Core, and KoKo's job is to enforce what Core decided and stream what happened back.

Licence and the cost of tracking two release lines

KoKo is licensed under GPL-3.0. That is a copyleft licence, and it applies to the connector you would be running on your bastion hosts. The repository includes a LICENSE file at the top level and the Makefile copies it into every build artifact, so the terms travel with the binary. If you modify KoKo and distribute it, or run a modified version as a network service, the obligations are yours to review with counsel. This is not legal advice and the repository does not describe how the project interprets the licence for network use.

Upgrade cost is driven by the parallel release lines. v3.10.23, v3.10.22 and v4.10.19 are all recent, and the default branch is dev, not a stable branch. The build embeds a cipher key generated at compile time, so a rebuilt binary is a new binary with respect to that value. The README does not state whether a cipher key change invalidates stored session data or active connections. Verify that against the release notes for your line before you replace a running KoKo in place.

Frequently asked questions

The questions below cover the points that come up most often when someone first meets KoKo in a JumpServer deployment. Answers are limited to what the repository and README state.

Editorial conclusion

Adopt KoKo when you already run JumpServer Core and want the character-protocol half of your access path, including SSH on port 2222 and the web proxy on 5050 or 5001, to be a separately built binary you control. Do not adopt it as a standalone SSH bastion: without CORE_HOST and a matching BOOTSTRAP_TOKEN it has no user directory, no policy and no audit trail, and the repository documents no independent mode. Before deploying, verify that your Core version matches the KoKo release line you pick, since v3.10.23 and v4.10.19 are published in parallel, and confirm that the KOKO_PRIVILEGED container setting is acceptable in your environment.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes