How l0n3m4n/github-vps works
1. This repository is not an application codebase; it is an operational guide for turning GitHub Codespaces into a temporary “VPS-like” environment, mainly for Kali Linux, pentesting, and CTF work.
2. The top-level readme.md is the primary source of truth. It describes the workflow, prerequisites, and command sequences for launching Docker-based Kali sessions inside a Codespace, then extending access with SSH, noVNC, or GitHub CLI.
3. The only other structured content is under assets/, which contains screenshots and a nested assets/installation_guide/readme.md. These are supporting documentation artifacts, not runtime components. The tets.md file appears to be an auxiliary/placeholder document.
4. The main runtime boundary is:
- GitHub Codespaces host environment on one side
- Dockerized Kali Linux container on the other
The repo’s core architecture is about bridging those two layers with Docker commands and container lifecycle management.
5. The Docker/Kali subsystem is the central execution environment. The documented flow is: pull kalilinux/kali-rolling, run it interactively or in privileged mode, then optionally install Kali metapackages such as kali-linux-default or kali-linux-headless depending on GUI needs.
6. A second subsystem covers privilege and network-device access. The guide explicitly calls out --privileged or --device=/dev/net/tun to support OpenVPN/TUN use cases. This is an important architectural constraint because some penetration-testing tools require host device passthrough that normal containers do not have.
7. A third subsystem is terminal-session automation. The embedded kali_privs.sh script is a convenience wrapper that finds a Kali container, starts it if needed, and opens an interactive shell via docker exec. This script sits at the user-automation boundary rather than inside the container itself.
8. The GUI access path is a separate subsystem built on VNC:
- setup-noVNC.sh installs XFCE, TightVNC, noVNC, and supporting packages
- it generates a self-signed certificate
- it configures VNC startup
- start-novnc.sh launches websockify and forwards the VNC server to a browser-accessible port
This creates a browser-based desktop channel into the Codespace.
9. The SSH-over-tunnel path is another independent access layer:
- SSH is enabled inside the Codespace
- an RSA key pair and authorized_keys are configured
- ngrok exposes local port 22 to the public internet over a TCP tunnel
This flow is for remote terminal access when direct Codespace access is inconvenient.
10. GitHub CLI is presented as a simpler control plane alternative to ngrok. It authenticates against GitHub, lists Codespaces, and opens SSH access directly to the selected Codespace. In the architecture, this bypasses the external tunnel service and uses GitHub’s own management plane.
11. The repository also documents operational state management for Docker and the environment: inspect, rename, attach, stop, and remove containers; check disk and RAM usage; and add non-root users. These are maintenance concerns around the same containerized workspace.
12. From an architecture-diagram perspective, the key nodes are: the user, GitHub Codespaces, Docker/Kali container, optional VNC/noVNC browser access, optional SSH/ngrok tunnel, and GitHub CLI. The primary data flow is interactive shell or GUI control from the user into the Codespace/container, with ngrok or GitHub CLI acting as access bridges.
13. There is no backend service, API server, database, or build pipeline in this repo. Its “system architecture” is really a set of documented deployment and access patterns for a cloud dev container used as a temporary security lab.
14. The repository’s main boundary is operational, not code-based: it teaches how to assemble a remote Linux workstation inside GitHub infrastructure, then choose one of three access modes—direct terminal, browser GUI, or tunneled SSH—depending on the task.
Main entry points: readme.md Main Guide · installation_guide/readme.md Install Guide · assets Assets
Components 17
Documentation
Primary repo content and supporting guides
- Main Guide · Primary source of truth for the workflow and command sequences
readme.md - Install Guide · Nested supporting installation and usage notes
assets/installation_guide/readme.md - Placeholder Note · Auxiliary placeholder document with limited architectural weight
assets/installation_guide/tets.md - Assets · Screenshots and supporting visual material
assets
Runtime Layers
Codespaces host and Dockerized Kali workspace
- Codespaces · GitHub-hosted development environment acting as the outer runtime boundary
- Docker CLI · Command layer used to pull, run, inspect, and manage containers
- Kali Container · Dockerized Kali Linux workspace used as the temporary VPS-like environment
- Privileged Mode · Container capability for TUN and other pentesting needs
Access Paths
Ways to reach the workspace interactively
- Kali Shell · Convenience script that locates a Kali container and opens an interactive shell
- VNC Stack · XFCE, TightVNC, noVNC, certificates, and startup wiring for browser desktop access
- noVNC Gateway · Websockify-based forwarding from VNC to a browser-accessible port
- SSH Tunnel · SSH exposed through ngrok for public terminal access
- ngrok · External TCP tunnel service used to publish local SSH
- GitHub CLI · Alternative access path that authenticates to GitHub and opens Codespace SSH
Operations
Container lifecycle and environment maintenance
- Container Ops · Inspect, attach, rename, stop, remove, and resource-check workflows
- Env Setup · User and environment preparation such as keys, SSH, and desktop prerequisites
Other components
- User · Person using the repository instructions to reach a temporary lab
Connections 19
- User → Main Guide: follows · Reads the operational guide to choose a workflow
- Main Guide → Codespaces: starts in · Runs inside the GitHub Codespaces host boundary
- Codespaces → Docker CLI: uses · Issues Docker commands from the Codespace environment
- Docker CLI → Kali Container: creates · Pulls and runs the Kali Linux container
- Kali Container → Privileged Mode: may require · Enables TUN or other elevated device access when needed
- Main Guide → Kali Shell: documents · Provides the wrapper for finding and entering a Kali container
- Kali Shell → Kali Container: execs into · Starts or attaches to an interactive shell in the container
- Main Guide → VNC Stack: documents · Explains the GUI desktop setup inside the container
- VNC Stack → noVNC Gateway: exposes · Forwards the VNC server to a browser-accessible session
- noVNC Gateway → User: serves desktop to · Lets the user interact with the Kali GUI in a browser
- Main Guide → SSH Tunnel: documents · Explains remote terminal access over SSH
- SSH Tunnel → ngrok: uses · Publishes SSH through an external tunnel
- ngrok → User: reaches · Provides remote terminal reachability to the user
- Main Guide → GitHub CLI: documents · Covers GitHub CLI as an alternate access/control path
- GitHub CLI → Codespaces: opens · Uses GitHub's management plane to reach the Codespace
- Main Guide → Container Ops: documents · Captures operational tasks for container upkeep
- Main Guide → Env Setup: documents · Covers keys, SSH setup, and desktop prerequisites
- Assets → Main Guide: supports · Screenshots and media reinforce the documented steps
- Install Guide → Main Guide: supplements · Nested installation guide extends the main workflow