shellcn

module
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2026 License: GPL-3.0

README

ShellCN logo

ShellCN

One self-hosted gateway for everything you log into.

CI

ShellCN is a single Go binary that gives you one secure, audited place to reach all your servers, containers, databases, and desktops. Run it, open a browser, and you're in.

It ships with 20 built-in protocols. Add more via plugins or Marketplace:

  • Shells: SSH
  • File transfer: SFTP, FTP/FTPS, SMB, WebDAV, S3
  • Containers & clusters: Docker, Swarm, Podman, Kubernetes, Proxmox
  • Remote desktops: VNC, RDP
  • Databases: PostgreSQL, MySQL, MongoDB, Redis
  • Observability: server monitoring
  • Directory: LDAP

Quick start

Each needs a master key (it encrypts stored credentials) and a first admin login, then open http://localhost:8081 and sign in. Reuse the same master key on restart, or stored credentials can't be decrypted.

Docker, one command

Data and session recordings live in /data, so mount a volume there.

docker run -d --name shellcn -p 8081:8081 \
  -v shellcn-data:/data \
  -e SHELLCN_MASTER_KEY="$(openssl rand -base64 32)" \
  -e SHELLCN_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e SHELLCN_BOOTSTRAP_ADMIN_PASSWORD=change-me \
  ghcr.io/charlesng35/shellcn:latest

Docker Compose

Save this as docker-compose.yml:

services:
  shellcn:
    image: ghcr.io/charlesng35/shellcn:latest
    ports:
      - "8081:8081"
    environment:
      SHELLCN_MASTER_KEY: ${SHELLCN_MASTER_KEY}
      SHELLCN_BOOTSTRAP_ADMIN_USERNAME: admin
      SHELLCN_BOOTSTRAP_ADMIN_PASSWORD: change-me
    volumes:
      - shellcn-data:/data
    restart: unless-stopped

volumes:
  shellcn-data:

Generate a key once with openssl rand -base64 32, put it in a .env file beside the compose file as SHELLCN_MASTER_KEY=..., then run docker compose up -d.

The /data volume also persists private plugins placed in /data/plugins.d.

Single binary

Grab the build for your platform from the releases page, then run it with the same three settings:

export SHELLCN_MASTER_KEY="$(openssl rand -base64 32)"
export SHELLCN_BOOTSTRAP_ADMIN_USERNAME=admin
export SHELLCN_BOOTSTRAP_ADMIN_PASSWORD=change-me
./shellcn

It serves on :8081 and keeps its data in the working directory.

For the full configuration surface, see config.example.yaml or .env.sample.

Early days. ShellCN is in active development, so expect a few rough edges. Take it for a spin and tell us what breaks. Issues, feedback, and contributions are very welcome.

Extending it

ShellCN keeps the built-in protocol set small. Extra protocols are external plugins:

  • Install ShellCN-maintained plugins from the Marketplace.
  • Build your own with the plugin starter.
  • To publish a plugin, release its binary and submit a manifest to shellcn-plugin-registry.
  • For private plugins, skip the registry and drop the binary in the gateway plugin directory.

The default plugin directory is /data/plugins.d in Docker and ./plugins.d when running the single binary. You can override it with plugins.dir or SHELLCN_PLUGINS_DIR.

Build from source

Requires Go 1.26+ and Node 24+.

make build    # single binary at bin/shellcn
make dev      # live-reloading dev server

Screenshots

ShellCN Kubernetes cluster overview shellcn-mongo-documents-tab.png

Features

  • One audited cockpit for shells, files, containers, clusters, databases, and desktops.
  • AI assistant for supported operations workflows.
  • Session recording for terminal and desktop sessions.
  • Plugin extension model for private protocols and Marketplace-installed plugins.
  • Agent transport for targets that cannot be reached directly from the gateway.
  • Role-based access control with per-route permissions, risk levels, and audit events.

Upcoming

  • OAuth2 / OIDC login
  • SAML login
  • LDAP authentication

ShellCN is developed across a small family of repos we maintain:

Repository What it is
shellcn The gateway: core, SDK, and the built-in protocol set.
shellcn-plugin-registry The plugin registry that powers the in-app Marketplace.
shellcn-contrib ShellCN-maintained external plugins, installable from the Marketplace.
shellcn-plugin-starter Template + docs for writing your own plugin.

License

GPL-3.0

Directories

Path Synopsis
cmd
agent command
Command agent is shellcn-agent: a plugin-agnostic reverse-tunnel proxy run inside a private target.
 Command agent is shellcn-agent: a plugin-agnostic reverse-tunnel proxy run inside a private target.
server command
Command server is the ShellCN gateway entrypoint.
 Command server is the ShellCN gateway entrypoint.
internal
ai
Package ai coordinates provider resolution, route tools, memory, and streaming turns.
 Package ai coordinates provider resolution, route tools, memory, and streaming turns.
ai/agent
Package agent builds the system prompt and relays a provider turn to the transport, buffering text deltas so the UI receives smooth, batched updates instead of a flood of tiny frames.
 Package agent builds the system prompt and relays a provider turn to the transport, buffering text deltas so the UI receives smooth, batched updates instead of a flood of tiny frames.
ai/budget
Package budget computes a turn's token budgeting.
 Package budget computes a turn's token budgeting.
ai/config
Package aiconfig manages shared and user-scoped AI provider configuration.
 Package aiconfig manages shared and user-scoped AI provider configuration.
ai/engine
Package engine defines the framework-agnostic AI provider interfaces.
 Package engine defines the framework-agnostic AI provider interfaces.
ai/engine/eino
Package eino is the only package that imports cloudwego/eino; it adapts the framework to the engine.Provider seam with an explicit tool-calling loop so each tool call flows through the risk-gated executor.
 Package eino is the only package that imports cloudwego/eino; it adapts the framework to the engine.Provider seam with an explicit tool-calling loop so each tool call flows through the risk-gated executor.
ai/memory
Package memory persists AI conversations and assembles context windows.
 Package memory persists AI conversations and assembles context windows.
ai/modelreg
Package modelreg resolves model token limits from live registries, provider catalogues, static metadata, and finally a safe default.
 Package modelreg resolves model token limits from live registries, provider catalogues, static metadata, and finally a safe default.
ai/tools
Package tools exposes risk-gated connection routes as agent tools.
 Package tools exposes risk-gated connection routes as agent tools.
app
Package app centralizes ShellCN product identifiers and published artifact names used across the backend.
 Package app centralizes ShellCN product identifiers and published artifact names used across the backend.
audit
Package audit records an append-only log of every authorized (and denied) operation.
 Package audit records an append-only log of every authorized (and denied) operation.
auth
Package auth handles authentication and session tickets.
 Package auth handles authentication and session tickets.
config
Package config loads bootstrap settings (needed before the database opens) from a YAML file overlaid by SHELLCN_* environment variables.
 Package config loads bootstrap settings (needed before the database opens) from a YAML file overlaid by SHELLCN_* environment variables.
email
Package email sends transactional mail (account invitations) over SMTP, using configuration loaded at startup.
 Package email sends transactional mail (account invitations) over SMTP, using configuration loaded at startup.
extplugin
Package extplugin adapts an out-of-process plugin subprocess to plugin.Plugin so the registry, projection, and route wrapper treat it like a built-in.
 Package extplugin adapts an out-of-process plugin subprocess to plugin.Plugin so the registry, projection, and route wrapper treat it like a built-in.
livelease
Package livelease defines platform-neutral lease primitives for live gateway state that must remain in process memory.
 Package livelease defines platform-neutral lease primitives for live gateway state that must remain in process memory.
models
Package models holds the core entity types shared across ShellCN.
 Package models holds the core entity types shared across ShellCN.
pluginmarket
Package pluginmarket fetches the plugin registry index and installs verified binaries: the indexed sha256 is the trust root for every download.
 Package pluginmarket fetches the plugin registry index and installs verified binaries: the indexed sha256 is the trust root for every download.
pluginregistry
Package pluginregistry owns the gateway runtime registry for built-in and external plugin instances.
 Package pluginregistry owns the gateway runtime registry for built-in and external plugin instances.
policy
Package policy enforces authorization and action risk.
 Package policy enforces authorization and action risk.
recording
Package recording owns session-recording capture and storage.
 Package recording owns session-recording capture and storage.
secrets
Package secrets provides the encrypted secret vault.
 Package secrets provides the encrypted secret vault.
server
Package server is the HTTP/WS adapter for APIs, plugin routes, and the UI.
 Package server is the HTTP/WS adapter for APIs, plugin routes, and the UI.
service
Package service holds the application business logic.
 Package service holds the application business logic.
session
Package session manages live sessions and their channels.
 Package session manages live sessions and their channels.
store
Package store provides the persistence repositories.
 Package store provides the persistence repositories.
telemetry
Package telemetry provides structured logging, Prometheus metrics, and health checks so the gateway itself is observable from day one.
 Package telemetry provides structured logging, Prometheus metrics, and health checks so the gateway itself is observable from day one.
transport
Package transport provides the direct and agent network dialers.
 Package transport provides the direct and agent network dialers.
version
Package version reports the running build version and checks GitHub for a newer release.
 Package version reports the running build version and checks GitHub for a newer release.
Package plugins is the home for first-party protocol plugins.
 Package plugins is the home for first-party protocol plugins.
docker
Package docker implements the Docker Engine protocol plugin.
 Package docker implements the Docker Engine protocol plugin.
ftp
Package ftp implements the FTP filesystem plugin.
 Package ftp implements the FTP filesystem plugin.
ftps
Package ftps implements the FTP over TLS filesystem plugin.
 Package ftps implements the FTP over TLS filesystem plugin.
kubernetes
Package kubernetes implements the Kubernetes protocol plugin: a Lens-grade operations cockpit rendered entirely from the manifest projection over the generic renderer.
 Package kubernetes implements the Kubernetes protocol plugin: a Lens-grade operations cockpit rendered entirely from the manifest projection over the generic renderer.
ldap
Package ldap implements the LDAP directory protocol plugin.
 Package ldap implements the LDAP directory protocol plugin.
mongodb
Package mongodb implements the MongoDB protocol plugin.
 Package mongodb implements the MongoDB protocol plugin.
mysql
Package mysql implements the MySQL/MariaDB protocol plugin.
 Package mysql implements the MySQL/MariaDB protocol plugin.
podman
Package podman implements the Podman plugin.
 Package podman implements the Podman plugin.
postgresql
Package postgresql implements the PostgreSQL protocol plugin.
 Package postgresql implements the PostgreSQL protocol plugin.
proxmox
Package proxmox implements the Proxmox VE protocol plugin: a deep node → guests/storage tree, VM/LXC/node detail views, live metrics, noVNC and xterm consoles, snapshots, backups, and lifecycle actions — all over the PVE REST API (with the console websocket bridged through the gateway transport).
 Package proxmox implements the Proxmox VE protocol plugin: a deep node → guests/storage tree, VM/LXC/node detail views, live metrics, noVNC and xterm consoles, snapshots, backups, and lifecycle actions — all over the PVE REST API (with the console websocket bridged through the gateway transport).
rdp
Package rdp implements the RDP remote-desktop plugin.
 Package rdp implements the RDP remote-desktop plugin.
redis
Package redis implements the Redis protocol plugin.
 Package redis implements the Redis protocol plugin.
s3
Package s3 implements the Amazon S3 filesystem plugin.
 Package s3 implements the Amazon S3 filesystem plugin.
servermonitor
Package servermonitor implements a host monitoring plugin.
 Package servermonitor implements a host monitoring plugin.
sftp
Package sftp implements the file-only SFTP protocol plugin.
 Package sftp implements the file-only SFTP protocol plugin.
shared/broker
Package broker contains small helpers shared by message-broker plugins.
 Package broker contains small helpers shared by message-broker plugins.
shared/dbcred
Package dbcred contains reusable credential handling for database plugins.
 Package dbcred contains reusable credential handling for database plugins.
shared/dockerengine
Package dockerengine is the shared runtime for Docker-API protocols.
 Package dockerengine is the shared runtime for Docker-API protocols.
shared/filesystem
Package filesystem contains shared manifest and route helpers for file browser plugins backed by different remote filesystem protocols.
 Package filesystem contains shared manifest and route helpers for file browser plugins backed by different remote filesystem protocols.
shared/ftpfs
Package ftpfs adapts github.com/jlaffaye/ftp to ShellCN's shared file browser.
 Package ftpfs adapts github.com/jlaffaye/ftp to ShellCN's shared file browser.
shared/hostmonitor
Package hostmonitor collects operating-system inventory and metrics for the server monitor plugin and the agent's remote host-monitor mode.
 Package hostmonitor collects operating-system inventory and metrics for the server monitor plugin and the agent's remote host-monitor mode.
shared/loopback
Package loopback fronts an agent tunnel as a local TCP endpoint.
 Package loopback fronts an agent tunnel as a local TCP endpoint.
shared/rfb
Package rfb implements the minimal RFB (VNC) protocol pieces ShellCN needs: a gateway-side handshake toward the browser using Security None (shared by the VNC and RDP plugins) plus upstream VNC authentication.
 Package rfb implements the minimal RFB (VNC) protocol pieces ShellCN needs: a gateway-side handshake toward the browser using Security None (shared by the VNC and RDP plugins) plus upstream VNC authentication.
shared/s3compat
Package s3compat adapts S3-compatible object storage to ShellCN's shared file browser contract.
 Package s3compat adapts S3-compatible object storage to ShellCN's shared file browser contract.
shared/sqldb
Package sqldb contains SQL plugin helpers that are independent of a specific database driver.
 Package sqldb contains SQL plugin helpers that are independent of a specific database driver.
shared/sshsftp
Package sshsftp contains the shared SSH session and SFTP route implementation.
 Package sshsftp contains the shared SSH session and SFTP route implementation.
shared/termshell
Package termshell builds the command for an interactive container/pod shell.
 Package termshell builds the command for an interactive container/pod shell.
smb
Package smb implements the SMB filesystem plugin.
 Package smb implements the SMB filesystem plugin.
ssh
Package ssh implements the full SSH protocol plugin.
 Package ssh implements the full SSH protocol plugin.
swarm
Package swarm implements the Docker Swarm orchestration plugin.
 Package swarm implements the Docker Swarm orchestration plugin.
vnc
Package vnc implements the VNC remote-desktop plugin.
 Package vnc implements the VNC remote-desktop plugin.
webdav
Package webdav implements the WebDAV filesystem plugin.
 Package webdav implements the WebDAV filesystem plugin.
sdk module
Package web embeds the built frontend assets and serves them from the binary.
 Package web embeds the built frontend assets and serves them from the binary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.