Prerequisites: Docker (for the Docker backend) and API keys for any cloud backends you want to use. The local and Docker sandboxes work without any cloud provider API keys.

Local smoke test

If you only want to confirm that Temporal workflows run locally, use the minimal example first:

export OPENAI_API_KEY="sk-..."
# Optional: export EXAMPLES_TEMPORAL_MODEL="gpt-5.4-mini"
# Optional: export EXAMPLES_TEMPORAL_TRACE="openai"
uv run --extra temporal python -m examples.sandbox.extensions.temporal.local_hello_workflow

This starts the Temporal Python SDK test server, runs one workflow and one model activity, connects the workflow to a local Unix sandbox, and then shuts down. It does not require the Temporal CLI, an already running Temporal dev server, or sandbox backend credentials.

The local smoke test enables OpenAI Agents tracing by default. Set EXAMPLES_TEMPORAL_TRACE=none to disable tracing, or EXAMPLES_TEMPORAL_TRACE=openai_with_temporal_spans to also ask the Temporal plugin to add Temporal spans. The Temporal span mode depends on Temporal plugin behavior and may omit regular Agents spans with some plugin versions; use the default openai mode when you want standard OpenAI trace spans.

Install just and the Temporal CLI if you don't have them already.

Change into the example directory:

cd examples/sandbox/extensions/temporal

Create a .env file in this directory with your API keys:

OPENAI_API_KEY="sk-..."
DAYTONA_API_KEY="dtn_..."   # optional, for Daytona backend
E2B_API_KEY="e2b_..."       # optional, for E2B backend

Start the Temporal dev server:
```
just temporal
```
In a second terminal, start the worker:
```
just worker
```
In a third terminal, start the TUI:
```
just tui
```

The just worker and just tui commands automatically install dependencies before starting.

TUI commands

Command	Description
`/switch`	Switch the current session to a different sandbox backend
`/fork [title]`	Fork the session onto a (possibly different) backend
`/title <name>`	Rename the current session
`/done`	Exit the TUI

Both /switch and /fork open an interactive backend picker. When switching to the local backend you can specify the workspace root directory.

How it works

A single Temporal worker registers all sandbox backends via SandboxClientProvider, so every backend's activities are available on one task queue. The workflow picks which backend to target each turn by calling temporal_sandbox_client(name) in its RunConfig.

Files:

temporal_sandbox_agent.py -- The AgentWorkflow definition and worker entrypoint. Each conversation turn calls Runner.run() with a SandboxRunConfig that targets the active backend. The workflow is long-lived: it idles between turns and persists indefinitely in Temporal.
temporal_session_manager.py -- A singleton SessionManagerWorkflow that tracks active sessions and handles create, fork, switch, and destroy operations.
temporal_sandbox_tui.py -- A Textual TUI that connects to the session manager and drives conversations via signals, updates, and queries.
examples/sandbox/misc/workspace_shell.py -- A shared Capability that gives the agent a shell tool for running commands in the sandbox workspace.

Switching backends is an in-place operation: the workflow receives a switch_backend update, changes its backend and manifest, clears the backend-specific session state, and the next turn creates a fresh session on the new backend. The portable snapshot is preserved so workspace files carry over.

Forking pauses the source workflow, snapshots its state and conversation history, and starts a new child workflow on the chosen backend. The fork gets an independent copy of the workspace and conversation.