Skip to content

docs(runtimes): driver TOML examples omit [openshell] version = 2 and fail preflight #3881

Closed
#3910
Closed
docs(runtimes): driver TOML examples omit [openshell] version = 2 and fail preflight#3881
#3910
Labels
area:docsDocumentation and examplesarea:gatewayGateway server and control-plane workstate:acceptedA maintainer decided OpenShell should pursue this issue

Description

@fede-kamel
fede-kamel
opened on Sep 29, 2026

User Story

As an operator configuring a compute driver from the Runtimes documentation, I want the TOML snippets there to be valid on their own, so that copying one into a fresh gateway.toml doesn't stop the gateway from starting.

Problem Statement

The Docker, Podman, and MicroVM sections of docs/how-it-works/sandboxes/runtimes.mdx show snippets like this:

[openshell.gateway]
compute_driver = "docker"

[openshell.drivers.docker]
socket_path = "/var/run/docker.sock"

Put into a new ~/.config/openshell/gateway.toml (the Linux package installs none), this makes the service fail at ExecStartPre=openshell-gateway config preflight:

gateway config preflight failed: ... category=missing_version detected_version=missing;
the file was preserved unchanged; migrate it before restarting the gateway

The snippets omit [openshell] / version = 2, which configuration.mdx shows but runtimes.mdx doesn't.

Impact / Why This Matters

The error tells the user to follow the schema v2 migration steps. That's confusing for someone who never had a v1 file, and it isn't obvious that the documented snippet itself is incomplete. The gateway stays down until they find the missing key.

Acceptance Criteria

  • The TOML examples in runtimes.mdx include [openshell] / version = 2, or the page states once, before the first example, that every file needs it.
  • Optional: when a file has only v2-shaped tables and no version key, the preflight message suggests adding [openshell] version = 2 rather than pointing to a migration.

Reproduction Steps

  1. Linux install with no existing ~/.config/openshell/gateway.toml.
  2. Copy the Docker driver snippet from runtimes.mdx into that file.
  3. Run openshell-gateway config preflight. It fails with missing_version.

Environment

  • OpenShell 0.1.2, gateway as a systemd user service (Debian package layout)

Activity

  1. github-actions
    added
    state:triage-neededOpened without agent diagnostics and needs triage
    on Sep 29, 2026

  2. purp commented on Oct 1, 2026

    @purp
    purp
    on Oct 1, 2026
    Collaborator

    📋 triage-agent

    Triage Assessment

    Classification: validated-bug

    Summary

    Confirmed from code and docs on main. Standalone gateway TOML examples in docs/how-it-works/sandboxes/runtimes.mdx omit [openshell] / version = 2, and gateway preflight rejects any file with an openshell table but no version key. High confidence.

    Investigation

    • runtimes.mdx has five standalone examples that start at [openshell.gateway] with no schema version: lines 30-33 (driver selection), 43-49 (extension driver), 87-93 (Docker), 163-166 (Podman), 186-194 (VM). That is two more than the issue lists. The bind-mount fragment at 142-149 is a partial example meant to be merged into an existing file.
    • crates/openshell-server/src/config_file.rs:674-684: preflight() returns missing_version when detected_version() (:618-635) finds an openshell table without version. [openshell.gateway] creates that table implicitly, so each snippet fails exactly as reported. parse_and_validate (:581-585) applies the same rule when the gateway loads the file.
    • The error text (config_file.rs:486) always says "migrate it before restarting the gateway" and links the schema v2 migration section (:481). The missing_version category does not distinguish a fresh file from a legacy v1 file, which explains the confusing guidance.
    • docs/how-it-works/gateways/configuration.mdx:46-48 and :68-74 document the requirement correctly. The gap is limited to runtimes.mdx.
    • The requirement was introduced by the schema v2 cutover (refactor(config): normalize and enforce gateway schema v2 #2814) and has shipped since v0.1.0. It is still present in v0.1.2 (latest) and on main.
    • No duplicate issues found. docs(runtimes): show required schema version in gateway TOML examples #3910 (open, by the reporter) proposes a docs change to runtimes.mdx.
    • The optional acceptance criterion (a preflight hint for v2-shaped files that lack a version) is a separate gateway change. It looks feasible: the gateway would need to recognise v2-only tables before choosing the message.

    Impact Signals

    • Affected users/scope: Users who build a new gateway.toml from the Runtimes page, especially Linux package installs, which ship no config file. The gateway service stays down until the file is fixed.
    • Regression: Docs drift since the schema v2 cutover (refactor(config): normalize and enforce gateway schema v2 #2814). No runtime behavior regressed.
    • Workaround: Available. Add [openshell] / version = 2 at the top of the file, as shown in the Gateway Configuration reference.
    • Evidence quality: High. The failing code path and the affected doc lines are both directly observable on main.

    Human Decision Required

    Decide whether OpenShell should address this issue. If yes, apply
    state:accepted, associate it with a roadmap item, or do both, and decide
    whether the work remains human-owned. Either action records acceptance;
    roadmap placement additionally records sequencing.
    To queue investigation or planning for an unattended agent, also apply
    agent:plan-requested. You can instead directly ask an agent to use
    create-spike or build-from-issue on this issue; the agent will warn about
    missing expected workflow labels and continue without changing them. If no,
    close it as not planned and record the rationale.

  3. purp
    added
    state:acceptedA maintainer decided OpenShell should pursue this issue
    area:docsDocumentation and examples
    area:gatewayGateway server and control-plane work
    and removed
    state:triage-neededOpened without agent diagnostics and needs triage
    on Oct 1, 2026
  4. johntmyers
    closed this as completedin #3910on Oct 12, 2026
  5. opensource-fork-sync
    added a commit that references this issue on Oct 12, 2026

    docs(runtimes): show required schema version in gateway TOML examples (…

    36c4c03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentation and examplesarea:gatewayGateway server and control-plane workstate:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions