Server Auto-Start — From Specs to Running Server

One command to go from YAML specs to a running HTTP server.

The Problem

Before v0.7.0, sysmara build gave you everything except a running server. You had YAML specs, generated route stubs in app/generated/, scaffolded capability handlers, entity interfaces, and policy enforcers. But to actually serve HTTP requests, you had to:

• Manually create a server.ts entry point
• Import every capability handler by hand
• Register each handler to the correct HTTP method and path
• Set up database connections, middleware, and error handling
• Keep all of this in sync whenever you added or removed capabilities

This was busywork that contradicted SysMARA's philosophy: if the framework knows your entire system graph, it should be able to wire the server itself.

sysmara start

A single command that takes your project from specs to a running HTTP server. No entry point to write, no routes to register, no imports to manage.

npx sysmara start

What happens under the hood:

1. Parse specs — reads all YAML files from system/ and validates them
2. Connect to database — uses the adapter configured in sysmara.config.yaml
3. Apply schema — ensures database tables match entity definitions
4. Discover handlers — scans app/capabilities/ for exported handler functions
5. Auto-wire routes — maps each capability to an HTTP method and path using route inference
6. Start server — binds to the configured port and begins accepting requests

Zero boilerplate. Zero manual wiring. Add a new capability to your specs, run sysmara build to scaffold the handler, and sysmara start picks it up automatically.

Route Inference

SysMARA infers HTTP methods and paths from capability names. The convention uses the capability prefix and its bound entity to determine the route:

Entity names are automatically pluralized for the URL path. Capabilities that do not match a known prefix are mapped to POST /<capability_name> as a fallback.

Server Entry Point Generation

Starting with v0.7.0, sysmara build generates app/server.ts as a standalone entry point. This file wires the same auto-start logic into a single runnable script:

// app/server.ts (generated by sysmara build)

import { createServer, parseSpecDirectory } from '@sysmara/core';

const specs = await parseSpecDirectory('./system');
const server = await createServer({
  specs: specs.specs!,
  handlers: './app/capabilities',
  config: './sysmara.config.yaml',
});

await server.start();
console.log(`SysMARA server listening on ${server.port}`);

Key behaviors:

• Generated once, skipped if exists — like scaffold files, app/server.ts lives in the editable safe edit zone. Re-running build will not overwrite your customizations.
• Customizable for production — add custom middleware, configure CORS, attach monitoring, or swap the default HTTP adapter. The generated file is a starting point, not a locked artifact.
• Runnable directly — npx tsx app/server.ts starts the server without the CLI.

Example Output

Running sysmara start on a project with user and article capabilities:

$ npx sysmara start

  SysMARA v0.7.0 — starting server

  ✓ Parsed 2 entities, 5 capabilities, 3 policies, 2 invariants
  ✓ Connected to PostgreSQL (localhost:5432/myapp)
  ✓ Schema applied — 2 tables synced

  Routes:
    POST   /users        → create_user
    GET    /users        → list_users
    GET    /users/:id    → get_user
    PUT    /users/:id    → update_user
    DELETE /users/:id    → delete_user
    POST   /articles     → create_article
    GET    /articles     → list_articles
    GET    /articles/:id → get_article

  ✓ Server listening on http://localhost:3000

Development vs Production

The two modes serve different stages of the development lifecycle:

Use sysmara start during development for fast iteration. Deploy app/server.ts (compiled to JavaScript) in production for full control and no CLI dependency.