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. PROVISIONING — the base image you asked for is being written to the board
4. IDLE — board reserved, waiting for you to connect
5. ACTIVE — your serial WebSocket is connected
6. 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.

A session that asked for a base image starts in PROVISIONING instead, and reaches IDLE when the board is ready. That time is not billed and the idle countdown does not run during it: the write is our step, not your time on the board. The console is open throughout, and the progress goes to it.

Base images

Every board type boots something you can talk to, so a first session needs no firmware of your own. Pick one when you start the session: an interactive shell that answers help, id, uptime, temp and bench; MicroPython, which gives you a REPL; or a Zephyr shell, on the STM32 and ESP32 families.

In the web UI the split button next to Start opens the list. Over the API, pass base_image_id to POST /v1/sessions; GET /v1/base-images?board_type=... lists what a board type offers. Writing it costs no credits.

How sessions end

A session can end for several reasons:

Reason	What happens
You end it	Click "End Session" in the UI, run srig session end, or call DELETE /v1/sessions/{id}
Idle timeout	No WebSocket connection for 1 minute: the session ends and the board is released
Credits exhausted	Your balance hits zero — the session ends immediately
Max duration	Free-tier sessions end after 10 minutes; pay as you go has no limit

Idle behavior

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

• Reconnect within 1 minute and the session resumes as ACTIVE
• Don't reconnect and the session ends automatically

Flashing firmware and power cycling the board restart that countdown too, so a session cannot end underneath a flash that is still running.

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 pay for the time it spends waiting to fire.

Reconnecting

You can reconnect to an idle session at any time within that 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 on a board type under Sessions, or the split button beside it to pick a base image.

CLI:

srig session create --board esp32-s3

API:

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