openapi.yaml

openapi: 3.1.0

# The daemon's HTTP control API — what `spinloop daemon` always exposes, and what
# `spinloop serve --api` exposes alongside a foreground engine.
#
# This file is checked against the implementation by
# internal/daemon/openapi_test.go: the routes here must match the ones the
# handler registers, and each schema's properties must match the JSON tags of
# the Go struct it describes. The test compares names, not types — where the two
# could still disagree, the Go code is the source of truth.
#
# Prose on the behaviour a schema cannot express lives in docs/http-api.md.

info:
  title: spinloop daemon control API
  summary: Supervise and observe a local inference engine.
  description: |
    The control API drives one supervised inference engine: start it, stop it,
    ask what it is doing, and set what it serves next.

     It listens on `:4242` by default (`--api-addr` overrides; on the daemon,
     `--loopback` binds `127.0.0.1:4242`). A non-loopback
     listen with no bearer token configured refuses to start, since the API can
     start and stop processes; a loopback listen may go tokenless.

    Under `spinloop daemon` nothing runs until a start request asks, and stopping
    the engine never ends the daemon — the API keeps answering. Under
    `spinloop serve --api` the engine is foreground-managed, so start always
    fails as already-running and stopping the engine ends serve itself.
  license:
    name: MIT
    identifier: MIT
  version: "1"

servers:
  - url: http://127.0.0.1:4242
    description: The daemon's default loopback address.

security:
  - bearerAuth: []

tags:
  - name: engine
    description: Driving and observing the supervised engine.
  - name: config
    description: What the engine serves.

paths:
  /v1/status:
    get:
      tags: [engine]
      operationId: getStatus
      summary: Report the supervised engine's state and idle time.
      description: |
        `lastActiveAt` and `idleSeconds` are the daemon's own answer to whether
        the engine is busy, derived from token counters it samples every 15
        seconds. Both are absent until an engine has run.
      responses:
        "200":
          description: The engine's current state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/start:
    post:
      tags: [engine]
      operationId: startEngine
      summary: Start the engine.
      description: |
        The body may carry a deploy config naming what to run, and the key the
        engine is gated with — validated and persisted exactly as a push, then
        started. With no body, the stored deploy config is served, gated with
        the stored key; with nothing stored, the start fails saying so.

        A body sent with a rejected start is not stored, neither its config nor
        its key.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StartRequest"
      responses:
        "200":
          description: The engine started; the reply is its new state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "400":
          description: |
            The config is invalid, the engine failed to start, there is nothing
            to serve, or a key was supplied for an engine that cannot be gated
            by one.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: An engine is already running. Nothing changed, and a carried config was not stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1/stop:
    post:
      tags: [engine]
      operationId: stopEngine
      summary: Stop the engine.
      description: |
        Idempotent: stopping when nothing runs succeeds. Under `spinloop daemon`
        this never ends the daemon itself.
      responses:
        "200":
          description: The engine is stopped; the reply is its new state.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          description: The engine could not be stopped.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /v1/metrics:
    get:
      tags: [engine]
      operationId: getMetrics
      summary: Return collected engine and host metrics.
      description: |
        Engine token counters scraped from the engine's own Prometheus endpoint,
        plus host GPU, CPU and memory figures. Every stat is optional: a host
        with no source for one simply omits it, so a machine without
        `nvidia-smi` reports engine stats and no GPU figures.
      responses:
        "200":
          description: The collected stats.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Stats"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/logs:
    get:
      tags: [engine]
      operationId: getLogs
      summary: Return a slice of the engine's captured output.
      description: |
        The supervised engine's stdout and stderr, as captured to the file
        `/v1/status` reports as `logPath`. Read-only: it never touches the
        engine, so it answers whether the engine is running, stopped or
        crashed — the last of which is when it is wanted most.

        Reads are always bounded. Omit `offset` to read the **end** of the log;
        pass the `nextOffset` from a previous reply to receive only what has
        been appended since, which makes following exact — no overlap window
        and no de-duplication. Nothing rotates this file, so it grows for the
        daemon's lifetime and a full read is never offered.
      parameters:
        - name: offset
          in: query
          required: false
          description: |
            Byte position to read from, normally the `nextOffset` of a previous
            reply. Omitted, the end of the log is returned.
          schema:
            type: integer
            format: int64
            minimum: 0
        - name: limit
          in: query
          required: false
          description: |
            Maximum bytes to return. Capped by the daemon regardless of what is
            asked for; omitted, a default slice is returned.
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: The requested slice of the log.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LogsResponse"
        "400":
          description: A query parameter was not a whole number, or was negative.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /v1/deploy-config:
    put:
      tags: [config]
      operationId: putDeployConfig
      summary: Set what the next start serves.
      description: |
        A running engine is deliberately untouched — the config takes effect on
        the next start, which the reply says.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeployConfig"
      responses:
        "200":
          description: The config was stored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Message"
        "400":
          description: The config is invalid or names a runner this host cannot serve.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        The token comes from the `SPINLOOP_API_TOKEN` environment variable —
        reachable through the Spinloop's adjacent `.env` — never from a flag, so
        the secret stays out of the process table. When no token is configured
        the API is unauthenticated, which `Listen` permits only on loopback.

  responses:
    Unauthorized:
      description: The bearer token is missing or wrong.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    StartRequest:
      type: object
      description: |
        The body of a start request: what to run, and the key the engine is
        gated with. Mirrors Go's daemon.StartRequest, which embeds a
        DeployConfig.
      allOf:
        - $ref: '#/components/schemas/DeployConfig'
        - type: object
          properties:
            engineApiKey:
              type: string
              description: |
                The API key the engine is started with. Supplied by the caller
                — a node sources no key of its own — and travelling with the
                config it accompanies: a start carrying a config and no key
                opens the engine, while a start carrying neither reuses what
                was stored.

                It is never returned. No reply, error, or log line produced by
                this API contains it, and the daemon passes it to the engine
                as a file path rather than an argument, so it does not appear
                in the node's process list either.

    StatusResponse:
      type: object
      description: The supervised engine's state. Mirrors Go's daemon.StatusResponse.
      required: [state]
      properties:
        state:
          type: string
          enum: [idle, running, stopped, crashed]
          description: |
            `idle` means nothing has been started yet; `crashed` means the
            engine exited unprompted, and is reported rather than restarted.
        runner:
          type: string
          description: The engine being served, when known.
          examples: [llamacpp, omlx, vllm, mtplx]
        model:
          type: string
          description: What it is serving, when known.
        servedName:
          type: string
          description: |
            The name the engine answers to — the served name its deploy config
            or Spinloop set — reported beside `model` when set. An aliased
            engine answers to both, and a caller may know either.
        uptimeSeconds:
          type: integer
          description: How long the engine has been running. Zero unless running.
        logPath:
          type: string
          description: The engine's log file, when running under the daemon.
        lastActiveAt:
          type: string
          format: date-time
          description: |
            When the engine last did any work, RFC 3339. Moved forward by a
            sample showing requests in flight or a moved counter, and by an
            engine start. Absent until an engine has run.
        idleSeconds:
          type: integer
          description: Seconds since `lastActiveAt`. Absent when that is.
        engine:
          allOf:
            - $ref: '#/components/schemas/EngineEndpoint'
          description: |
            Where the running engine answers inference requests. Absent unless
            an engine is running.
        ready:
          type: string
          enum: [ready, not-ready]
          description: |
            Whether the running engine last answered its own health check,
            distinct from `state` reaching `running` — the process can be
            alive while still loading weights. Absent, not `not-ready`, when
            it does not apply: no engine is running, the running engine's
            runner has no known health-check convention, or this daemon
            predates the check. Mirrored on Stats' `ready`, from the same
            record.
        version:
          type: string
          description: |
            The spinloop binary's build-time version string, from
            `main.version`. Set to "dev" when not overridden at build time.

    EngineEndpoint:
      type: object
      description: |
        Where the supervised engine serves. Parts rather than a URL on
        purpose: the daemon knows its engine binds `127.0.0.1:8080`, which is
        useless to anyone else, and it cannot know the name a client reaches
        this host by — a LAN name, a tailscale name, a published container
        port. The caller composes these against the host it already has. A node
        that does know that name — a cloud environment, whose control plane
        publishes the instance's address — reports it in `host`.
      required: [port]
      properties:
        host:
          type: string
          description: |
            The name or address a client reaches the engine by, when the node
            knows it. A daemon leaves it absent; a cloud environment's status
            fills it with the instance's published address.
        port:
          type: integer
          description: |
            The port the engine listens on — the engine's, never the control
            API's. One is not derivable from the other.
          examples: [8080, 8000]
        path:
          type: string
          description: |
            The OpenAI-compatible path prefix, when it is not the usual `/v1`.
            Absent means the default.
        loopbackOnly:
          type: boolean
          description: |
            The engine is bound to loopback, so it answers only on that
            machine. Lets a remote caller explain a refused connection rather
            than merely suffer it.
        requiresKey:
          type: boolean
          description: |
            The engine was started with an API key, so a caller needs one. The
            key itself is never reported under any endpoint: authorisation to
            drive a node is not authorisation to be handed its engine's
            credential.

    Stats:
      type: object
      description: Collected engine and host metrics. Mirrors Go's metrics.Stats.
      required: [state]
      properties:
        state:
          type: string
          enum: [idle, running, stopped, crashed]
        runner:
          type: string
        modelId:
          type: string
        servedName:
          type: string
          description: |
            The name the engine answers to beside the model id, mirroring
            StatusResponse's `servedName` from the same record — so a caller
            resolving a stopped host's model from its metrics gets the same
            name a running host reports on its status.
        uptimeSeconds:
          type: integer
        tokens:
          $ref: "#/components/schemas/TokenStats"
        gpus:
          type: array
          items:
            $ref: "#/components/schemas/GpuStat"
        cpu:
          $ref: "#/components/schemas/CpuStat"
        memory:
          $ref: "#/components/schemas/MemoryStat"
        speed:
          type: number
          description: |
            The engine's own generation rate in tokens per second, parsed
            from the timing lines it prints into its captured output
            (llama.cpp's print_timing `tg` figure today). Present only while
            the engine runs and has printed a figure within the last sampler
            interval; absent — never zero — for a stopped or quiet engine, an
            engine that prints no rate, and a daemon that predates the
            figure.
        history:
          type: array
          description: |
            The retained system readings, oldest first — one per sampler tick
            while an engine ran, covering at most the last 10 minutes. They
            survive a stop (the readings up to the stop say what the engine
            was doing until it stopped) and clear when the next engine
            starts. Absent where no reading has been taken, on the same
            absence-not-zero terms as the rest of the reply.
          items:
            $ref: "#/components/schemas/HistorySample"
        errors:
          type: array
          description: Collection failures. An absent source is omitted rather than reported here.
          items:
            type: string
        lastActiveAt:
          type: string
          format: date-time
          description: |
            When the engine last did any work, RFC 3339. The same value
            `/v1/status` reports, from the same record. Reported whatever the
            engine's state — a stopped engine still says when it last worked,
            even though the figures above are absent. Absent until an engine
            has run.
        idleSeconds:
          type: integer
          description: Seconds since `lastActiveAt`. Absent when that is, and absent at zero.
        ready:
          type: string
          enum: [ready, not-ready]
          description: |
            Whether the running engine last answered its own health check.
            The same value `/v1/status` reports, from the same record.
            Absent, not `not-ready`, when it does not apply: no engine is
            running, its runner has no known health-check convention, or
            this daemon predates the check.
        retainUntil:
          type: string
          format: date-time
          description: |
            The environment's retention deadline, RFC 3339: the idle sweep
            will not terminate the instance before it. A property of the cloud
            instance, not the engine, so it is absent for local daemon nodes
            and for cloud environments without an update URL. The stats reply
            carries it only while it is a time in the future — a passed
            deadline keeps nothing, so it is dropped there and on this read.

    TokenStats:
      type: object
      description: Per-engine token and request counters, read from its Prometheus endpoint.
      properties:
        running:
          type: integer
          description: Requests in flight (processing plus waiting/deferred).
        counter:
          type: integer
          description: The sum of the engine's cumulative counters — the activity signal.
        promptTokens:
          type: integer
        generationTokens:
          type: integer
        requests:
          type: integer
          description: |
            The engine's cumulative request counter, present only where the
            engine exposes one — vLLM's request_success_total. Absent for an
            engine family whose metrics carry no cumulative request count
            (llama.cpp's, today): a missing figure is not a zero, it is a
            counter the engine never produced.

    GpuStat:
      type: object
      description: One GPU's figures, from nvidia-smi.
      properties:
        index:
          type: integer
        name:
          type: string
          examples: ["NVIDIA L40S"]
        utilization:
          type: integer
          description: Percent.
        memoryUsed:
          type: integer
          description: Bytes.
        memoryTotal:
          type: integer
          description: Bytes.
        temperature:
          type: integer
          description: Degrees Celsius.

    CpuStat:
      type: object
      description: Whole-host CPU utilisation.
      properties:
        utilization:
          type: number
          description: Percent.

    MemoryStat:
      type: object
      description: System memory, in bytes.
      properties:
        total:
          type: integer
        used:
          type: integer

    HistorySample:
      type: object
      description: |
        One retained reading of the host's figures, as the bar format plots
        it: a 0-100% figure per series rather than the raw one. The field
        names are one letter each because the readings ride the remote relay
        over SSM, whose command output truncates at 4KB — forty samples of
        the window must fit that budget alongside the current reading.
      required: [t]
      properties:
        t:
          type: integer
          description: When the reading was taken, unix seconds.
        c:
          type: number
          description: Whole-host CPU utilisation, percent.
        m:
          type: number
          description: System memory used over total, percent.
        s:
          type: number
          description: |
            The engine's generation rate in tokens per second, from the
            timing lines its output carried during this tick's interval.
            Absent where the engine printed no figure since the previous
            tick — silence means nothing was generated, not a rate of zero.
        g:
          type: array
          items:
            $ref: "#/components/schemas/HistoryGPU"

    HistoryGPU:
      type: object
      description: One GPU's figures in a retained reading, one-letter fields as its parent.
      required: [i, u]
      properties:
        i:
          type: integer
          description: The GPU's index.
        u:
          type: integer
          description: Utilisation, percent.
        m:
          type: number
          description: Memory used over total, percent. Absent where the GPU reports no total.

    DeployConfig:
      type: object
      description: |
        What to serve, in the same shape `spinloop cloud deploy` derives from an
        Spinloop. Mirrors Go's remote.DeployConfig. There is no default runner: an
        unset or invalid one fails loudly rather than guessing.
      required: [runner]
      properties:
        runner:
          type: string
          # The engines a deploy config can name. mtplx appears because a fleet
          # node can be woken with it; it is not a cloud runner (no machine
          # image). omlx is not a wakeable runner yet.
          enum: [llamacpp, vllm, mtplx]
        modelId:
          type: string
          description: The weights to serve — a Hugging Face repo, or a local path on the instance.
        quant:
          type: string
          description: The quantisation to select, where the runner takes one.
        contextSize:
          type: integer
        parallel:
          type: integer
          description: |
            The number of concurrent request slots the engine should run
            with. Zero/absent means unset: no parallelism flag is added, and
            contextSize is used unscaled. Translated into each runner's own
            flag at start time — llamacpp's ctx-size is scaled by this value,
            since llama.cpp divides that budget across its parallel slots;
            vllm's context is left unscaled, since its concurrency is bounded
            independently via max-num-seqs.
        servedModelName:
          type: string
          description: The name the endpoint advertises the model under.
        serveArgs:
          type: array
          description: Runner-specific flags, pre-tokenised.
          items:
            type: string
        companions:
          type: object
          description: |
            Companion weights loaded beside the main weights, keyed by role.
            Each value is a bare filename within the model's own Hugging Face
            repo, never a path — the deployment decides where it lands on disk
            and names it there itself. Omitted when there are none.
          additionalProperties:
            type: string
          propertyNames:
            enum: [draft, mmproj]
        spinloopVersion:
          type: string
          description: |
            The spinloop release the environment's instances install at boot.
            Empty or absent means the boot installs the latest published
            release. A pin is normalised before it is sent — the leading v
            of a release tag is not part of the version (1.26.1, not
            v1.26.1). The environment's control plane reads it when it
            renders the boot script; the daemon does not act on it.
        instanceType:
          type: string
          description: |
            The EC2 instance type the environment's instances launch as — a
            family and size separated by a dot (g6e.xlarge). Empty or absent
            means launch as the control plane's default type. A property of
            the deployment: the environment's control plane reads it when it
            launches a fresh instance; a re-wake of a stopped instance keeps
            the type it launched with. The daemon does not act on it.

    Message:
      type: object
      description: A plain acknowledgement, where there is nothing to report but acceptance.
      required: [message]
      properties:
        message:
          type: string

    LogsResponse:
      type: object
      description: |
        A bounded slice of the engine's captured output, with the cursor needed
        to read on from it.
      required: [content, nextOffset, size]
      properties:
        content:
          type: string
          description: The slice of the log that was read.
        nextOffset:
          type: integer
          format: int64
          description: |
            The position immediately after `content`. Pass it back as `offset`
            to receive only what has been appended since.
        size:
          type: integer
          format: int64
          description: The log's current length, so a caller can see how far behind it is.
        path:
          type: string
          description: The log file being read, matching `logPath` from status.
        missing:
          type: boolean
          description: |
            There is no log file: no engine has ever run here, or the daemon
            forwards engine output to its own stdio. Distinct from a log that
            exists and is empty.
        staleOffset:
          type: boolean
          description: |
            The requested `offset` is past the end of the log — it was truncated
            or replaced — so resume from `nextOffset` rather than waiting for a
            position that will never arrive.

    Error:
      type: object
      description: The failure reply. Every non-2xx status carries one.
      required: [error]
      properties:
        error:
          type: string