Why do you need it?
In our organization we integrate with OpenSandbox through the official SDK rather than calling the REST API directly — the typed client is our integration contract. Whenever an operation is missing from the SDK we are forced to drop down to raw HTTP alongside it, which defeats that standardization and couples our code to the wire protocol. This is one of those gaps:
execd already serves the interactive PTY session lifecycle (POST /pty, GET /pty/{sessionId}, DELETE /pty/{sessionId}, plus the /pty/{id}/ws WebSocket), but the REST routes were never added to specs/execd-api.yaml. Two consequences:
- The generated SDK clients can drift from the real server protocol, since the spec is supposed to be the source of truth.
- None of the SDKs expose a PTY session service, so a consumer that wants interactive terminals has to hand-roll the REST calls outside the SDK.
How could it be?
Add the routes to the spec and expose a PTY session service across the SDKs:
- spec: add the three
/pty REST routes, matching execd's real behavior — DELETE returns 200 (empty body) and all three document the 501 NOT_SUPPORTED platform response. The interactive /pty/{id}/ws channel stays a WebSocket (not modelled by OpenAPI).
- generated clients: regenerate the spec-driven clients (Python
openapi-python-client, JS openapi-typescript, Kotlin at build time).
- hand-written clients: add the
/pty transport directly to Go and C# (their execd clients are hand-written).
- service: expose a PTY session service (create / status / delete) wired into the execd stack and reachable on the sandbox facade in every SDK.
Input: optional cwd / command on create; a session id for status/delete.
Output: the created session id; session status (running + output offset).
Other related information
Additive: the PTY stack member is optional in the public adapter-factory contract, with an unavailable-PTY fallback, so existing custom factories keep working. PTY is platform-gated (501 NOT_SUPPORTED on non-Unix). A proposed implementation is open as #1054.
Co-authored-by: Atenea Agent srv_atenea_gitlab@ofidona.net
Why do you need it?
In our organization we integrate with OpenSandbox through the official SDK rather than calling the REST API directly — the typed client is our integration contract. Whenever an operation is missing from the SDK we are forced to drop down to raw HTTP alongside it, which defeats that standardization and couples our code to the wire protocol. This is one of those gaps:
execd already serves the interactive PTY session lifecycle (
POST /pty,GET /pty/{sessionId},DELETE /pty/{sessionId}, plus the/pty/{id}/wsWebSocket), but the REST routes were never added tospecs/execd-api.yaml. Two consequences:How could it be?
Add the routes to the spec and expose a PTY session service across the SDKs:
/ptyREST routes, matching execd's real behavior —DELETEreturns200(empty body) and all three document the501 NOT_SUPPORTEDplatform response. The interactive/pty/{id}/wschannel stays a WebSocket (not modelled by OpenAPI).openapi-python-client, JSopenapi-typescript, Kotlin at build time)./ptytransport directly to Go and C# (their execd clients are hand-written).Input: optional
cwd/commandon create; a session id for status/delete.Output: the created session id; session status (running + output offset).
Other related information
Additive: the PTY stack member is optional in the public adapter-factory contract, with an unavailable-PTY fallback, so existing custom factories keep working. PTY is platform-gated (
501 NOT_SUPPORTEDon non-Unix). A proposed implementation is open as #1054.Co-authored-by: Atenea Agent srv_atenea_gitlab@ofidona.net