Skip to content

Starting the Apistry Server

This page explains how to start Apistry once you already understand the basics. It builds on the Overview and focuses on the two supported startup modes and when to use each.

If you have not yet run Apistry successfully, start with the Overview first.

Startup Modes (Free vs Licensed)

Apistry has two startup modes. Both start the same runtime engine; the difference is how configuration is supplied and what capabilities are enabled.

Mode Command Intended Use
Development / Evaluation apistry serve Local development, evaluation, quick iteration
Configured / Production apistry start Config-driven, licensed, production deployments

These modes represent a progression from exploration to production.

The Big Picture

Apistry is designed to be easy to evaluate and safe to operate in production.

  • Free mode prioritizes fast startup and low friction (no external dependencies required).
  • Licensed mode prioritizes explicit configuration and production-grade integrations.

These are not two different products. They are the same code, with different startup modes and capabilities enabled.

Licensing

Area Free Mode Licensed Mode
Startup serve start
Configuration file startup ❌ ✅
NeDB (in-memory + filesystem) ✅ ✅
MongoDB adapter ❌ ✅
Other DB adapters ❌ ✅
Included orchestration actions ✅ ✅
Custom orchestration actions ❌ ✅

Most users follow this path:

  1. Start in free mode

    • apistry serve
    • NeDB (in-memory or filesystem-backed)
    • iterate on contract shape and lifecycle behavior
    • if you make breaking model changes: load/replace the database

  2. Move to configured operation

    • purchase a license
    • introduce a config file
    • switch to apistry start (licensed)
    • make the environment reproducible
    • set up testing/staging environments

  3. Move to production persistence

    • adopt MongoDB or other licensed adapters
    • deploy with explicit configuration and operational controls

This progression preserves Apistry’s core idea: the contract remains the source of truth as you move from local to production.

apistry serve

Local Development Mode

apistry serve starts Apistry with minimal configuration and sensible defaults.

When to Use

  • Local development
  • Contract experimentation
  • Learning Apistry
  • Evaluating capabilities

Characteristics

  • No config file required
  • Uses built-in defaults
  • Supports NeDB (in-memory or filesystem-backed)
  • License not required
  • Fast startup with minimal friction

Basic Usage

apistry serve -c contracts

Optional database directory:

apistry serve -c contracts -d contracts/nedb

What Happens

When running in serve mode, Apistry:

  1. Loads OpenAPI contracts
  2. Validates contract structure
  3. Derives routes, schemas, and persistence behavior
  4. Starts the runtime server
  5. Exposes Swagger UI at /docs

This mode is intentionally simple and optimized for speed of iteration.

apistry start

Configured / Production Mode (Licensed)

apistry start runs the same runtime engine, but uses an explicit configuration file. This mode is required for licensed and production-grade deployments.

When to Use

  • Production environments
  • Explicit, repeatable configuration
  • Licensed features
  • Database adapters beyond NeDB
  • Custom orchestration actions

Characteristics

  • Requires a configuration file
  • Requires a valid license
  • Enables advanced adapters and extensions
  • Designed for controlled deployments

Basic Usage

apistry start -c config.yaml

Configuration Responsibility

In start mode:

  • All runtime behavior is explicit
  • Environment assumptions are eliminated
  • Configuration becomes part of deployment artifacts
  • The service is reproducible across environments

The configuration file defines:

  • contracts location
  • database connection
  • license files
  • logging behavior
  • orchestration custom actions
  • security settings
  • etc.

Database Backends

NeDB (Built-in)

NeDB is built into Apistry so you can run immediately.

You can use it as:

  • in-memory (fast, ephemeral)
  • filesystem-backed (persistent across restarts)

NeDB is intended for development and evaluation, and can also serve lightweight use cases.

MongoDB (Licensed Adapter)

MongoDB is supported through a licensed adapter for production scenarios, including:

  • externally managed persistence
  • multi-instance services
  • operational scaling and monitoring
  • event streaming and triggers
  • unique index management

MongoDB is optional. It is not required to start using Apistry.

What This Page Does Not Cover

This page intentionally avoids: - detailed CLI flag documentation - full configuration file schemas - licensing mechanics

Those topics are covered in: - CLI Reference - Configuration Reference

Summary

  • Apistry has one runtime, not two servers
  • Startup modes control how configuration is supplied
  • serve optimizes for speed and learning
  • start optimizes for control and production correctness

Once you understand the difference, choosing the correct mode becomes trivial.