Sessions

A session reserves a physical board for your exclusive use. While a session is active, no one else can access that board.

Lifecycle

PENDING ──▶ ALLOCATING ──▶ IDLE ◀──▶ ACTIVE
                            │          │
                            ▼          ▼
                          ENDED ◀──────┘

1. PENDING — session created, looking for a matching board
2. ALLOCATING — board found, pod is setting up the connection
3. IDLE — board reserved, waiting for you to connect
4. ACTIVE — your serial WebSocket is connected
5. ENDED — session over, board released

Sessions start in IDLE after allocation. They become ACTIVE when you open the serial console (web UI) or connect via WebSocket (CLI/SDK). Closing the connection moves the session back to IDLE.

How sessions end

A session can end for several reasons:

Reason	What happens
You end it	Click "End Session" in the UI, run fbay session end, or call DELETE /v1/sessions/{id}
Idle timeout	No WebSocket connection for 30 seconds — the session ends and the board is released
Credits exhausted	Your balance hits zero — the session ends immediately
Max duration	Free-tier sessions are capped at 10 minutes; paid tiers have no limit

Idle behavior

When your WebSocket disconnects (you close the browser tab, your network drops, etc.), the session enters IDLE state. A 30-second countdown starts:

• Reconnect within 30 seconds and the session resumes as ACTIVE
• Don't reconnect and the session ends automatically

Credits are consumed during both ACTIVE and IDLE states — the board is still reserved for you.

TIP

If you're done, always end your session explicitly. Don't rely on the idle timeout — you'll burn 30 seconds of credits waiting for it to fire.

Reconnecting

You can reconnect to an idle session at any time within the 30-second window. The board and session state are preserved, but previous terminal output is not — you'll get a fresh serial stream from the point of reconnection.

One session at a time

You can only have one active session at a time. To start a new session, end your current one first. Attempting to create a second session returns 409 Conflict.

Starting a session

Web UI: Click Start Session on an available board in the dashboard.

CLI:

fbay session create --board esp32-s3

API:

curl -X POST https://api.fbay.io/v1/sessions \
  -H "Authorization: Bearer key_..." \
  -H "Content-Type: application/json" \
  -d '{"board_type": "esp32-s3"}'