Installation Guide

Installing Noviz Pro

A complete, step-by-step install for everything in the Noviz Pro source code: the backend API, its database, the admin console, the agent (chat) app, and — as an optional step — connecting a real ERP system via the ERPNext connector. This same guide ships as docs/INSTALL.md inside the source code itself, so it stays with the code you actually received.

What you're installing

The agent runs and is fully testable without a real ERP connected — see Step 3 for what a demo install looks like without one.

Prerequisites

• Node.js 18+ and npm
• Postgres 14+, with permission to run CREATE EXTENSION vector;
• An OpenAI API key, or any OpenAI-compatible endpoint + key
• (Optional, only if connecting a real ERP) An ERPNext instance reachable over HTTP(S), with an admin login

Step 1 — Install the backend

cd backend
npm install
cp .env.example .env

Two values you can set immediately, regardless of the rest:

# .env
AGENT_JWT_SECRET=change_this_to_a_long_random_string
LLM_API_KEY=sk-...            # your OpenAI (or OpenAI-compatible) key
CREDENTIAL_ENCRYPTION_KEY=... # generate with the command below

node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

Run that command twice — once for AGENT_JWT_SECRET if you'd rather generate one than type your own, and once for CREDENTIAL_ENCRYPTION_KEY, which encrypts admin-provisioned ERP credentials at rest and needs to be a real random value.

Step 2 — Install the backend database

Everything agent-side — session context, semantic search, interaction logs, admin settings — lives in one self-hosted Postgres database with the vector extension. It never touches your ERP's own database.

createdb erp_agent
psql erp_agent -c "CREATE EXTENSION IF NOT EXISTS vector;"

Then run every migration in backend/src/db/migrations/, in filename order — they're numbered for exactly this reason:

cd backend
for f in src/db/migrations/*.sql; do psql erp_agent -f "$f"; done

That creates (among others): context_embeddings (pgvector semantic search), interaction_log / rule_evaluations (every reasoning-engine run, also the training-data source), settings / admin_audit_log, and user_credentials (encrypted at rest).

# .env
DATABASE_URL=postgres://user:password@localhost:5432/erp_agent

The database starts empty — it fills in as the agent is used. It does not need seed/sample data to run; that's a separate concern from the ERPNext side, covered next.

Step 3 — Connect an ERP system (optional)

The agent's core is ERP-agnostic by design — it talks to whatever implements the connector interface. ERPNext ships as the reference connector in the source code and is the only one implemented out of the box.

You can skip this step entirely and still complete the full install through Step 6 — the backend, database, admin console, and agent app all come up fine with no ERP connected; you just won't be able to log in as an ERPNext user or call ERPNext-backed tools until this step is done.

3a. Using your own ERPNext instance

In ERPNext: your user profile → API Access → Generate Keys. Put the resulting key/secret in the backend's .env:

# .env
ERPNEXT_BASE_URL=https://your-erpnext-site.example.com
ERPNEXT_API_KEY=...
ERPNEXT_API_SECRET=...
SYSTEM_PROVIDER=erpnext

These are service-level credentials, held only by the agent backend. Individual end users still log in with their own ERPNext identity — the two are kept deliberately separate.

3b. ERPNext reference/demo database (optional)

If you don't already have an ERPNext instance with data in it, you need something populated to point this at — an empty ERPNext site has nothing for the agent to list or act on. Two options:

• Spin up a fresh ERPNext instance yourself (the official frappe_docker quick-start, or a Frappe Cloud trial site) and enter a handful of test records by hand — a Sales User and a couple of Quotation records is enough for Step 6.
• Import ERPNext's own demo/sample data, if your version ships one, as a faster starting point.

Connecting a different ERP later

Swapping in a different business system (SAP, or anything else) means writing one new connector implementation — the source code includes a checklist for exactly this. Nothing in the core engine or either frontend needs to change; it's a custom-connector engagement, not something the base source ships pre-built. Reach out to support@noviz.in if that's what you need.

Step 4 — Install the admin console

cd frontend/admin
npm install
cp .env.example .env
npm run dev

Open http://localhost:5173. Sign in with a user whose role is in ADMIN_ROLES (default: System Manager) — this is a separate permission check from ordinary agent tool access. You should see Global Settings, User Credentials, Policy Documents, and a live module-status strip.

Step 5 — Install the agent (chat) app

cd frontend/agent
npm install
cp .env.example .env
npm run dev

Open http://localhost:5174.

Step 6 — Test with a demo install

This confirms the whole stack — backend, database, admin console, agent app, and (if completed) ERPNext — actually works end to end.

1. In ERPNext, create one user with the Sales User role, and 1–2 Quotation records so there's something for the agent to find.
2. Sign in to the agent app (:5174) as that user.
3. Ask it: "list my quotations." You should get a rendered table back.
4. In the admin console (:5173), confirm the module-status strip shows your active modules, and that you can edit a setting.

If you skipped Step 3, confirm the rest is wired correctly by checking GET /api/tools returns a tool list once logged in via an admin-provisioned credential — full ERP-backed testing needs Step 3 completed first.

Optional: Docker (backend only)

A production Dockerfile is included if you'd rather not run the backend with npm run dev directly:

cd backend
docker build -t noviz-agent-backend .
docker run -p 4000:4000 --env-file .env noviz-agent-backend

The two frontend apps aren't containerized — npm run build produces static output you can serve from any static host or reverse proxy, pointed at each app's configured API base.

Troubleshooting

• Backend won't start — check DATABASE_URL is reachable and every migration ran without error, in order.
• Login fails against ERPNext — confirm the API key/secret belong to a user with permission to read roles, and that ERPNEXT_BASE_URL has no trailing-slash mismatch.
• No tools available after login — the logged-in user's ERPNext role isn't mapped to any tools in the role policy config. Sales User → quotation.list is the one mapping present out of the box.
• Anything else: contact us with which step, the exact command, and the exact error message or response body.

Precautions before you go live

Noviz is an AI ERP agent, and like any AI system, it can make mistakes. Review its outputs before relying on them in production, and never let it make unsupervised decisions on matters with serious financial, operational, or compliance consequences without human sign off. If you complete Step 3 against your own live ERPNext data rather than a demo/reference database, treat every action the agent takes there with the same review discipline you'd apply to a person new to the role. See our full Responsible AI page for the complete disclaimer.

Support

Questions about installing or extending this beyond what's documented here — including custom connectors for a different ERP/business system, or a synthetic test database sized to your needs — reach us at support@noviz.in.