Skip to content

StartBoxRun: optional caller-chosen run token, returned on the run record, so a caller can identify its own run #3668

Open

Description

@hsinatfootprintai

Problem

A caller that starts a box run (StartBoxRun, POST /v1/containers/{username}/code-runs) cannot later tell, from ListBoxRuns, which run is the one it started. If the caller loses the response (a crash, a failed write on its side, a network cut after the daemon accepted the start), the next attempt is refused with "a run of the same name is already going" and the caller cannot tell whether that run is its own or one a person started by hand under the same name.

Matching on run name plus a start-time window is not safe: a hand-started run of the same name inside the window is indistinguishable from the caller's. The caller would then report another run's output as its own result. Today the safe fallback is to wait for the run to finish and start the prompt again, so the work can run twice.

Proposal

Let StartBoxRunRequest carry an optional caller-chosen opaque identifier (for example client_token, at most 128 bytes, free text) and return it on the BoxRun record in StartBoxRun, ListBoxRuns and the run's detail:

  • Stored with the run; survives a daemon restart for as long as the run record does.
  • Never interpreted by the daemon. A run started from the CLI has none (empty).
  • Optionally, a second start with the same token on the same box returns the existing run instead of a busy refusal (idempotent start). If that is too large a change, echoing the token alone is enough for the caller to match.
  • Advertise it as a capability so a caller can fall back on an older daemon.

Acceptance

  • A run started with a token shows that token in ListBoxRuns.
  • A run started without one shows an empty token; a run started by hand never shows a caller's token.
  • Two runs started with different tokens are distinguishable after a daemon restart.
  • A daemon that lacks the field is detectable through the capability list.

Blocked by: none
Sprint: #3734
Part of #3734

Open question (answer on #3734, row for this issue): Q2 — idempotent start, or echo the token only? Default: echo only.

Activity

  1. hsinatfootprintai commented on Nov 12, 2026

    @hsinatfootprintai
    ContributorAuthor

    A client implementing against this request has assumed these names, so a daemon that ships the same names needs no client change: request/response field client_token (JSON clientToken) on StartBoxRun and on the BoxRun record returned by StartBoxRun and ListBoxRuns, and the capability string box_run_client_token in the system-info capability list. Different names are fine if preferred; the client change is small.

  2. added
    phase-2-optimizeSprint phase 2: improves the flow, not required for it to work
    needs-verificationCannot be proven by CI — verify against a deployed environment
    needs-decisionWaiting on a human decision — not implementable until answered
    on Nov 15, 2026
  3. hsinatfootprintai commented on Nov 15, 2026

    @hsinatfootprintai
    ContributorAuthor

    Decision recorded on #3734 — Q2 (echo the token only, no idempotent start): default accepted by @hsinatfootprintai (2026-11-15). The issue is ready to implement against the default.

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

    needs-verificationCannot be proven by CI — verify against a deployed environmentphase-2-optimizeSprint phase 2: improves the flow, not required for it to work

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions