Forge OS • Enterprise Multi-Tenant Workspace

Kanban boards, dynamic databases and a Notion-style knowledge base in one self-hosted workspace. Built on Astro SSR with a synchronous SQLite core — no virtual DOM, no client-side framework, no external services.

Live instance · Report a bug · Request a feature · Changelog

English · Español

Table of contents

• Why Forge OS
• Features
• Screenshots
• Getting started
  • Requirements
  • Install
  • Scripts
• Tech stack
• Deployment
• Security
• Roadmap
• Contributing
• License

Why Forge OS

Most team workspaces make you choose: a fast board with no documentation, or a wiki that cannot track work. Forge OS puts both behind the same multi-tenant boundary, so an issue can link to a page and the page knows which issues reference it.

It runs as a single Node process against a local SQLite file. There is no database server to operate, no queue, no cache tier. Cloning the repo and running two commands gives you a working instance.

Features

• Strict multi-tenant isolation — workspaces are separated at the data layer, not the UI. Every query is scoped by workspace_id, with exhaustive IDOR protection on each endpoint.
• Kanban and sprints — epics, stories, tasks and bugs across four columns with persistent drag & drop, plus server-side time tracking that auto-stops when an issue reaches Done.
• Knowledge base — a Notion-style editor built on Editor.js with tables, code blocks, undo/redo and bidirectional links between pages and issues.
• Dynamic databases — build Airtable-style tables from the UI, without touching a schema file.
• Sprint metrics — velocity, burndown, distribution and precision charts rendered with Chart.js from real work logs.
• Forge Hub — public profiles with banner, avatar and bio, inline editing, friendships and user blocking.
• Guest accounts — restricted, isolated sessions that can be promoted to a real account later, carrying their provisional workspaces across.
• Command palette — Cmd/Ctrl+K for global navigation, plus single-key shortcuts throughout the app.
• Bilingual UI — English and Spanish, detected automatically.

(back to top)

Screenshots

Every image below comes from npm run seed — regenerate them all with npm run screenshots.

Sprint metrics — velocity, burndown, workload distribution and estimation precision, drawn from real work logs.

Knowledge base — a Notion-style editor with a page tree and bidirectional links between pages and issues.

Hub — every workspace, your pending tasks and notifications in one place.

(back to top)

Getting started

Requirements

Node.js 22.12 or newer. CI runs on Node 26.

Nothing else. better-sqlite3 ships prebuilt binaries for linux-x64, linux-arm64, macOS and Windows, so there is no compiler step — an earlier version of this page asked for a C++ toolchain that is not actually needed.

Install

git clone https://github.com/JoseSerpaCode/Forge-OS.git
cd Forge-OS
npm install

Populate a demo workspace — a sprint, a board spread across all four columns, work logs and a small knowledge base:

npm run seed

Then start the dev server:

npm run dev

The app is served at http://localhost:4321. Sign in as avery with the seed password (LocalDevPass123! by default; override it by exporting TEST_PASSWORD before seeding).

npm run seed refuses to touch a database that already has data. Pass -- --force to wipe and reseed. Point it elsewhere with DATABASE_URL if you want to keep your working database untouched.

Scripts

Command	What it does
npm run dev	Dev server on port 4321
npm run build	Production build (Node adapter)
npm run seed	Seed a demo workspace (-- --force to overwrite)
npm test	Unit tests (Vitest)
npm run test:e2e	End-to-end tests (Playwright)
npm run typecheck	astro check

(back to top)

Tech stack

• Frontend — Astro 7 with vanilla JS and CSS. No virtual DOM and no framework runtime shipped to the browser.
• Backend — Astro SSR on the Node adapter, running as a single monolithic server with its own middleware chain. Realtime over Socket.IO.
• Database — SQLite through better-sqlite3, synchronous and in-process.
• Testing — Playwright for end-to-end flows, Vitest for units.

(back to top)

Deployment

Full walkthrough in deploy/README.md — a VM with a persistent disk, Caddy in front and systemd keeping the process alive. It is what runs forge-os.online on a free-tier e2-micro.

Three things worth knowing before you open it:

• Data lives outside the checkout (/var/lib/forge-os, via DATABASE_URL and STORAGE_DIR), so a deploy that wipes the directory cannot take the database or the uploads with it.
• PUBLIC_SITE_URL is required in production. Without it the app advertises itself as localhost:4321 in the canonical URL and the OpenGraph tags, even while serving a real domain.
• Never cp forge.db. The database runs in WAL mode, so copying the file gives you an incomplete or corrupt snapshot. Use scripts/backup.sh, which goes through sqlite3 .backup and verifies the result with integrity_check.

Once installed, updates are one command:

sudo /opt/forge-os/scripts/deploy.sh

It backs up the database, sets dist/ aside, builds, restarts, and waits for /healthz — which does a real read against SQLite — before calling the deploy good. If any step fails it returns to the previous commit and leaves the service running the version that worked.

(back to top)

Security

• RBAC — owner, editor, commenter and viewer roles, enforced server-side.
• Attack surface — active mitigations for SQL injection, XSS, SSRF and path traversal in attachment handling, behind a strict CSP.
• Uploads — 10 MB ceiling, MIME type verification, UUIDv4 identifiers.
• Rate limiting — persistent across restarts, applied to auth and public endpoints, keyed on CF-Connecting-IP so it cannot be bypassed by forging X-Forwarded-For.
• Registration — usernames are checked against reserved and abusive names (with leetspeak and separator evasion folded in), and a signed arithmetic challenge keeps generic bots out. The challenge is served by this app: no third-party captcha widget, because the product promises no third-party scripts.
• No third parties, literally — no analytics, no trackers, no external fonts on app pages, and no remote avatar service. The CSP allows 'self' only.
• Guest accounts are socially inert — they can read the app, but cannot send friend requests, block anyone, or be the target of either. They are also kept out of search suggestions, so the user directory does not become a visitor log.

Found something? See SECURITY.md.

(back to top)

Roadmap

• Identity and workspaces — login, sessions, multi-tenant isolation
• Knowledge base — documents, safe Markdown parsing, block editor
• Bidirectional links between pages and issues — the API is there (linked-pages, backlinks), the interface is not
• Kanban and sprints — drag & drop, velocity/distribution/precision metrics, time tracking
• Dashboard — cross-workspace summary and global notifications
• UI/UX and command palette — global shortcuts, modals, toast feedback
• Dynamic databases (phase 1) — Airtable-style tables from the UI
• Public landing page and guest accounts created on request
• Production deployment with automated rollback and verified backups
• Dynamic databases (phase 2) — relations, formulas and saved views
• Full-text search across pages and issues
• Sign in with Google and GitHub — full-redirect flow with a signed state; each provider activates only when its credentials are configured
• Responsive pass over the in-app screens

(back to top)

Contributing

Contributions are welcome.

1. Fork the project
2. Create your branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'feat(scope): add AmazingFeature')
4. Push the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Please read the contribution guidelines first. Pull requests that change critical flows are expected to come with Playwright tests.

License

Distributed under the MIT License. See LICENSE.

(back to top)