Skip to content

Update exit-code guidance once box info carries exit_code (boxlite#1528) #46

Description

@silverzki

Two pages will become incorrect once boxlite-ai/boxlite#1528 ships. They are
accurate today — this is a follow-up to land after that PR merges and
releases, not before.

That PR adds exit_code to the box-info surface: BoxStateInfo gains the
field in every binding, and GET /v1/boxes/{id} returns it once the box has
stopped because its main command exited.

1. manage-sandbox/lifecycle.mdx — "Exit codes" section

Current text:

BoxStateInfo carries pid, running and status — no exit code. To
read the main command's exit code, attach to it.

All three claims stop holding: BoxStateInfo carries it, the REST API returns
it, and attach() is no longer the only route. Suggested replacement:

BoxStateInfo carries pid, running, status and exit_code. The exit
code is present once the box has stopped because its main command exited,
and absent otherwise — 0 is a real exit code, so test for absence rather
than for a falsy value. It survives the box stopping, so it can be read
after the fact. Use attach() when you need to follow the session live
rather than read its outcome afterwards.

The attach() example below that paragraph stays valid and is still the right
answer for streaming; it just stops being the only way to learn the code.

2. reference/python.mdx — the attach row

Current text:

With no argument, attaches to the init session — the entrypoint + cmd
process — which is the only way to read its exit code.

Drop the "only way" clause and point at the stored field instead, e.g. "…the
entrypoint + cmd process, for following it live. Its exit code is also on
info().state.exit_code once the box has stopped."

Why this matters

These two pages are exactly what POL-603 was filed against: a user following
them is sent to attach(), which on Cloud has no route for the main session
and in any case only streams a live process — it cannot answer after the box
has stopped, which is the case they actually have. Fixing the API without
fixing these leaves the documented path pointing at the dead end.

Activity

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions