Titan vs Omnitron

These are two distinct layers. Most projects use Titan alone — it's a complete backend framework. Omnitron is opt-in — a higher-level platform that supervises, deploys, and operates many Titan apps together.

This page draws the line precisely so you know what to install and what to skip.

At a glance

flowchart TB
  subgraph Titan["Titan — backend framework (always)"]
    direction LR
    App["Application.create(module)"]
    DI[Nexus DI container]
    Net[Netron RPC<br/>HTTP / WS / TCP / Unix]
    Lif[Lifecycle hooks]
    Mods[14 modules: auth, cache, db, ...]
  end

  subgraph Omnitron["Omnitron — supervisor + control plane (opt-in)"]
    direction LR
    Daemon[Long-running daemon]
    CLI[75+ CLI commands]
    Console[Web console]
    Infra[Declarative infra provisioning]
    Cluster[Cluster + fleet]
    MCP[MCP server for AI agents]
  end

  Titan -. you can use this alone .-> Run1[node dist/index.js]
  Titan --> Omnitron
  Omnitron --> Run2[omnitron up — supervises N Titan apps]

  classDef titan fill:#e8f5e9,stroke:#43a047,color:#1b5e20
  classDef omni fill:#f3e5f5,stroke:#8e24aa,color:#4a148c
  class Titan titan
  class Omnitron omni

Titan = the runtime. Build a backend, expose RPC, run it.

Omnitron = the operator. Supervise many backends, provide the operator UI / CLI / agent surface.

Titan alone (no Omnitron)

@omnitron-dev/titan is a self-contained backend framework. You can build a complete production service with just Titan + the modules you need. No daemon, no extra runtime, no operator overhead — just a Node process.

// my-app/src/main.ts — that's the whole entrypoint
import { Application, Module, Service } from '@omnitron-dev/titan';
import { Public } from '@omnitron-dev/titan/decorators';
import { TitanDatabaseModule } from '@omnitron-dev/titan-database';
import { TitanAuthModule }     from '@omnitron-dev/titan-auth';

@Service('users@1.0.0')
class UsersService {
  @Public()
  async findById(id: string) { /* ... */ }
}

@Module({
  imports: [
    TitanDatabaseModule.forRoot({
      connection: { dialect: 'postgres', connection: env.DATABASE_URL },
    }),
    TitanAuthModule.forRoot({ jwtSecret: env.JWT_SECRET }),
  ],
  providers: [UsersService],
})
class AppModule {}

const app = await Application.create(AppModule, {
  netron: { http: { port: 3000 } },
});

await app.start();
process.on('SIGTERM', () => app.stop());

Run with:

node dist/main.js

You get everything:

This is a complete stack. Run it under any process supervisor: PM2, systemd, Docker, Kubernetes, Fly, Railway, Render — Titan is just a Node process.

What Omnitron adds

@omnitron-dev/omnitron is an optional higher-level platform that uses Titan internally (it's itself a Titan app) and supervises other Titan apps.

Adds, on top of what Titan already gives you:

It's not "Titan with extras" — it's a separate platform that happens to use Titan as its runtime substrate.

When you need Omnitron

Reach for Omnitron when any of these apply:

• ≥ 2 Titan apps to start, stop, and inspect together.

• Multi-environment — dev / staging / prod stacks on the same host without container orchestration.

• Multi-node fleet — coordinate apps across machines from one operator surface.

• Web console — you want a UI for ops, not just a CLI.

• Declarative infra — omnitronConfig: { database: true, redis: true, s3: true } and forget about provisioning.

• AI agent integration — omnitron kb mcp for agents to drive the platform.

• Operator-level RBAC — three roles (viewer / operator / admin) on top of your app's user auth.

When you don't

Omnitron is overkill for:

• Single Titan app running on one box — node dist/main.js is fine.

• Already containerised — if Docker Compose / Kubernetes / Fly is your supervisor, Omnitron's supervision overlaps. Run the Titan apps directly in containers.

• Edge / serverless — Cloudflare Workers, Deno Deploy, AWS Lambda. Omnitron daemon assumes Node + Unix sockets; doesn't fit these runtimes.

• Single-purpose microservice — one team, one service, one deploy. The framework overhead doesn't pay back.

• Smaller projects (≤ 2 apps, single team) — Titan + your preferred process manager is simpler.

Migration paths

Start with Titan alone

pnpm add @omnitron-dev/titan
# ... add modules as needed
node dist/main.js

Add Omnitron later

The same Titan app runs unchanged under Omnitron. Just add the ecosystem config:

// omnitron.config.ts (new file at repo root)
import { defineEcosystem } from '@omnitron-dev/omnitron';

export default defineEcosystem({
  apps: [
    { name: 'api', bootstrap: './apps/api/dist/bootstrap.js' },
  ],
});

Convert main.ts to bootstrap.ts:

// apps/api/src/bootstrap.ts — was main.ts
import { defineSystem } from '@omnitron-dev/omnitron';

export default defineSystem({
  name:    'api',
  version: '1.0.0',
  processes: [
    {
      name:   'http',
      module: './app.module.js',
      transports: { http: { port: 3000 } },
    },
  ],
});

Run:

omnitron up                      # starts daemon + api

The Titan app's source — @Service, @Module, @Public, business logic, modules — does not change. The same Netron endpoints work; clients keep working without modification.

Drop Omnitron later

Equally easy in reverse: replace omnitron up with node dist/main.js (using the original main.ts-style boot) or with your container orchestrator. Titan keeps running.

Cost comparison

What the docs cover for each

Real numbers

A small project (one Titan app, single Postgres, two HTTP routes):

For 1 app: the ratio is bad. For 5 apps: same daemon, ~150 MB total vs 5 × 80 = 400 MB if each apps' supervision was duplicated.

TL;DR

Titan is the framework. You probably need it.

Omnitron is the platform. You probably don't — until you do.

See also

• Architecture — how Titan composes

• Principles — the rules behind both layers

• Comparison — how the whole stack compares to alternatives

• Omnitron overview — if you've decided you want Omnitron

• Deployment — how to ship either way