> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tai42.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Merge env overrides and reload the fleet

> Merge env overrides into the stored config and reload this worker and the fleet.

A hot-class key is re-read in place. A recycle-class key rolls a worker recycle across the
fleet on a supervised deployment: the response's ``recycle`` carries the roll's rows (``null``
when the change carried no recycle-class key), and when the roll converged this worker
recycles itself after replying — on the HTTP edge and on every projected tool door alike (a
post-reply graceful self-exit its supervisor respawns).
A change the deployment cannot carry is refused with a 400 before anything is written, naming
the key: a recycle-class key on a bare (unsupervised) deployment, and the bus URL or a key the
deployment pins on every shape.

``secret_keys`` (when not ``None``) replaces the operator's secret marks in the same write;
the marks variable itself is never accepted as an ``env`` key.

Called over MCP, the reload answers on the session that called it and then retires that session with
the generation it ran on: a later call on the same session fails (streamable HTTP answers it 404,
and an SSE session's stream closes), so the client starts a new session to go on.



## OpenAPI

````yaml /openapi.json post /api/config/env
openapi: 3.1.0
info:
  description: >-
    The operator HTTP surface served under /api/*. The platform's core routes.
    Plugin routes are published by each plugin.
  title: tai42-skeleton API
  version: 23.0.0
servers: []
security: []
paths:
  /api/config/env:
    post:
      tags:
        - config
      summary: Merge env overrides and reload the fleet
      description: >-
        Merge env overrides into the stored config and reload this worker and
        the fleet.


        A hot-class key is re-read in place. A recycle-class key rolls a worker
        recycle across the

        fleet on a supervised deployment: the response's ``recycle`` carries the
        roll's rows (``null``

        when the change carried no recycle-class key), and when the roll
        converged this worker

        recycles itself after replying — on the HTTP edge and on every projected
        tool door alike (a

        post-reply graceful self-exit its supervisor respawns).

        A change the deployment cannot carry is refused with a 400 before
        anything is written, naming

        the key: a recycle-class key on a bare (unsupervised) deployment, and
        the bus URL or a key the

        deployment pins on every shape.


        ``secret_keys`` (when not ``None``) replaces the operator's secret marks
        in the same write;

        the marks variable itself is never accepted as an ``env`` key.


        Called over MCP, the reload answers on the session that called it and
        then retires that session with

        the generation it ran on: a later call on the same session fails
        (streamable HTTP answers it 404,

        and an SSE session's stream closes), so the client starts a new session
        to go on.
      operationId: post_api_config_env
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    $ref: '#/components/schemas/ApplyResponse'
                required:
                  - data
                type: object
          description: Success.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Malformed request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Missing or invalid api key.
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadingError'
          description: The server is applying a config reload; retry shortly.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
components:
  schemas:
    EnvUpdate:
      additionalProperties: false
      description: >-
        An env write: overrides merged into the stored env, and optionally the
        whole set of secret marks.


        ``env`` maps names to string values (``""`` deletes a name).
        ``secret_keys`` absent or

        ``null`` leaves the stored marks untouched; a list REPLACES them (``[]``
        deletes them).
      properties:
        env:
          additionalProperties:
            type: string
          title: Env
          type: object
        secret_keys:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          default: null
          title: Secret Keys
      required:
        - env
      title: EnvUpdate
      type: object
    ApplyResponse:
      description: >-
        The standard mutation-op response: this worker's local reload result
        merged with the fleet fan-out summary.


        ``env_keys`` is the count of env keys the reload loaded. ``recycle`` is
        the fleet recycle

        roll the change ran — ``null`` when it carried no recycle-class key.
        ``awaiting_respawn`` is

        the operation's verdict: the workers still awaiting a respawn after it
        (name + keys) — empty

        when the change rolled a recycle that converged and this worker recycles
        itself; a worker the

        roll did not reach, and every listed worker of a change that rolls
        nothing, keep their keys.
      properties:
        awaiting_respawn:
          items:
            $ref: '#/components/schemas/AwaitingWorker'
          title: Awaiting Respawn
          type: array
        env_keys:
          title: Env Keys
          type: integer
        fanout:
          $ref: '#/components/schemas/FanoutSummary'
        recycle:
          anyOf:
            - $ref: '#/components/schemas/RecycleRoll'
            - type: 'null'
          default: null
        status:
          title: Status
          type: string
      required:
        - status
        - env_keys
        - fanout
      title: ApplyResponse
      type: object
    Error:
      properties:
        code:
          description: >-
            Stable machine-readable reason a client keys a dedicated error state
            on, present on refusals that opt in (e.g. a 501 not-configured
            refusal). Optional: absent when the error carries only a
            human-readable message.
          type: string
        error:
          type: string
      required:
        - error
      type: object
    ReloadingError:
      properties:
        error:
          const: reloading — the server is applying a config reload; retry shortly
          type: string
        reloading:
          const: true
          type: boolean
      required:
        - error
        - reloading
      type: object
    AwaitingWorker:
      description: >-
        One worker an operation names as still awaiting a respawn.


        Its recycle-class ``keys`` changed in the stored env since its process
        bound them (at boot, or

        when the plugin that declares them was loaded), and nothing in the
        operation respawns it.
      properties:
        keys:
          items:
            type: string
          title: Keys
          type: array
        name:
          title: Name
          type: string
      required:
        - name
        - keys
      title: AwaitingWorker
      type: object
    FanoutSummary:
      description: >-
        The mode-tagged fan-out summary embedded under a mutation response's
        ``fanout`` field.


        ``mode`` selects the shape: ``local-only`` carries only ``note`` (a lone

        worker reached no sibling); ``fleet`` and ``unreachable`` carry the
        per-worker

        broadcast report
        (``op``/``reachable``/``local_only``/``results``/``error``),

        the ``unreachable`` variant having no worker list, only ``error``. The

        mode-variant fields are optional so one model describes every mode
        without

        reshaping any wire payload.
      properties:
        error:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Error
        local_only:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Local Only
        mode:
          title: Mode
          type: string
        note:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Note
        op:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Op
        reachable:
          anyOf:
            - type: boolean
            - type: 'null'
          default: null
          title: Reachable
        results:
          anyOf:
            - items:
                $ref: '#/components/schemas/FanoutWorkerResult'
              type: array
            - type: 'null'
          default: null
          title: Results
      required:
        - mode
      title: FanoutSummary
      type: object
    RecycleRoll:
      description: >-
        The report of a fleet recycle roll an env change carrying a
        recycle-class key ran.


        ``recycle`` the worker lines of the roll (the writer's own
        ``self-deferred`` line when its

        post-response self-exit is armed); ``fresh`` the new ready lives seen
        since the change began;

        ``recycle_stopped`` is ``null`` when the roll ran to its end, otherwise
        where it stopped and

        why. Names only — never env values.
      properties:
        fresh:
          items:
            $ref: '#/components/schemas/FreshLife'
          title: Fresh
          type: array
        recycle:
          items:
            $ref: '#/components/schemas/RecycleEntry'
          title: Recycle
          type: array
        recycle_stopped:
          anyOf:
            - $ref: '#/components/schemas/RecycleStop'
            - type: 'null'
          default: null
      required:
        - recycle
        - fresh
      title: RecycleRoll
      type: object
    FanoutWorkerResult:
      description: >-
        One worker's verdict within a multi-worker fan-out report.


        ``payload`` carries a query op's per-worker data; ``error`` a failed
        apply's

        message; ``detail`` the publisher's note for a computed
        missing/departed/

        timed-out verdict. ``outcome`` is the worker's terminal outcome as its
        wire

        string.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        error:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Error
        name:
          title: Name
          type: string
        outcome:
          title: Outcome
          type: string
        payload:
          anyOf:
            - $ref: '#/components/schemas/JsonValue'
            - type: 'null'
          default: null
      required:
        - name
        - outcome
      title: FanoutWorkerResult
      type: object
    FreshLife:
      description: One newly-ready worker life observed since the pre-apply snapshot.
      properties:
        generation:
          title: Generation
          type: integer
        kind:
          title: Kind
          type: string
        name:
          title: Name
          type: string
      required:
        - name
        - kind
        - generation
      title: FreshLife
      type: object
    RecycleEntry:
      description: >-
        One worker line in a profile-apply report.


        ``status`` is ``recycled`` (confirmed on reality), ``timed-out`` or
        ``failed`` (the

        target the roll stopped at), or ``self-deferred`` (the applier's own
        post-response

        self-exit). ``detail`` names why a ``timed-out`` / ``failed`` target did
        not

        converge, and is ``null`` otherwise.
      properties:
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        generation_before:
          title: Generation Before
          type: integer
        kind:
          title: Kind
          type: string
        name:
          title: Name
          type: string
        status:
          title: Status
          type: string
      required:
        - name
        - kind
        - status
        - generation_before
      title: RecycleEntry
      type: object
    RecycleStop:
      description: >-
        Where a profile apply's recycle roll stopped and why.


        ``name`` is the target the roll stopped at (its line in ``recycle``
        carries the

        target's own outcome), or ``null`` when the bus could not be read before
        a target was

        reached.
      properties:
        detail:
          title: Detail
          type: string
        kind:
          title: Kind
          type: string
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      required:
        - kind
        - name
        - detail
      title: RecycleStop
      type: object
    JsonValue: {}
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: x-api-key
      type: apiKey

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.