Open-source project
jumpserver/koko avatar
jumpserver/koko

KoKo: JumpServer's Character-Protocol Connector and What It Actually Handles

KoKo is a connector of JumpServer for secure connections using character protocols, supporting SSH, Telnet, Kubernetes, SFTP and database protocols

540 stars245 forksJavaScriptGPL-3.0

At a glance

What is it?
KoKo is the connector component in JumpServer that handles SSH, Telnet, Kubernetes, SFTP, and database protocols. This review covers how it works, how to run it, and where its limits are.
Who is it for?
Adopt KoKo if you are already running JumpServer and need a single connector for character-based protocols like SSH, Telnet, Kubernetes, SFTP, and databases. Do not adopt it as a standalone SSH gateway, because it depends on JumpServer Core for authentication and session management.
Can I use it commercially?
Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
Is it still maintained?
Yes. The repository last received commits 1 day ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • jumpserver/koko540 ★ · +8
Star history
Repository2026-08-232026-11-15
jumpserver/koko532540

8 Stars in the last 84 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Where KoKo Fits in JumpServer

KoKo is not a standalone product. It is a connector inside JumpServer, an open-source bastion host project. Its job is to handle connections that use character protocols: SSH, Telnet, Kubernetes, SFTP, and database protocols. The README describes it as a connector, which means it sits between the JumpServer Core (the control plane) and the actual target servers. The name comes from a Dota hero, Kunkka, which tells you little about its function but does indicate the project's informal culture. For an engineer evaluating JumpServer, KoKo is the piece that makes terminal sessions possible. Without it, JumpServer would have no way to open a shell on a remote host. The repository is written in Golang and Vue, with the frontend for the web terminal and file management built in Vue. This split is important: the Go binary handles the protocol logic, while the Vue app renders the browser-based interface.

The Protocol Coverage and What It Means in Practice

The feature list in the README is short: SSH, SFTP, Web Terminal, Web File Management. But the description at the top of the README goes further, mentioning Telnet, Kubernetes, and database protocols. That discrepancy is worth noting. The features section may be incomplete, or the description may be aspirational. Either way, the practical implication is that KoKo is not just an SSH proxy. It also handles SFTP for file transfer, which is a common requirement in bastion environments. The web terminal and web file management are the user-facing parts, letting operators access targets from a browser without a local SSH client. The database protocol support is there, but the README does not detail which database engines are supported. If you need a specific database, you will have to check the source or the JumpServer documentation. The reliance on usql for database connections is mentioned in the acknowledgments, which gives a hint that the database support is built on a generic SQL tool, not a custom implementation.

How KoKo Works: The Bootstrap and Core Connection

The configuration example shows the core mechanism. KoKo needs two things to start: a CORE_HOST address and a BOOTSTRAP_TOKEN. The CORE_HOST is the URL of the JumpServer Core service, and the BOOTSTRAP_TOKEN is a shared secret that must match what Core expects. The README says to change it to the same as core. This is a simple authentication handshake. When KoKo starts, it presumably registers itself with Core using that token, then Core can route session requests to it. The config.yml file is central. You create it manually by copying config_example.yml. The dev setup shows a minimal example: CORE_HOST: http://127.0.0.1:8080 and BOOTSTRAP_TOKEN: PleaseChangeMe. That is the entire configuration for a basic setup. The Docker Compose path uses environment variables instead: CORE_HOST, KOKO_SSH_PORT, and KOKO_HTTP_PORT. The default Docker setup points to host.docker.internal:8080, which is a Docker-specific hostname for reaching the host machine. That is a clean way to run KoKo against a Core on the same machine without changing config files.

Building and Running KoKo: The Commands You Need

The README gives a straightforward build process. You clone the repository, run make, and it produces compressed packages for multiple architectures in a build folder. The package name follows the pattern koko-[branch name]-[commit]-linux-amd64.tar.gz. That means the build output is not just a binary; it is a tarball with the binary and probably supporting files. To run it on a Linux amd64 server, you unpack the tarball, create a config.yml, and execute ./koko. The dev environment setup is more involved. You copy config_example.yml to config.yml, edit the CORE_HOST and BOOTSTRAP_TOKEN, then run make run. The current README says make run requires Docker Compose to start guacd; make dev runs KoKo without starting or stopping guacd. The first run downloads prebuilt libghostty-vt and usql binaries. That is a dependency you should be aware of: it is fetched at build or run time, so your build environment needs internet access. For the frontend, you cd into ui, run yarn install, then npm run serve. That assumes you have Node.js and Yarn installed. The Docker route is simpler for testing: docker compose up --build. This builds the image and starts KoKo with the default ports, 2222 for SSH, 5050 for HTTP, and 5001 for the web proxy. Export the bootstrap token used by Core first. You can override those with environment variables.

The Docker Path and Its Defaults

Docker is the fastest way to try KoKo. The README says to use Docker Compose, and it sets sensible defaults. By default, KoKo connects to http://host.docker.internal:8080, which is the host machine's port 8080 from inside a container. That assumes your JumpServer Core is running on the host. The default host ports are 2222 for SSH, 5050 for HTTP and 5001 for the web proxy; KOKO_SSH_PORT, KOKO_HTTP_PORT and KOKO_WEB_PROXY_PORT override them. Set BOOTSTRAP_TOKEN to the value used by Core. The supplied development Compose file runs the container in privileged mode, so review and restrict it before production use. This is a practical setup for local development. However, the README does not mention production Docker deployment specifics, like how to handle secrets or scale multiple KoKo instances. The multi-platform build requires Docker 19.03 or higher with Buildx enabled, which is a standard requirement for cross-architecture images. For a production environment, you would likely run KoKo as a container alongside other JumpServer components, but the README does not give a full compose file for the entire stack. It only covers KoKo in isolation.

Limitations and Failure Modes

KoKo is not a universal remote access tool. It is tightly coupled to JumpServer Core. If you try to run KoKo without a matching Core instance, it will fail to authenticate or will sit idle waiting for instructions. The bootstrap token is a single point of failure: if it does not match Core, KoKo cannot connect. Another limitation is the build process. The make command produces packages for various architectures, but the README only shows a Linux amd64 example. If you need a different platform, you must rely on the make output or Docker, and you have to verify that the architecture is included. The libghostty-vt dependency is downloaded on first use, which means an offline build or run will fail unless you have cached that library. The README does not explain how to vendor that dependency. Also, the feature list is sparse. The description mentions Telnet, Kubernetes, and databases, but the features section only lists SSH, SFTP, Web Terminal, and Web File Management. That gap means you should not assume a protocol is supported until you confirm it in the source or documentation. For a production deployment, this could be a rude surprise if you expect Kubernetes exec sessions and they are not actually implemented.

Alternatives and How They Differ

The main alternative to KoKo is a standalone SSH bastion like Teleport or Apache Guacamole. Teleport is a Go-based access proxy that handles SSH, Kubernetes, and databases, but it is a complete system with its own identity management and audit logging. It does not need a separate core service; it is all-in-one. KoKo, by contrast, is a component that relies on JumpServer Core for authentication and session control. If you want a lightweight SSH gateway without the overhead of JumpServer, Teleport is a more direct fit. Apache Guacamole is another option, but it is a clientless remote desktop gateway that supports SSH and VNC, and it works through a web browser. Its approach is different: it proxies the protocol over HTTP and renders it in a browser, whereas KoKo integrates with JumpServer's web terminal and file management. The key difference is that KoKo is not designed to stand alone. You cannot just download KoKo and use it as your SSH jump host. You need the JumpServer stack. Alternatives give you a complete solution out of the box, but they do not plug into JumpServer's audit and permission model.

Maintenance and Upgrade Considerations

The repository has an active release cadence, with versions like v3.10.23 and v4.10.19 pushed in August 2026. The default branch is dev, which means you should not rely on the dev branch for production. The releases are tagged, so you can pin a version. The license is GPL-3.0, which has implications if you plan to modify and distribute KoKo. You would need to make your changes available under the same license. The build system is make-based, which is standard but requires Go and the frontend toolchain. Upgrading KoKo likely means rebuilding or pulling a new Docker image, then restarting. The README does not document a migration path or upgrade notes, so you will need to test each version yourself. The dependency on usql for database connections is an external project, and its updates could affect KoKo's behavior. If you use database protocols, you should track usql's changes as well. Overall, the maintenance cost is moderate: the project is active, but you must manage the build and configuration yourself. There is no mention of a stable release branch, so you have to choose between dev and tagged releases carefully.

Editorial conclusion

Adopt KoKo if you are already running JumpServer and need a single connector for character-based protocols like SSH, Telnet, Kubernetes, SFTP, and databases. Do not adopt it as a standalone SSH gateway, because it depends on JumpServer Core for authentication and session management. Before deploying, verify that your target architectures are covered by the make build output, and check that the bootstrap token and CORE_HOST configuration match your Core instance. For a simple SSH bastion without the full JumpServer stack, consider a lighter tool like Teleport or Apache Guacamole, but note that KoKo is the only one that natively integrates with JumpServer's web terminal and file management.

Frequently asked questions

What does JumpServer Koko do?

It is the JumpServer connector for secure connections over character protocols, supporting SSH, Telnet, WinRM, Kubernetes, SFTP and database protocols. Its feature list names four items specifically: SSH, SFTP, a web terminal and web file management.

How do I run Koko locally for development?

Copy config_example.yml to config.yml, set CORE_HOST and BOOTSTRAP_TOKEN to match your core, then run `make run`, which needs Docker Compose to start and stop guacd. `make dev` runs Koko without touching guacd and needs no Compose. Prebuilt terminal emulation files and the SQL client are downloaded on first use.

Which ports does Koko expose?

SSH on 2222, HTTP on 5050 and the web proxy on 5001 by default, each overridable with KOKO_SSH_PORT, KOKO_HTTP_PORT and KOKO_WEB_PROXY_PORT. A health check probes the koko health path on port 5050 every ten seconds with ten retries.

How does Koko connect to Windows assets?

Through a persistent PowerShell runspace using PSRP over WinRM with password-based NTLM authentication, on the asset's WinRM listener port. NTLM message encryption is required, HTTPS verifies the certificate by default unless allow_invalid_cert is enabled on the platform, and the feature needs the winrm terminal access migration applied.

What stops an AI agent from running risky PowerShell through Koko?

An AI command matching a notify-and-warn ACL is refused, and approving the AI task does not replace the manual risk confirmation, which has to be done in the terminal. Every mode still runs through PSRP with command auditing, and PSRP reports pipeline state so results cannot invent an exit code.

Is the Koko container privileged by default?

In the shipped compose file, yes: the service sets privileged to true and KOKO_PRIVILEGED defaults to true, with LOG_LEVEL at DEBUG and the web proxy bound to 0.0.0.0. The bootstrap token also defaults to a placeholder string.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/jumpserver-koko.svg)](https://hysenlabs.com/projects/jumpserver-koko)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/jumpserver-koko.svg)](https://hysenlabs.com/projects/jumpserver-koko)

Was this useful?