Deployment

Introduction

A Pilotoo server is an ordinary NestJS application. Deploying it means giving it a PostgreSQL database, its configuration folder and environment, a real identity, and a proxy that lets WebSocket connections through. This page lists those pieces.

Database

Set DATABASE_URL to a PostgreSQL database. The server creates its schema (pilotoo_app) and tables on first boot, so there is no migration step to run. Conversations, checkpoints, run events, usage and tenant agents live there.

Run one server process per database. A second process on the same database would take the first one’s background tasks for abandoned ones and mark them interrupted.

Bootstrap

Your main.ts owns two things the module cannot do for you: the JSON body limit and HTTP CORS.

src/main.ts

import 'reflect-metadata';

import { NestFactory } from '@nestjs/core';
import type { NestExpressApplication } from '@nestjs/platform-express';
import { configureBodyLimit } from '@pilotoo/server';

import { AppModule } from './app.module';

const app = await NestFactory.create<NestExpressApplication>(AppModule);
configureBodyLimit(app);
app.enableCors({ origin: ['https://app.example.com'], credentials: false });
await app.listen(Number(process.env.PORT ?? 4317));

configureBodyLimit sizes the JSON limit for the largest body a route accepts, and leaves the model gateway’s two passthrough routes unparsed until the caller is known. Restrict origin to your own sites instead of the origin: true the demos use.

Note

The Socket.IO gateway has its own CORS setting, fixed at origin: true without credentials. Browsers are therefore not stopped from connecting by origin; the gateway relies on the identity check.

Identity

With no identity configured, every caller is the local owner. Never expose a server like that. Either set AUTH_IDENTITY_URL to an endpoint of your own auth, or pass an identityResolver to forRoot. See Authentication.

Configuration folders

Pin PILOTOO_CONFIG_DIR, AGENT_SKILLS_DIR and AGENT_WORKSPACE_DIR to absolute paths that ship with your deployment. Without them the kit searches upward from its own files, which fails once it is installed under node_modules. See Configuration.

Behind a proxy

The gateway accepts WebSocket connections only; it does not fall back to HTTP long polling. Your proxy must pass the Upgrade and Connection headers and allow long-lived connections. A run streams for as long as the agent works, so do not give the proxy a short idle timeout.

The same server also serves the REST routes. GET /health is anonymous and suits a load balancer’s health check. GET /protocol is anonymous and returns the protocol version.

Next steps

• Authentication
• Storage
• Local backend hosting