Developer quickstart

How a new app gets built on EvoPlatform. The short version: scaffold from a template, run standalone while you build, and flip to platform mode with environment variables when you're ready to share tenancy, auth, and billing.

Scaffold an app

evo new my-app --dir ./apps --port 4300 --db-port 5450

evo new clones the Next.js starter template under a new identity: names, ports, database, and secrets are all rewritten for your app. What comes wired in:

• Tenancy — row-level isolation, tenant-scoped queries
• Auth — email/password sessions, with signup, login, and account pages
• Offline-first sync — an IndexedDB mutation queue with last-write-wins merge, so the app works without a connection
• A sample domain (projects/tasks) to replace with your own

Standalone mode

The scaffolded app runs entirely on its own: local users table, a single implicit tenant, no external services. This is the default — build your product here. Apps can live their whole life standalone if multi-tenancy is never needed.

Join the platform

When the app should become a tenant of the shared platform:

evo register my-app --platform-url https://platform.example.com \
  --email you@example.com --dir ./apps/my-app

evo register signs in as a platform admin, registers the app in the platform's registry, and writes the credentials into the app's .env:

PLATFORM_URL=https://platform.example.com
EVO_CLIENT_ID=app_...
EVO_CLIENT_SECRET=...        # shown by the platform exactly once; caught here
NEXT_PUBLIC_PLATFORM_MODE=1

Restart the app and PLATFORM_URL flips it into platform mode: logins are delegated to the platform (password and passkey), local rows are provisioned just-in-time from verified claims, and the Members page — invites, roles, billing — lights up. The app verifies platform-issued JWTs locally against the platform's published keys (JWKS), so a platform outage doesn't take sign-ins down with it once tokens are cached.

What the SDK gives you

@evoplatform/sdk-node is the whole integration surface:

• verifyToken — local JWT verification via cached JWKS
• login / refresh / logout / signup — auth proxying for your own forms
• passkey* — WebAuthn ceremonies proxied through your app
• listTenantMembers, createTenantInvite, … — member management for workspace admins
• createCheckout / createBillingPortal — per-app Stripe billing
• sendEmail, pushEvent — tenant-aware email and audit events

Adding Ask AI

Evo.ai is a separate service with its own URL and credentials, so the SDK ships a separate client for it rather than a method on EvoPlatform:

import { AskAi } from '@evoplatform/sdk-node';

const ai = new AskAi({
  url: process.env.EVOAI_URL!,
  serviceKey: process.env.EVOAI_SERVICE_KEY, // server-side only
});

const { answer, sources, gated } = await ai.ask({
  question,
  tenantId: session.tenantId,
  sourceTypes: ['permit'],   // inherit your app's own permission model
});

Two ways to authenticate, matching the two ways an app is built:

Your app	Pass	The tenant comes from
Has its own login	serviceKey on the client, tenantId per call	your X-Data-Tenant header
Is in platform mode	accessToken per call	the token's verified claims

The service key identifies the application, not the customer — a holder can name any tenant, so it stays server-side and tenantId must come from your own session, never from anything the browser sent.

A refusal is not an error. ask() resolves normally with gated: true when the question was declined as unrelated to the indexed data, and unconfigured: true when the tenant has no usable model. Render both differently from a failure — showing the guardrail working as an error teaches people to distrust the assistant.

Timeout defaults to 120 s, because a model composing an answer over retrieved records is not a fast API call.

Going deeper

Install, architecture, and the template contract live in the EvoPlatform repository's docs/ folder, next to the code they describe:

• docs/INSTALL.md — full local setup, evo new, and platform mode
• docs/ARCHITECTURE.md — system design and the reasoning behind it
• docs/TEMPLATE_CONTRACT.md — what a starter template must satisfy

Running the platform on your own infrastructure is covered by a set of guides in docs/guides/, written for someone who has not used EvoPlatform before:

1. Self-hosting EvoPlatform — laptop trial through to production with TLS
2. Adding Ask AI — Evo.ai alongside it, cloud model or local
3. Connecting your data — sources, sync, and verifying answers are grounded
4. Integrating Ask AI into your app — the three client patterns
5. Air-gapped installation — the whole stack with no internet connection