Gingee - Application Server

A Gen AI Project

See AI Disclaimer

The objective of the project is to validate the feasibility of GenAI in platform/framework level programming as opposed to generating simplistic applications and in the process be the world's first AI authored and human co-authored production ready application server.

What is Gingee?

Gingee is a secure, batteries-included Node.js application server designed to dramatically accelerate web app development. Co-authored by a human architect and a GenAI partner, it provides a full featured platform that allows developers to focus on business logic instead of boilerplate. It achieves this through a secure sandbox, a powerful module ecosystem, and a comprehensive application lifecycle management system.

🚀 Quick Start

Requires Node.js ≥ 20.18.1 (Node 20 LTS or newer).

Get a new, fully configured Gingee server running in under a minute. See video

# 1. Install the Gingee CLI (may take a few moments to complete)
npm install -g gingee-cli

# 2. Create a new Gingee project
gingee-cli init my-gingee-project

# 3. Navigate into your new project
cd my-gingee-project

# 4. Start the server!
npm start

# 5. Browse to http://localhost:7070

That's it! You should now see Glade - the Gingee admin panel in your web browser. You can install applications for the Gingee platform from the Gingee App Store.

Key Features

Gingee is a comprehensive platform designed to provide a secure, efficient, and enjoyable development experience.

• Secure by Default

  • Whitelist Permissions System: Applications have no access to the filesystem, database, network, email, generative AI, or CRON scheduler by default. Administrators grant explicit permissions for a "secure by default" posture. See the Threat Model (cooperative multi-app vs hostile multi-tenant).
  • Sandboxed Execution: Server scripts run in a gbox vm context: custom require, path jails, no host process (cooperative multi-app isolation—not a multi-tenant VM). UMD libs that need Function work by default; set box.allow_dynamic_code: false for stricter lockdown. With cache.server.enabled, sandboxed module instances are reused across requests (handler still runs every time); use no_cache_regex or reloadApp for live edits.

• Instant Time to Joy

  • All-in-One CLI: A single command (gingee-cli init) scaffolds a complete, runnable project with a built-in admin panel.
  • Simplified API: All request/response logic goes through $g from gingee(). Entry scripts keep await gingee(async ($g) => …); required box modules can use bare request-local $g without threading it through every require.
  • Flexible Routing: Use zero-configuration file-based routing for rapid development, or create a routes.json for powerful, dynamic RESTful APIs.
  • Modern JavaScript: Use modern ESM syntax (import/from) directly in your server scripts with zero build steps or configuration.

• Batteries-Included Backend

  • Multi App Hosting: Deploy and run multiple apps with clear isolation, individual app lifecycles and hot app reloads.
  • Multi-Database Support: Write your code once and deploy against PostgreSQL, SQLite, MySQL, MSSQL, and Oracle, with a consistent API. SQLite is always installed; other drivers are optional dependencies (install fails soft if a native build fails).
  • Rich Standard Library: A comprehensive suite of sandboxed modules for common tasks, including crypto, image processing, pdf generation, db access, fs (including list/stat/walk), httpclient (get/post/put/patch/delete), transactional email (SendGrid / console), and generative ai (Gemini / mock, streaming chat, multimodal, document parse, moderation). Optional project box.local_modules for shared host libraries.
  • Streamed Responses: Progressive output (e.g. SSE for AI tokens) via $g.response.startStream / writeSSE / endStream.
  • WebSockets (opt-in): Master-owned realtime on the public HTTP(S) port (app.json → websockets + permission); rooms/broadcast via require('websockets'). Multi-node: websockets.fanout.driver: "redis" + sibling websockets.redis. Sample: ginchat.
  • Background queue: require('queue').add with memory or Redis drivers, retries, DLQ, and box job handlers. Glade Queue / DLQ: live jobs (running/waiting/pending/delayed) + DLQ retry/discard. CRON can target type: "queue".
  • CRON Scheduler: App-declared schedules in app.json (script, URL, or queue job); scheduler.enabled (default off); optional Redis coordination; Glade Schedules with Run now.
  • Request & Outbound Limits: Concurrency caps, request/stream timeouts, and default httpclient timeouts via gingee.json → limits.
  • Egress / SSRF policy: Default-protected outbound URL checks on httpclient and scheduler URL jobs (gingee.json → egress).
  • Config secrets: env:VAR / file:… references in JSON config, resolved by the engine (apps still cannot read host process.env).
  • Prometheus Metrics: Engine-scoped /metrics scrape endpoint (default localhost-only; optional bearer token) for HTTP scripts, limits, egress, scheduler, WebSocket (incl. fan-out), and queue/DLQ series.
  • Audit Trail: Append-only JSONL log of permission changes and app lifecycle events (gingee.json → audit, default logs/audit.jsonl).
  • Process isolation (opt-in): Selected apps can run server scripts in a child process (isolation.mode: "process"); public ports stay on the master. Privileged apps stay in-process; buffered + SSE over IPC; groups and auto-restart supported.
  • Application Startup Hooks: Define startup_scripts to automatically run database migrations or seed data when your app is installed or upgraded.
  • Application Middleware: Define default_include to automatically inject scripts in front of all API end points of the app. Enabling easy authentication, policies, role management etc.

• Full Lifecycle & Automation

  • Glade Admin UI: Built-in web panel for app lifecycle (install, upgrade, rollback, delete, permissions), Schedules / Run now, and Queue / DLQ (live jobs + dead letter).
  • Interactive Installers: Both the CLI and the Glade UI feature intelligent installers that read an app's requirements, prompt the admin for permission consent, and guide them through database configuration.
  • Automated Deployments: All lifecycle commands in the CLI can be run non-interactively using a preset file, making it perfect for CI/CD pipelines.
  • Automatic Maintenance Mode: The server automatically puts an application into a 503 Service Unavailable state during critical lifecycle events to ensure data integrity.
  • Built for Scale: With a pluggable distributed caching system (Redis), native service installation, and PM2 compatibility.

• Decentralized App Store

  • Discover and install applications from any gstore.json manifest on the web using the gingee-cli. Anyone can host their own public or private app store.

• GenAI-Native Workflow

  • Co-authored by a human architect and a Generative AI partner, Gingee is a testament to a new, highly efficient "Dialog-Driven Development" workflow. The project includes a pre-built knowledge bundle (ai-context.md) to empower you to build your own apps with an AI partner.

Documentation

Dive deeper into the architecture and learn how to build powerful applications with Gingee.

Concepts

| Document | Description | | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------- | | Core Concepts | A high-level overview of the Gingee philosophy, project structure, the sandbox, and the module ecosystem. | | Features | The list of features supported by Gingee | | Roadmap | The roadmap of core and app features in the pipeline for the Gingee app platform |

Configuration & Setup

| Document | Description | | :------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------- | | Gingee CLI | The all-in-one command-line interface for the Gingee platform | | Server Configuration (gingee.json) | A full reference guide for the server-wide gingee.json file, controlling settings like ports, caching, and security. | | Glade Admin Panel | Glade is the official, web-based administration panel for Gingee |

Developer Docs

| Document | Description | | :--------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | | App Structure & app.json | A detailed breakdown of the app folder structure and a comprehensive reference for all app.json configuration options. | | Server Script Guide | Learn the anatomy of a server script and get a full API reference for the powerful $g global object. | | App Developer Guide | A guide to creating your apps on the Gingee platform | | App Packaging Guide | Gingee platform's standardized application packaging process | | App Permissions Guide | Gingee platform's app permissions ecosystem. | | SPA App Dev Guide | A guide to creating modern SPA with frameworks on the Gingee platform | | GStore Hosting Guide | Gingee platform's decentralized app store hosting guide |

Refrence

| Document | Description | | :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------- | | Full API Reference | The complete JSDoc-generated API documentation for every function in every Gingee app module. | | API Examples | Examples of using Gingee modules, It can also be installed in a Gingee server using the .gin package in the dist folder. | | | Gingee App Store | The official Gingee app store |

Project Details

| Project Phase | Status | Current Token Count | | :---------------- | :--------- | :-------------------------------------------------------------------------- | | Phase 1 | Completed | 1,038,862 / 1,048,576 (1M tokens used out of a 1M token context window) | | Phase 2 | Completed | 702,180 / 1,048,576 (700K tokens used out of a 1M token context window) |

Tooling

Google AI Studio, VS Code, NodeJS, NPM, JSDoc

Contributing

Please see our CONTRIBUTING guide for more details on how to contribute.

License

Gingee is licensed under the MIT License. See the LICENSE file for details.

Sponsors

Credits

| Role | Contributor | | :-------------- | :----------------------------------------------------------- | | Ideation | Vignesh Swaminathan | | Author | AI Provider | | Co-Author | Vignesh Swaminathan | | Tester | Vignesh Swaminathan | | Tech Writer | AI Provider | | Reviewer | Vignesh Swaminathan |