start()

Start a server from a configuration object. Returns a SimpleServer carrying the resolved URL and a stop() method.

import { start } from 'sovrium'

const server = await start({ name: 'my-app' })

console.log(`Server running at ${server.url}`)

start validates the config against AppSchema before binding anything. An invalid config rejects with a Sovrium failed to start: error naming the failing path — it never starts a half-configured server.

StartOptions

The optional second argument. Every property has a working default, so start(app) alone is valid.

Property	Description
port	Port number, 0–65535. 0 binds an available port. Default: 3000.
hostname	Interface to bind. Default: localhost.
publicDir	Static file directory. Files are served at their relative path.
configPath	Path to the config file, recorded in the lock file for restart and reload.
configHash	Hash of the config content, used to detect changes on reload.

The last two exist for the CLI's own lifecycle commands. Set them only if you are reimplementing restart/reload yourself; otherwise leave them alone.

import { start } from 'sovrium'

const server = await start(
  {
    name: 'my-app',
    tables: [
      {
        id: 1,
        name: 'tasks',
        fields: [
          { id: 1, name: 'title', type: 'single-line-text', required: true },
          { id: 2, name: 'done', type: 'checkbox' },
        ],
      },
    ],
  },
  {
    port: 8080,
    hostname: '0.0.0.0',
    publicDir: './public',
  }
)

Binding to a free port

Passing port: 0 lets the OS pick. This is the reliable pattern for tests and for several instances on one machine — read the real port back off server.url rather than assuming one:

const server = await start({ name: 'test-app' }, { port: 0 })

const response = await fetch(`${server.url}/api/health`)
console.log(response.status) // 200

await server.stop()

Shutting down

stop() resolves once shutdown is complete, so an await is enough to sequence teardown:

const server = await start({ name: 'my-app' })

process.on('SIGTERM', async () => {
  await server.stop()
  process.exit(0)
})

Related Pages

• TypeScript API Overview — AppConfig and the other functions.
• Type Reference — SimpleServer and the config types.
• Lifecycle Commands — the same behaviour from the CLI.
• Environment Variables — PORT and the rest of the runtime inputs.