Shell Access

Back to API Overview

This page covers the high-level shell access flow. For the browser-to-gateway message contract, read Shell WebSocket Interaction.

Overview

The shell access system provides authenticated browser users with temporary interactive shell sessions in isolated shell pods.

Main components:

• Shell access token APIs
• Shell storage readiness API
• Shell gateway WebSocket service
• Shell extension token APIs
• Shell pods with per-user startup credentials

High-Level Flow

1. Call createShellAccessTokenV1.
2. Open wss://.../ws using the returned gatewayUrl.
3. Send the initial connect payload with sessionId, accessToken, and jwt.
4. Let the gateway consume the token, synchronize shell storage readiness, and create the shell pod.
5. Exchange terminal traffic over WebSocket.
6. Extend inactivity deadlines by calling extendShellAccessTokenV1 and then sending the returned extension token over WebSocket.

Token Creation

The create-token operation returns:

• a short-lived single-use accessToken
• sessionId
• tokenEID
• expiresAt
• gatewayUrl

If a startupScript is requested, the gateway resolves that pinned script and sources it before the shell becomes interactive.

Storage Readiness

Before shell admission, the gateway ensures shell storage and quota state are ready for the session. This readiness step seeds missing quota records, reconciles limits, captures current usage, and returns the data the gateway needs to render startup quota notices.

Extensions

Shell sessions use two deadlines:

• Hard deadline: absolute maximum lifetime
• Soft deadline: inactivity deadline extended by the browser

The browser must periodically:

1. Call extendShellAccessTokenV1
2. Send the returned extension token through WebSocket
3. Update local deadline tracking from the returned extend_ack

Available Shell Functionality

The shell image exposes a curated toolset suitable for learning and guided platform workflows. Clients should treat the session as ephemeral and avoid assuming desktop-like persistence beyond the documented storage behavior.

Protected Web Services

A shell session’s pod can additionally host a protected, user-specific HTTP service, reachable through the shell gateway at a per-session subdomain. This is a two-layer registered model: a platform-vetted service definition (name, launch command, port, a pinned program file tree) and, separately, an instructor-registered content registration attached to it (e.g. one class’s specific challenge data). Neither layer trusts the shell user’s own zone – both are pinned, sha256-verified snapshots resolved at session-mint time, delivered into a native sidecar container the interactive shell cannot read from.

To use a protected web service, supply contentRegistrationEID when creating a shell access token (createShellAccessTokenV1); the response gains serviceBaseUrl and serviceAuthUrl. After the shell WebSocket connects, call POST {serviceAuthUrl} with the same JWT to obtain a one-time redeemUrl; opening it sets a scoped, host-only cookie and grants browser access to serviceBaseUrl. See the repository’s docs/what-and-why/architecture/shell-protected-services.md for the full design (two-layer authorization model, security properties, native-sidecar isolation) and the Security > Shell Services API operations below.

Shell-Specific Entry Points

• createShellAccessTokenV1
• consumeShellAccessTokenV1
• extendShellAccessTokenV1
• consumeShellExtensionTokenV1
• disconnectShellAccessTokenV1
• closeShellAccessTokenV1
• ensureShellStorageReadyV1
• createShellServiceDefinitionV1
• listShellServiceDefinitionsV1
• readShellServiceDefinitionV1
• updateShellServiceDefinitionV1
• deleteShellServiceDefinitionV1
• createShellServiceContentRegistrationV1
• listShellServiceContentRegistrationsV1
• readShellServiceContentRegistrationV1
• updateShellServiceContentRegistrationV1
• deleteShellServiceContentRegistrationV1
• readShellServiceBundleFileV1

Next Step

Read Shell WebSocket Interaction before implementing the browser terminal client.