Client-side sessions

Operate Blaxel sandboxes directly from a frontend client using time-limited, scoped session tokens generated by your backend, with no proxy needed.

In many situations, you’ll need to operate a sandbox from a frontend client. When doing so, you cannot share the Blaxel credentials needed to access the sandbox. The solution is to use sessions.

Sessions are created for a sandbox from a backend server (using Blaxel credentials) and then shared with the frontend client, allowing the browser to connect to the sandbox.

From a session, you can:

• only interact with the sandbox API (i.e. manage the sandbox filesystem, processes and logs).

From a session, you cannot:

• interact with Blaxel API to create other preview URLs or sessions. These operations must be done server-side.

Basic example

Create a temporary backend session to access a sandbox instance from your client application. Main parameter for this is expiresAt, a Date() corresponding to the expiration date.

TypeScript

// From your backend
import { SandboxInstance } from "@blaxel/core";

const sandbox = await SandboxInstance.get("my-sandbox");

const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
const session = await sandbox.sessions.create({ expiresAt });

# From your backend
from datetime import datetime, timedelta, UTC
from blaxel.core import SandboxInstance

sandbox = await SandboxInstance.get("my-sandbox")

expires_at = datetime.now(UTC) + timedelta(hours=24)
session = await sandbox.sessions.create({"expires_at": expires_at})

/// From your frontend:
import { SandboxInstance } from "@blaxel/core";

const sandboxWithSession = await SandboxInstance.fromSession(session)

Create if expired

This helper function either retrieves an existing session or creates a new one if it expired. You can optionally pass delta (default: 1 hour), the time window in milliseconds before actual expiration when a session should still be recreated.

TypeScript

const expiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24 hours
const session = await sandbox.sessions.createIfExpired(
  { expiresAt },
  60000 // delta in milliseconds
);

expires_at = datetime.now(UTC) + timedelta(hours=24)
session = await sandbox.sessions.create_if_expired(
  {"expiresAt": expires_at},
  delta_seconds=60000
)

Example (NextJS)

The following example demonstrates a full implementation of sessions in a backend server and frontend client using NextJS.

Server code (backend)

import { NextResponse } from 'next/server';
import { SandboxInstance } from "@blaxel/core";

const SANDBOX_NAME = 'my-sandbox';
const responseHeaders = {
  "Access-Control-Allow-Origin": "http://localhost:3000",
  "Access-Control-Allow-Methods": "GET, POST, PUT, DELETE, OPTIONS, PATCH",
  "Access-Control-Allow-Headers": "Content-Type, Authorization, X-Requested-With, X-Blaxel-Workspace, X-Blaxel-Preview-Token, X-Blaxel-Authorization",
  "Access-Control-Allow-Credentials": "true",
  "Access-Control-Expose-Headers": "Content-Length, X-Request-Id",
  "Access-Control-Max-Age": "86400",
  "Vary": "Origin"
}

export async function GET() {
  // Get or create sandbox
  const sandbox = await SandboxInstance.createIfNotExists({
    name: SANDBOX_NAME,
    image: "blaxel/base-image:latest",
    memory: 4096,
    region: "us-pdx-1"
  });

  // Create session (24 hours expiry)
  const session = await sandbox.sessions.create({
    expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
  });

  // Create preview for port 3000
  const preview = await sandbox.previews.create({
    metadata: { name: "app-preview" },
    spec: {
      port: 3000,
      public: true,
      responseHeaders: responseHeaders
    }
  });

  return NextResponse.json({
    session,
    preview_url: preview.spec?.url
  });
}

Client code (frontend)

'use client'

import { SandboxInstance } from "@blaxel/core";
import { useState, useEffect } from "react";

export default function SandboxClient() {
  const [sandbox, setSandbox] = useState(null);
  const [previewUrl, setPreviewUrl] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    initializeSandbox();
  }, []);

  async function initializeSandbox() {
    // Get session from backend
    const response = await fetch('/api/sandbox');
    const { session, preview_url } = await response.json();

    // Create sandbox from session
    const sandboxInstance = await SandboxInstance.fromSession(session);

    setSandbox(sandboxInstance);
    setPreviewUrl(preview_url);

    // Start development server
    await sandboxInstance.process.exec({
      name: "dev-server",
      command: "npm run dev",
      workingDir: "/app",
      waitForPorts: [3000]
    });
    setLoading(false);
  }

  if (loading) return <div>Loading sandbox...</div>;

  return (
    <div>
      <h1>Sandbox Demo</h1>
      {previewUrl && (
        <iframe
          src={previewUrl}
          width="100%"
          height="600px"
          title="App Preview"
        />
      )}
    </div>
  );
}