SECURITY
On-premises
Run Converge on your own servers so project data stays in your network. What an install consists of and how it is configured.
Overview
Converge can be installed on your company's own servers, so project data never leaves your network. The engineering modules run in your engineers' browsers and need no outside connection. Projects, saved versions and seat records sit in your own database on your own hardware.
Tell us about your environment when you book a demo, and we will confirm what the install needs. This page describes the parts of an install and their settings, so your IT team knows what to expect.
What stays inside your network
- The engineering modules, from PVT and wells to simulation and economics. Calculations run in the browser.
- Projects, saved versions, reviews, approved reporting versions and comments, in one database per company on your database server.
- Sign-in, licences, seats and the audit log, in a control database on the same server.
The AI Engineer needs a model to talk to: either a cloud AI provider your company approves, or a model you host yourselves. With a self-hosted model, AI Engineer requests stay inside your network too. Tell us which model you plan to use and we will confirm the setup with you.
Parts of an install
| Part | What it is |
|---|---|
| App | A static web build that your engineers open in a browser. The web server that serves it also forwards /v1/ requests to the API, so the app and the API share one origin. |
| API service | One Node.js 20 process. It serves sign-in, projects, seats, roles, the audit log, the REST API, the MCP server and the AI Engineer. It listens on port 8080 by default. |
| Database | PostgreSQL (tested with version 16). A control database, converge_control by default, plus one database per company, created automatically when a company's owner confirms their email. |
| Admin portal | A second static web build for the people who run the install: companies, licences, licence requests, school domains and staff. |
| An outbound email service for confirmation, invite and password-reset links. |
The API applies its database migrations at start-up. The database user it connects as must be allowed to create databases, because each company gets its own.
The API also runs a sweep every 60 seconds that clears lapsed seats, old rate-limit windows and expired sessions.
Configuration
The API reads its settings from environment variables at start-up and refuses to start when a required setting is missing.
Required
| Setting | Purpose |
|---|---|
APP_URL |
The app's public address; used in emailed links and as an allowed origin |
DB_HOST, DB_USER, DB_PASSWORD |
Database connection |
Required in production
With ENVIRONMENT=production, the API also refuses to start without these:
| Setting | Purpose |
|---|---|
SESSION_KEY |
Key for hashing session ids at rest, 32 or more characters. Changing it ends every session. |
LEASE_SIGNING_KEY |
Key for signing seat tokens, 32 or more characters |
TOTP_ENC_KEY |
Key for encrypting staff secrets at rest, 32 or more characters |
PROXY_SECRET |
Shared secret the app's web server sends with forwarded requests, 32 or more characters. Only then does the API trust forwarded client addresses. |
ADMIN_URL |
The admin portal's address |
| Email settings | Sender address and the email service key |
Optional
| Setting | Default | Purpose |
|---|---|---|
PORT |
8080 | Listening port |
DB_PORT |
5432 | Database port |
DB_NAME |
converge_control |
Control database name |
DB_SSL |
off |
off, no-verify or verify. verify needs DB_SSL_CA, the database server's CA certificate (PEM). |
DB_POOL_MAX |
4 | Connections to the control database |
TENANT_POOL_MAX, TENANT_POOLS_MAX |
2, 8 | Connections per company database, and company databases kept open at once |
SITE_URL, EXTRA_ORIGINS |
none | Further allowed origins |
COOKIE_DOMAIN |
host only | Parent domain for the session cookie, when the app and API are on different hosts |
TRUSTED_PROXY_HOPS |
1 | Proxies in front of the API that add to the forwarded-address header |
TRIAL_WEEKS |
4 | Length of the business free trial |
API_KEY_RATE_PER_MIN |
120 | Requests per minute per API key |
TOOL_WORKERS, TOOL_TIMEOUT_MS |
2, 120000 | Worker threads for AI Engineer tool calls, and the time limit per call (ms) |
| AI provider keys | none | One key per cloud AI provider you allow. A provider without a key is reported as unavailable. |
BOOTSTRAP_ADMIN_EMAIL, BOOTSTRAP_ADMIN_NAME |
none | First administrator (below) |
First administrator
Set BOOTSTRAP_ADMIN_EMAIL (and optionally BOOTSTRAP_ADMIN_NAME) and start the API. If no administrator exists yet, the API creates that administrator with no password and emails a single-use "set your password" link, valid for 24 hours. It never runs once any administrator exists. Check the address before you set it: whoever receives the link becomes a superadmin.
Further administrators are invited from the admin portal's Staff page. Administrator passwords need at least 14 characters, and the last active superadmin cannot be disabled or demoted.
Security settings that carry over
Everything on the Security page applies to an on-premises install: separate company databases, server-side seat and permission checks, hashed passwords and links, rate limits, session controls and the audit log. Back up the control database and every company database with your normal database backups.
Local mode is different
A build of the app with no API address runs in local mode: no sign-in, every module available, one project kept in that browser's storage, and no shared database. It is useful for evaluation on a single machine, but it has no seats, roles, enforced sign-off or audit log. An on-premises install is the full service, run on your servers.