#Session Supervisor

The Session Supervisor runs and observes long-lived processes inside a sandbox. A session has a stable identity, one current process attempt, and a retained event journal. Client connections are attachments to that state; they do not own it.

Use a supervised session when a process must continue across API reconnects, expose replayable output, accept explicit stdin and EOF, or recover after the sandbox runtime is replaced. Use Contexts for short-lived command execution and REPL-oriented workflows that do not need a durable event journal.

Execution Model#

Every event has a monotonically increasing seq. Process-bound operations can include expected_attempt_id so stale clients cannot write to, signal, or resize a newer attempt accidentally.

Connection Choice#

SSE is the simplest default for output consumers. WebSocket is useful for interactive PTY attachments, but it does not change the lifecycle or delivery model.

SDK Quickstart#

These examples attach to an existing sandbox from SANDBOX0_SANDBOX_ID, start /bin/cat, send one input followed by explicit EOF, consume the journal, then prove the session still exists after the stream is closed.

go
package main

import (
  "context"
  "encoding/base64"
  "fmt"
  "io"
  "log"
  "os"
  "time"

  sandbox0 "github.com/sandbox0-ai/sdk-go"
  "github.com/sandbox0-ai/sdk-go/pkg/apispec"
)

func main() {
  ctx := context.Background()
  options := []sandbox0.Option{
      sandbox0.WithToken(os.Getenv("SANDBOX0_TOKEN")),
  }
  if baseURL := os.Getenv("SANDBOX0_BASE_URL"); baseURL != "" {
      options = append(options, sandbox0.WithBaseURL(baseURL))
  }
  client, err := sandbox0.NewClient(options...)
  if err != nil {
      log.Fatal(err)
  }
  sandbox := client.Sandbox(os.Getenv("SANDBOX0_SANDBOX_ID"))

  created, err := sandbox.CreateSession(ctx, apispec.ExecutionSessionSpec{
      Name:    apispec.NewOptString("docs-pipe"),
      Command: []string{"/bin/cat"},
      Io: apispec.NewOptExecutionSessionIOSpec(apispec.ExecutionSessionIOSpec{
          Mode: apispec.NewOptExecutionSessionIOMode(apispec.ExecutionSessionIOModePipes),
      }),
  }, &sandbox0.CreateSessionOptions{
      IdempotencyKey: fmt.Sprintf("docs-%d", time.Now().UnixNano()),
  })
  if err != nil {
      log.Fatal(err)
  }
  defer sandbox.DeleteSession(ctx, created.ID)

  attempt, ok := created.Attempt.Get()
  if !ok {
      log.Fatal("session has no current attempt")
  }
  stream, err := sandbox.WatchSessionEvents(ctx, created.ID, nil)
  if err != nil {
      log.Fatal(err)
  }

  _, err = sandbox.WriteSessionInput(ctx, created.ID, apispec.ExecutionSessionInputRequest{
      InputID:           fmt.Sprintf("input-%d", time.Now().UnixNano()),
      ExpectedAttemptID: apispec.NewOptString(attempt.ID),
      DataBase64:        apispec.NewOptString(base64.StdEncoding.EncodeToString([]byte("hello from Go\n"))),
      EOF:               apispec.NewOptBool(true),
  })
  if err != nil {
      log.Fatal(err)
  }

  var lastSeq int64
  for {
      event, err := stream.Recv()
      if err != nil {
          if err == io.EOF {
              break
          }
          log.Fatal(err)
      }
      lastSeq = event.Seq
      if encoded, ok := event.DataBase64.Get(); ok {
          data, err := base64.StdEncoding.DecodeString(encoded)
          if err != nil {
              log.Fatal(err)
          }
          fmt.Print(string(data))
      }
      if event.Type == "attempt.exited" {
          break
      }
  }
  if err := stream.Close(); err != nil {
      log.Fatal(err)
  }
  current, err := sandbox.GetSession(ctx, created.ID)
  if err != nil {
      log.Fatal(err)
  }
  fmt.Printf("session=%s phase=%s cursor=%d\n", current.ID, current.Phase, lastSeq)
}

Input, EOF, and Attempt Fencing#

POST /inputs accepts base64-encoded bytes, explicit EOF, or both. The response means the operation was accepted into the current attempt's input queue; it does not mean the application consumed the bytes.

• Generate a unique input_id for each logical write.
• Reuse the same input_id and content when retrying an ambiguous request. Once its receipt is durable, the server returns duplicate: true without queueing it again.
• Include expected_attempt_id when input belongs to a particular process attempt. A newer attempt causes 409 session_conflict instead of receiving stale input.
• Set eof: true to close stdin after earlier queued bytes. Disconnecting an attachment is never EOF.

No process API can provide exactly-once application consumption. If the runtime fails after bytes reach the process but before the input receipt is durable, a retry can replay them. Design the application protocol to tolerate this ambiguity when it matters.

Retained Events and Reconnect#

Paged reads and streams share the same journal cursor:

1. Process each event and remember its seq after the side effect commits.
2. Reconnect SSE with Last-Event-ID: <seq> or reconnect SSE/WebSocket with ?after=<seq>.
3. Deduplicate by seq; replay is expected.

For a limited HTTP page, continue with the final event's seq. The page's cursor.earliest and cursor.latest describe the full retained window, not the next-page position.

The default retention is 64 MiB and 24 hours per session. A cursor older than retained history returns 410 event_cursor_expired and reports the earliest sequence in the retained window. Reconcile current session state with GET /sessions/{'{session_id}'}, then resume with after=earliest-1 (or after=latest when the retained window is empty), or apply application-specific recovery.

Slow live subscribers can be detached when their in-memory delivery buffer fills. This does not lose retained journal data; reconnect from the last committed sequence.

Attempts, Restart, and Runtime Recovery#

An attempt ID identifies one process execution. It changes when:

• the restart policy starts the process again after exit
• a client creates or replaces an attempt
• an execution-relevant session specification is replaced
• a paused or replaced sandbox runtime is restored and runtime_recovery is restart

The session ID and event sequence remain stable across these boundaries. runtime_generation distinguishes events and attempts produced by different sandbox runtime instances.

Sandbox pause stops the current runtime after flushing session state into the checkpointed root filesystem. Resume creates a new runtime generation. It does not restore the old PID, memory, sockets, or terminal connection; it either creates a new attempt or leaves the session stopped according to runtime_recovery.

Readiness#

Readiness controls when an attempt moves from starting to running:

For delay and output, timeout_ms terminates an attempt that never becomes ready. Readiness observes process bytes only; it does not interpret an application protocol.

PTY Sessions#

Set io.mode to pty with initial rows, cols, and term. Use PUT /terminal or a WebSocket resize message to update the terminal size. Use expected_attempt_id on resize and signal messages to prevent a stale terminal attachment from controlling a replacement attempt.

PTY output is emitted as stream: "pty". Pipe sessions keep stdout and stderr separate.

CLI Reference#

HTTP API#

All public paths are scoped by sandbox:

Deleting the sandbox or reaching its hard TTL deletes its sessions. Deleting an individual session stops its current attempt and removes its retained state.