Skip to content

api.md

Latest commit

 

History

History
179 lines (134 loc) · 4.31 KB

api.md

File metadata and controls

179 lines (134 loc) · 4.31 KB
Raw

API Reference

Authoritative reference for Ignite CLI and HTTP endpoints.

CLI

ignite init <name>

Initialize a new service scaffold.

ignite init <name> [options]

Options:

  • -p, --path <path>: custom output path (defaults to name)
  • -r, --runtime <runtime>: runtime spec (default bun)

ignite run <service>

Execute a service inside a virtualized microVM sandbox.

ignite run <service> [options]

Options:

  • -i, --input <json>: JSON-serialized payload sent to guest runtime.
  • -r, --runtime <runtime>: runtime spec override.
  • --skip-preflight: run preflight checks but do not block execution on failure.
  • --json: output execution report in JSON format.
  • --verbose: show sub-millisecond timings of all microVM lifecycle phases.
  • --memory <mb>: override RAM allocation limit (in MB) assigned to the VM.
  • --cpus <cores>: override CPU cores assigned to the VM.
  • --kernel <path>: path to custom guest vmlinux kernel.
  • --rootfs <path>: path to custom guest rootfs disk.
  • --runtimes-root <path>: path to custom host language runtimes folder.
  • --vsock-port <port>: custom host-guest VSOCK communication port.
  • --console-out <path>: file path to log guest serial console outputs.
  • --audit / --audit-output <path>: not implemented; returns an error. See Threat Model for the isolation that is enforced.

ignite preflight <service>

Run preflight validators without execution.

ignite preflight <service>

Exit behavior:

  • exits with code 0 on pass/warn statuses, and code 1 on fail.

ignite serve

Start HTTP REST API server.

ignite serve [options]

Options:

  • -p, --port <port>: API port (default 3000)
  • -h, --host <host>: host or IP to bind (default localhost)
  • -s, --services <path>: path to services root folder (default ./services)

Environment:

  • IGNITE_API_KEY: when set, every endpoint except /health requires Authorization: Bearer <key>. When unset, the server executes services for any caller that can reach it and logs a warning at startup — keep the bind address on localhost in that case.
  • IGNITE_CORS_ORIGINS: comma-separated list of exact allowed origins (e.g. https://app.example.com). When unset, no CORS headers are sent at all, which blocks browser-based cross-origin access by default.
  • IGNITE_KERNEL_PATH, IGNITE_ROOTFS_PATH, IGNITE_RUNTIMES_ROOT: override the guest kernel, rootfs image, and runtimes directory.

Requests are rate limited to 60 per minute per client IP, keyed on the real transport peer address (not the spoofable X-Forwarded-For header). If you run Ignite behind a reverse proxy, apply per-client limits at the proxy.

HTTP REST API

GET /health

Response:

{
  "status": "ok",
  "version": "0.9.0"
}

/health is the only endpoint that does not require authentication.

GET /services

List service folders under the configured services path root.

Response:

{
  "services": ["hello-world", "data-processor"]
}

POST /services/:serviceName/execute

Execute service inside microVM sandbox.

Request body:

{
  "input": { "data": [1, 2, 3] },
  "skipPreflight": false,
  "audit": false
}

audit must be false or omitted. Security audit mode is not implemented; sending true returns an error rather than silently reporting an audit that never ran.

coldStartTimeMs is present only when the guest runtime emits an IGNITE_INIT_TIME: line on stderr, and memoryUsageMb likewise depends on an IGNITE_MEMORY_MB: line. Both are omitted or zero otherwise rather than estimated.

Response:

{
  "success": true,
  "serviceName": "data-processor",
  "metrics": {
    "executionTimeMs": 85,
    "memoryUsageMb": 34.2,
    "coldStart": true,
    "coldStartTimeMs": 14,
    "exitCode": 0,
    "stdout": "...",
    "stderr": "..."
  },
  "preflight": {
    "serviceName": "data-processor",
    "timestamp": "2026-06-27T17:33:00.000Z",
    "checks": [
      {
        "name": "dependency-count",
        "status": "pass",
        "message": "Low dependency count (0)",
        "value": 0,
        "threshold": 50
      }
    ],
    "overallStatus": "pass"
  }
}

Error response:

{
  "success": false,
  "serviceName": "data-processor",
  "error": "Detailed error message"
}