EGH Research

# PyForge Web IDE PyForge is a powerful, browser-based IDE that connects to a real Node.js and bash backend. It provides a full shell environment right in your web browser, with direct access to the underlying file system and internet, all within a secure sandbox. It is designed to provide a rich, enterprise-grade development experience for projects of any scale. ## Features - **Real Bash Terminal:** A fully interactive bash terminal with internet access for running commands and using tools like `curl`, `git`, `wget`, `pip`, and more. - **File Explorer:** Manage files and directories within a secure `/workspace` directory. - **Package Manager:** A UI to install Python packages directly using `pip`. - **Multi-Tab Code Editor:** A responsive editor to write and edit your Python scripts, shell scripts, and other files. - **Source Control Integration:** A dedicated panel to manage your Git workflow, including cloning, viewing status, and committing & pushing changes with a single click. - **Web Preview:** Render static HTML files generated by your code directly within the IDE. --- ## Getting Started Follow these steps to get PyForge running on your local machine. ### 1. Install Dependencies Open a terminal and run the following command to install the necessary packages: ```bash npm install ``` ### 2. Configure GitHub Authentication (Crucial) To use Git features like `git clone` or `git push` on private repositories, you must configure a **GitHub Personal Access Token (PAT)**. - **Generate a PAT:** Go to your GitHub settings -> Developer settings -> Personal access tokens -> Tokens (classic) and generate a new token with the `repo` scope. - **Set the Environment Variable:** Before starting the server, set the `GITHUB_PAT` environment variable in your terminal. On macOS/Linux: ```bash export GITHUB_PAT="ghp_YourPersonalAccessTokenHere" ``` On Windows (Command Prompt): ```bash set GITHUB_PAT="ghp_YourPersonalAccessTokenHere" ``` The server reads this token on startup and configures Git to use it for all authenticated operations. ### 3. Start the Development Server After installation and PAT configuration, start the server: ```bash npm run dev ``` This command will start both the backend server and the frontend web application. You can access the PyForge IDE in your browser at the URL provided (usually `http://localhost:8000`). --- ## Security Model: The Workspace Jail PyForge is powerful because it provides real shell access, but this power is controlled within a strict security sandbox. - **Server-Side Jail:** The environment is **not** a browser-based sandbox (like Pyodide/WASM). It is a server-side file system jail. The backend Node.js server intercepts every command and ensures it operates **only within the `/workspace` directory**. - **No Escape:** Directory traversal attacks (e.g., `cd ../../`) are blocked. A script running inside the workspace cannot access, read, or write to the host machine's system files (like `/etc`, `/root`, etc.). - **Analogy:** Think of the `/workspace` as a secure, walled-off room. You have full internet access inside that room (`curl`, `git clone`, `pip install`). However, you absolutely cannot open the door and access the building's control systems. Any malicious script you download can only cause damage *inside your own room*. --- ## Architecture: Single-Instance vs. Multi-User It is critical to understand the application's current architectural model. - **Current State (One Shared Room):** The current application provides **one single clean room**. If you and a colleague both connect to the same server instance (`npm run dev`), you will be sharing the exact same filesystem, terminal session, and Git configuration. It is like two people using the same single computer. The `GITHUB_PAT` is also shared for this instance. - **Future Enterprise State (Many Private Rooms):** For a true multi-user, enterprise-grade service, the architecture would need to ensure that **each user gets their own completely separate and isolated "clean room" simultaneously.** This is a significant architectural leap and would be achieved using a different set of tools, such as: - **Containerization (Docker):** Packaging this application into a portable container. - **Orchestration (Kubernetes):** A system to automatically spin up a new, dedicated container for each user session and destroy it afterward. The current codebase is the powerful **"engine"** for this IDE. A full enterprise deployment would involve wrapping this engine in an orchestration layer to create and manage a private, secure room for every single user.