The Problem

Ever Gauzy is an open-source ERP/CRM/HRM platform that bundles employee time-tracking, project management, invoicing, and applicant tracking into one system. For a business that wants to replace several SaaS subscriptions with self-hosted software, the pain point is integration—most open-source ERPs cover accounting or HR, but not both with time-tracking and a desktop timer. Gauzy attempts to cover all of it behind a single API.

What This Does

This is not one codebase but a collection of four self-contained projects under packages/ (9,534 files) and apps/ (2,425 files). The substantial ones are the API server (packages/core), the Angular web UI (apps/webapp), the desktop timer for employee time-tracking (apps/desktop-timer), and an MCP server for AI tool integration. The stack is TypeScript across the board (8,404 files) with NestJS on the backend, Angular on the web frontend, and Express used in the desktop API.

The platform exposes headless REST/GraphQL APIs (documented at https://api.gauzy.co/docs), with features spanning HRM, CRM, accounting, inventory, and multi-currency/multi-language support. The README lists integrations with Upwork and HubStaff, plus a desktop timer that runs on Windows and Linux.

How It Is Wired

The entry point for the API is apps/api/src/main.ts, which boots a NestJS application. The core business logic lives in packages/core/src/lib, where controllers route to services that persist via TypeORM entities. The desktop timer runs as an Electron app with its own API (apps/desktop-api), communicating with the main Gauzy API for timesheet sync.

The deployment wiring is extensive: .deploy/ contains Dockerfiles for the API, desktop apps, MCP server, and MCP-auth, plus Kubernetes manifests for demo, stage, and prod environments across Civo and Cloudflare. CI runs through Jenkins (.github/workflows/deploy-civo-prod.yml exists, but the primary CI is Jenkins). The docker-compose files in .deploy/ssh/ handle Cloudflare and Let's Encrypt SSL setups.

The wiring for the MCP server is the least mapped part of this repo—the analysis shows its Dockerfile and Kubernetes manifests but no clear internal call graph from the entry points analyzed.

How To Use It

Setup: Clone with git clone https://github.com/moses-y/ever-gauzy, then install dependencies with yarn install (the repo uses yarn, evidenced by the lockfile).

Configuration: The app loads environment variables from .env.compose at boot. This file is committed to the repo and contains generated secrets—rotate them before any real deployment. A .env.example with empty values should replace it.

Running it: The API starts via yarn start:api (inferred from the NestJS structure; the README documents yarn start for the webapp). Docker deployments use the compose files in .deploy/—for a demo, run docker-compose -f .deploy/ssh/with-letsencrypt/demo/docker-compose.api.demo.letsencrypt.pre.yml up.

Real-World Use

A consulting firm with 40 employees could deploy Gauzy to replace separate tools for time-tracking (Toggl), invoicing (FreshBooks), and CRM (HubSpot). Employees run the desktop timer (apps/desktop-timer), which records activity and syncs to the API. The firm's admin uses the web UI for payroll calculations from tracked hours, invoicing from project budgets, and candidate tracking for hiring. The MCP server would let an internal AI assistant query employee timesheets or project status through natural language.

Code Health & Issues

Static analysis found 7 issues (2 critical, 1 high, 4 medium):

  • Critical - Committed credentials in .env.compose (JWT secrets, DigitalOcean keys, Cloudinary secret, AI API key, PostHog key). These are loaded at boot and are live credentials. Rotate all of them and remove the file from the index.
  • Critical - Secrets in fork-triggerable workflow .github/workflows/deploy-civo-prod.yml (CIVO_KUBECONFIG, ingress certs). A PR can exfiltrate these. Move to workflow_run or gate on an environment.
  • High - Committed .env files (.env.compose, .env.demo.compose, .env.docker, .env.local). git rm --cached and rotate.
  • Medium - No permissions: declaration in workflows—GITHUB_TOKEN inherits repo defaults.
  • Medium - No Dependabot/Renovate across 96 manifests.
  • Medium - Docker base images (node:24.16.0-alpine3.23) not pinned by digest.
  • Medium - No dependency vulnerability scan in CI.

The repo has 549 test files and CI, but the committed secrets are a release blocker.

The Bottom Line

Gauzy is a genuinely broad platform with serious engineering behind it—the monorepo structure, desktop apps, and Kubernetes deployment targets are production-grade. The committed credentials and fork-triggerable secrets make it unsafe to deploy as-is; rotate everything first. For a business wanting a single self-hosted ERP/HRM with time-tracking, it's worth the setup effort. For anything less than that, the complexity outweighs the benefit.