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 projectcd 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 gboxvm 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