Self-hosted `/v1/sessions` does not implement the SDK session timeout field

Author: CruelCreated Aug 24, 2026Updated Aug 24, 2026

The Steel SDKs expose a session timeout when creating a browser session. For example, the Node SDK uses:

typescript
client.sessions.create({
  timeout: 10000,
})

The Python SDK exposes the corresponding session-create option under its generated Python parameter naming.

However, the current open-source steel-browser API server does not appear to accept or implement a session timeout on POST /v1/sessions.

Looking at the current server implementation:

  • CreateSession in api/src/modules/sessions/sessions.schema.ts does not define a timeout field.
  • handleLaunchBrowserSession() does not read or pass a timeout into SessionService.startSession().
  • SessionService.startSession() has no timeout parameter and does not schedule automatic session release.
  • SessionDetails still includes a timeout field, but the OSS server initializes it from sessionStats as:
typescript
const sessionStats = {
  duration: 0,
  eventCount: 0,
  timeout: 0,
  creditsUsed: 0,
  proxyTxBytes: 0,
  proxyRxBytes: 0,
};

I also reproduced this against a self-hosted instance by creating a session directly via REST with:

json
{
  "timeout": 10000
}

The session was created successfully, but the response reported:

json
{
  "timeout": 0,
  "status": "live"
}

and the session remained live well beyond 10 seconds, including past 30 seconds, until explicitly released.

So there appears to be a mismatch between the SDK/API contract and the current self-hosted server implementation: clients can specify a session timeout, but the OSS API server currently ignores it and does not enforce automatic release.

Expected behavior could be one of:

  1. Add timeout to the self-hosted CreateSession schema and implement server-side release after the requested duration; or
  2. If this is intentionally hosted-only behavior, make that distinction explicit in the SDK/API docs and generated clients.

It may also be worth clarifying the timeout field in SessionDetails, since the OSS server currently always initializes it to 0 despite describing it as the session timeout duration.

The CLI appears to implement timeout handling client-side, which may be compensating for the lack of server-side timeout handling in self-hosted mode.