# jumpserver/koko architecture

> Architecture diagram of the GitHub repository jumpserver/koko, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jumpserver/koko
- Repository: https://github.com/jumpserver/koko

## Overview

KoKo is JumpServer’s secure connector for interactive access to SSH, Telnet, WinRM, Kubernetes, SFTP, and database assets, with web terminal and file-management capabilities. A principal workflow is a user authenticating and selecting an asset, then entering a protocol-aware session that connects to the target and carries terminal or file activity. WebSocket and Guacamole paths support web sessions, while a separate authenticated web proxy carries HTTP and CONNECT traffic. The graph emphasizes documented and indexed relationships; unsampled subsystems are represented only where the README establishes the capability, without asserting internal wiring.

Main entry points: [`pkg/proxy/server.go`](https://github.com/jumpserver/koko/blob/dev/pkg/proxy/server.go) (Protocol proxy), [`pkg/auth/user_auth.go`](https://github.com/jumpserver/koko/blob/dev/pkg/auth/user_auth.go) (User authentication), [`pkg/srvconn/connmanager.go`](https://github.com/jumpserver/koko/blob/dev/pkg/srvconn/connmanager.go) (Target connections), [`pkg/handler/select_handler.go`](https://github.com/jumpserver/koko/blob/dev/pkg/handler/select_handler.go) (Asset selection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access and authentication"]
  node_auth["User authentication<br/>[user_auth.go]"]
  node_asset_selection["Asset selection<br/>[select_handler.go]"]
  node_direct_access["Direct access handler<br/>[direct_handler.go]"]
  node_ssh_listener["SSH listener<br/>[server.go]"]
end

subgraph group_sessions["Session transport"]
  node_exchange["Session exchange<br/>[redis.go]"]
  node_session_registry["Session registry<br/>[manager.go]"]
  node_lion_session["Guacamole sessions<br/>[server.go]"]
  node_lion_tunnel["Guacamole tunnel<br/>[server.go]"]
end

subgraph group_targets["Target connections"]
  node_protocol_proxy["Protocol proxy<br/>[server.go]"]
  node_database_proxy["Database proxy<br/>[server_database.go]"]
  node_server_connections["Target connections<br/>[connmanager.go]"]
  node_ssh_clients["SSH client pool<br/>[sshclients.go]"]
end

subgraph group_web["Web experiences"]
  node_http_router["HTTP router<br/>[webrouter.go]"]
  node_web_client["Web session client<br/>[client.go]"]
  node_web_terminal_tools["Terminal tools"]
  node_web_proxy["HTTP web proxy<br/>[server.go]"]
end

subgraph group_operations["Session operations"]
  node_koko_tasks["Background tasks<br/>[task.go]"]
  node_winrm_tools["WinRM AI tools<br/>[protocol.go]"]
  node_zmodem["ZMODEM transfer<br/>[zsession.go]"]
end

node_user(("JumpServer user"))
node_target_asset(("Managed asset"))
node_core(("JumpServer Core"))
node_redis[("Redis")]
node_web_user(("Web client"))

node_user -->|"authenticates"| node_auth
node_user -.->|"selects asset"| node_asset_selection
node_asset_selection -->|"loads assets"| node_server_connections
node_asset_selection -.->|"starts access"| node_protocol_proxy
node_ssh_listener -->|"dispatches sessions"| node_direct_access
node_direct_access -->|"creates proxy"| node_protocol_proxy
node_direct_access -->|"sets connection options"| node_server_connections
node_protocol_proxy -->|"opens target connection"| node_server_connections
node_protocol_proxy -->|"delegates database"| node_database_proxy
node_protocol_proxy -->|"reuses SSH client"| node_ssh_clients
node_target_asset -.->|"serves protocol"| node_server_connections
node_http_router -->|"authenticates requests"| node_auth
node_http_router -.->|"routes terminal WebSocket"| node_web_client
node_web_client -->|"exchanges messages"| node_exchange
node_web_client -->|"uses session tools"| node_web_terminal_tools
node_web_terminal_tools -->|"invokes session proxy"| node_protocol_proxy
node_exchange -->|"stores exchange state"| node_redis
node_koko_tasks -->|"uses proxy"| node_protocol_proxy
node_koko_tasks -->|"uses session service"| node_lion_session
node_lion_session -->|"serves tunneled sessions"| node_lion_tunnel
node_lion_tunnel -->|"joins share room"| node_auth
node_lion_tunnel -->|"records file activity"| node_protocol_proxy
node_web_user -->|"sends HTTP or CONNECT"| node_web_proxy
node_web_proxy -->|"forwards traffic"| node_target_asset
node_protocol_proxy -.->|"exposes AI commands"| node_winrm_tools
node_protocol_proxy -->|"supports file transfer"| node_zmodem
node_core -.->|"provides identity"| node_auth
node_core -.->|"provides session services"| node_lion_session

click node_auth "https://github.com/jumpserver/koko/blob/dev/pkg/auth/user_auth.go"
click node_asset_selection "https://github.com/jumpserver/koko/blob/dev/pkg/handler/select_handler.go"
click node_direct_access "https://github.com/jumpserver/koko/blob/dev/pkg/handler/direct_handler.go"
click node_ssh_listener "https://github.com/jumpserver/koko/blob/dev/pkg/sshd/server.go"
click node_http_router "https://github.com/jumpserver/koko/blob/dev/pkg/httpd/webrouter.go"
click node_web_client "https://github.com/jumpserver/koko/blob/dev/pkg/httpd/client.go"
click node_web_terminal_tools "https://github.com/jumpserver/koko/blob/dev/pkg/httpd/terminal_sessiontools.go"
click node_exchange "https://github.com/jumpserver/koko/blob/dev/pkg/exchange/redis.go"
click node_session_registry "https://github.com/jumpserver/koko/blob/dev/pkg/session/manager.go"
click node_protocol_proxy "https://github.com/jumpserver/koko/blob/dev/pkg/proxy/server.go"
click node_database_proxy "https://github.com/jumpserver/koko/blob/dev/pkg/proxy/server_database.go"
click node_server_connections "https://github.com/jumpserver/koko/blob/dev/pkg/srvconn/connmanager.go"
click node_ssh_clients "https://github.com/jumpserver/koko/blob/dev/pkg/srvconn/sshclients.go"
click node_lion_session "https://github.com/jumpserver/koko/blob/dev/pkg/lion/session/server.go"
click node_lion_tunnel "https://github.com/jumpserver/koko/blob/dev/pkg/lion/tunnel/server.go"
click node_koko_tasks "https://github.com/jumpserver/koko/blob/dev/pkg/koko/task.go"
click node_web_proxy "https://github.com/jumpserver/koko/blob/dev/pkg/webproxy/server.go"
click node_winrm_tools "https://github.com/jumpserver/koko/blob/dev/internal/sessiontools/protocol.go"
click node_zmodem "https://github.com/jumpserver/koko/blob/dev/pkg/zmodem/zsession.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_asset_selection,node_direct_access,node_ssh_listener,node_user,node_web_user toneBlue
class node_exchange,node_session_registry,node_lion_session,node_lion_tunnel,node_redis toneAmber
class node_protocol_proxy,node_database_proxy,node_server_connections,node_ssh_clients,node_core toneMint
class node_http_router,node_web_client,node_web_terminal_tools,node_web_proxy toneRose
class node_koko_tasks,node_winrm_tools,node_zmodem,node_target_asset toneIndigo
```

## Components

### Access and authentication

- [User authentication](https://github.com/jumpserver/koko/blob/dev/pkg/auth/user_auth.go): `pkg/auth/user_auth.go`
- [Asset selection](https://github.com/jumpserver/koko/blob/dev/pkg/handler/select_handler.go): `pkg/handler/select_handler.go`
- [Direct access handler](https://github.com/jumpserver/koko/blob/dev/pkg/handler/direct_handler.go): `pkg/handler/direct_handler.go`
- [SSH listener](https://github.com/jumpserver/koko/blob/dev/pkg/sshd/server.go): `pkg/sshd/server.go`

### Session transport

- [Session exchange](https://github.com/jumpserver/koko/blob/dev/pkg/exchange/redis.go): `pkg/exchange/redis.go`
- [Session registry](https://github.com/jumpserver/koko/blob/dev/pkg/session/manager.go): `pkg/session/manager.go`
- [Guacamole sessions](https://github.com/jumpserver/koko/blob/dev/pkg/lion/session/server.go): `pkg/lion/session/server.go`
- [Guacamole tunnel](https://github.com/jumpserver/koko/blob/dev/pkg/lion/tunnel/server.go): `pkg/lion/tunnel/server.go`

### Target connections

- [Protocol proxy](https://github.com/jumpserver/koko/blob/dev/pkg/proxy/server.go): `pkg/proxy/server.go`
- [Database proxy](https://github.com/jumpserver/koko/blob/dev/pkg/proxy/server_database.go): `pkg/proxy/server_database.go`
- [Target connections](https://github.com/jumpserver/koko/blob/dev/pkg/srvconn/connmanager.go): `pkg/srvconn/connmanager.go`
- [SSH client pool](https://github.com/jumpserver/koko/blob/dev/pkg/srvconn/sshclients.go): `pkg/srvconn/sshclients.go`

### Web experiences

- [HTTP router](https://github.com/jumpserver/koko/blob/dev/pkg/httpd/webrouter.go): `pkg/httpd/webrouter.go`
- [Web session client](https://github.com/jumpserver/koko/blob/dev/pkg/httpd/client.go): `pkg/httpd/client.go`
- [Terminal tools](https://github.com/jumpserver/koko/blob/dev/pkg/httpd/terminal_sessiontools.go): `pkg/httpd/terminal_sessiontools.go`
- [HTTP web proxy](https://github.com/jumpserver/koko/blob/dev/pkg/webproxy/server.go): `pkg/webproxy/server.go`

### Session operations

- [Background tasks](https://github.com/jumpserver/koko/blob/dev/pkg/koko/task.go): `pkg/koko/task.go`
- [WinRM AI tools](https://github.com/jumpserver/koko/blob/dev/internal/sessiontools/protocol.go): `internal/sessiontools/protocol.go`
- [ZMODEM transfer](https://github.com/jumpserver/koko/blob/dev/pkg/zmodem/zsession.go): `pkg/zmodem/zsession.go`

### Other components

- **JumpServer user**
- **Managed asset**
- **JumpServer Core**
- **Redis**
- **Web client**

## Connections

- JumpServer user → User authentication: authenticates (evidence: `pkg/auth/user_auth.go`)
- JumpServer user → Asset selection: selects asset
- Asset selection → Target connections: loads assets (evidence: `pkg/handler/select_handler.go`)
- Asset selection → Protocol proxy: starts access
- SSH listener → Direct access handler: dispatches sessions (evidence: `pkg/sshd/server.go`)
- Direct access handler → Protocol proxy: creates proxy (evidence: `pkg/handler/direct_handler.go`)
- Direct access handler → Target connections: sets connection options (evidence: `pkg/handler/direct_handler.go`)
- Protocol proxy → Target connections: opens target connection (evidence: `pkg/proxy/server.go`)
- Protocol proxy → Database proxy: delegates database (evidence: `pkg/proxy/server.go`)
- Protocol proxy → SSH client pool: reuses SSH client (evidence: `pkg/proxy/server.go`)
- Managed asset → Target connections: serves protocol
- HTTP router → User authentication: authenticates requests (evidence: `pkg/httpd/webrouter.go`)
- HTTP router → Web session client: routes terminal WebSocket
- Web session client → Session exchange: exchanges messages (evidence: `pkg/httpd/client.go`)
- Web session client → Terminal tools: uses session tools (evidence: `pkg/httpd/terminal_sessiontools.go`)
- Terminal tools → Protocol proxy: invokes session proxy (evidence: `pkg/httpd/terminal_sessiontools.go`)
- Session exchange → Redis: stores exchange state (evidence: `pkg/exchange/redis.go`)
- Background tasks → Protocol proxy: uses proxy (evidence: `pkg/koko/task.go`)
- Background tasks → Guacamole sessions: uses session service (evidence: `pkg/koko/task.go`)
- Guacamole sessions → Guacamole tunnel: serves tunneled sessions (evidence: `pkg/lion/tunnel/server.go`)
- Guacamole tunnel → User authentication: joins share room (evidence: `pkg/lion/tunnel/server.go`)
- Guacamole tunnel → Protocol proxy: records file activity (evidence: `pkg/lion/tunnel/server.go`)
- Web client → HTTP web proxy: sends HTTP or CONNECT (evidence: `pkg/webproxy/server.go`)
- HTTP web proxy → Managed asset: forwards traffic (evidence: `pkg/webproxy/server.go`)
- Protocol proxy → WinRM AI tools: exposes AI commands
- Protocol proxy → ZMODEM transfer: supports file transfer (evidence: `pkg/proxy/server.go`)
- JumpServer Core → User authentication: provides identity
- JumpServer Core → Guacamole sessions: provides session services
