# l0n3m4n/github-vps architecture

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

- Interactive diagram: https://gitdiagram.com/l0n3m4n/github-vps
- Repository: https://github.com/l0n3m4n/github-vps

## Overview

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`](https://github.com/l0n3m4n/github-vps/blob/main/readme.md) (Main Guide), [`assets/installation_guide/readme.md`](https://github.com/l0n3m4n/github-vps/blob/main/assets/installation_guide/readme.md) (Install Guide), [`assets`](https://github.com/l0n3m4n/github-vps/tree/main/assets) (Assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_docs["Documentation"]
  node_main_guide["Main Guide<br/>doc<br/>[readme.md]"]
  node_install_guide["Install Guide<br/>doc<br/>[readme.md]"]
  node_placeholder_note["Placeholder Note<br/>[tets.md]"]
  node_assets_bundle["Assets<br/>media"]
end

subgraph group_runtime["Runtime Layers"]
  node_codespaces[("Codespaces<br/>host environment")]
  node_docker_cli["Docker CLI<br/>container control"]
  node_kali_container[("Kali Container<br/>security lab")]
  node_privileged_access{{"Privileged Mode<br/>device passthrough"}}
end

subgraph group_access["Access Paths"]
  node_shell_wrapper["Kali Shell<br/>wrapper script"]
  node_vnc_stack[("VNC Stack<br/>desktop stack")]
  node_novnc_gateway["noVNC Gateway<br/>browser bridge"]
  node_ssh_tunnel{{"SSH Tunnel<br/>remote access"}}
  node_ngrok["ngrok<br/>tunnel service"]
  node_github_cli["GitHub CLI<br/>control plane"]
end

subgraph group_ops["Operations"]
  node_container_ops["Container Ops<br/>maintenance"]
  node_env_setup["Env Setup<br/>configuration"]
end

node_user(("User<br/>operator"))

node_user -->|"follows"| node_main_guide
node_main_guide -->|"starts in"| node_codespaces
node_codespaces -->|"uses"| node_docker_cli
node_docker_cli -->|"creates"| node_kali_container
node_kali_container -.->|"may require"| node_privileged_access
node_main_guide -->|"documents"| node_shell_wrapper
node_shell_wrapper -->|"execs into"| node_kali_container
node_main_guide -->|"documents"| node_vnc_stack
node_vnc_stack -->|"exposes"| node_novnc_gateway
node_novnc_gateway -->|"serves desktop to"| node_user
node_main_guide -->|"documents"| node_ssh_tunnel
node_ssh_tunnel -->|"uses"| node_ngrok
node_ngrok -->|"reaches"| node_user
node_main_guide -->|"documents"| node_github_cli
node_github_cli -->|"opens"| node_codespaces
node_main_guide -->|"documents"| node_container_ops
node_main_guide -->|"documents"| node_env_setup
node_assets_bundle -.->|"supports"| node_main_guide
node_install_guide -.->|"supplements"| node_main_guide

click node_main_guide "https://github.com/l0n3m4n/github-vps/blob/main/readme.md"
click node_install_guide "https://github.com/l0n3m4n/github-vps/blob/main/assets/installation_guide/readme.md"
click node_placeholder_note "https://github.com/l0n3m4n/github-vps/blob/main/assets/installation_guide/tets.md"
click node_assets_bundle "https://github.com/l0n3m4n/github-vps/tree/main/assets"

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_main_guide,node_install_guide,node_placeholder_note,node_assets_bundle toneBlue
class node_codespaces,node_docker_cli,node_kali_container,node_privileged_access toneAmber
class node_shell_wrapper,node_vnc_stack,node_novnc_gateway,node_ssh_tunnel,node_ngrok,node_github_cli toneMint
class node_container_ops,node_env_setup toneRose
class node_user toneNeutral
```

## Components

### Documentation

Primary repo content and supporting guides

- [Main Guide](https://github.com/l0n3m4n/github-vps/blob/main/readme.md): doc · Primary source of truth for the workflow and command sequences · `readme.md`
- [Install Guide](https://github.com/l0n3m4n/github-vps/blob/main/assets/installation_guide/readme.md): doc · Nested supporting installation and usage notes · `assets/installation_guide/readme.md`
- [Placeholder Note](https://github.com/l0n3m4n/github-vps/blob/main/assets/installation_guide/tets.md): note · Auxiliary placeholder document with limited architectural weight · `assets/installation_guide/tets.md`
- [Assets](https://github.com/l0n3m4n/github-vps/tree/main/assets): media · Screenshots and supporting visual material · `assets`

### Runtime Layers

Codespaces host and Dockerized Kali workspace

- **Codespaces**: host environment · GitHub-hosted development environment acting as the outer runtime boundary
- **Docker CLI**: container control · Command layer used to pull, run, inspect, and manage containers
- **Kali Container**: security lab · Dockerized Kali Linux workspace used as the temporary VPS-like environment
- **Privileged Mode**: device passthrough · Container capability for TUN and other pentesting needs

### Access Paths

Ways to reach the workspace interactively

- **Kali Shell**: wrapper script · Convenience script that locates a Kali container and opens an interactive shell
- **VNC Stack**: desktop stack · XFCE, TightVNC, noVNC, certificates, and startup wiring for browser desktop access
- **noVNC Gateway**: browser bridge · Websockify-based forwarding from VNC to a browser-accessible port
- **SSH Tunnel**: remote access · SSH exposed through ngrok for public terminal access
- **ngrok**: tunnel service · External TCP tunnel service used to publish local SSH
- **GitHub CLI**: control plane · Alternative access path that authenticates to GitHub and opens Codespace SSH

### Operations

Container lifecycle and environment maintenance

- **Container Ops**: maintenance · Inspect, attach, rename, stop, remove, and resource-check workflows
- **Env Setup**: configuration · User and environment preparation such as keys, SSH, and desktop prerequisites

### Other components

- **User**: operator · Person using the repository instructions to reach a temporary lab

## Connections

- 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
