Session Execution
- 52 installs
- 1.1k repo stars
- Updated August 4, 2026
- cloudflare/sandbox-sdk
session-execution is an agent skill for Cloudflare Sandbox SDK session command execution, streaming, and stdout/stderr separation.
About
The session-execution skill guides work on Cloudflare Sandbox SDK command execution with reliable stdout and stderr separation. It points contributors to docs/SESSION_EXECUTION.md for architecture covering foreground exec in the main shell versus background execStream and startProcess subshell modes. Foreground exec uses temp files for output capture because bash waits for redirect completion, while background mode streams through FIFOs with per-line binary prefixes marking stdout and stderr before log parser reconstruction. Completion signaling writes exit codes atomically to an id.exit file via tmp plus mv with hybrid fs.watch and polling for tmpfs robustness, and background runs await labelers.done before reading final output. Review checklists verify atomic exit handling, FIFO cleanup on errors, and per-session mutex serialization that prevents false-positive race reports within one session. Key files include session.ts, SessionManager.ts mutex lifecycle, and CommandClient SDK interface. Use when developing or reviewing session execution, shell state, command handlers, or sandbox process management in the SDK.
- Documents foreground exec versus background execStream execution modes.
- Uses binary line prefixes to separate stdout and stderr in streamed logs.
- Signals completion with atomic exit files and hybrid watch polling.
- Explains per-session mutex serialization for command execution safety.
- Lists review checks for FIFO cleanup and labelers.done awaiting.
Session Execution by the numbers
- 52 all-time installs (skills.sh)
- Ranked #3,221 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
session-execution capabilities & compatibility
- Capabilities
- foreground and background execution mode guidanc · binary prefix stdout/stderr stream contract · atomic exit code completion signaling · per session mutex concurrency model explanation · code review checklist for fifo and cleanup paths
- Works with
- cloudflare · docker
- Use cases
- debugging · devops
What session-execution says it does
Session execution has a mutex that serializes command execution per session.
npx skills add https://github.com/cloudflare/sandbox-sdk --skill session-executionAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 52 |
|---|---|
| repo stars | ★ 1.1k |
| Last updated | August 4, 2026 |
| Repository | cloudflare/sandbox-sdk ↗ |
How does sandbox session exec handle foreground output, background FIFO streaming, and exit signaling?
Develop or review Cloudflare Sandbox SDK session execution, FIFO streaming, and stdout/stderr separation.
Who is it for?
SDK contributors working on session.ts, command handlers, or sandbox shell process management.
Skip if: Skip for unrelated Cloudflare Workers routing, frontend UI work, or general DevOps deployment tasks.
When should I use this skill?
User works on session execution, execStream, FIFO streaming, or reviews sandbox command handling code.
What you get
Correct session execution changes with reliable stream separation, completion detection, and mutex-aware concurrency reasoning.
Files
Session Execution
Read docs/SESSION_EXECUTION.md before working in this area. It explains the architecture for reliable command execution with stdout/stderr separation.
Key Concepts
Two execution modes:
- Foreground (exec): Runs in main shell, state persists. Uses temp files for output capture.
- Background (execStream/startProcess): Runs in subshell via FIFOs. Labelers prefix output in background.
Binary prefix contract:
- Stdout:
\x01\x01\x01prefix per line - Stderr:
\x02\x02\x02prefix per line - Log parser reconstructs streams from these prefixes
Completion signaling:
- Exit code written to
<id>.exitfile via atomictmp+mv - Hybrid fs.watch + polling detects completion (robust on tmpfs/overlayfs)
- Background mode uses
labelers.donemarker to ensure output is fully captured
When Developing
- Understand why foreground uses temp files (bash waits for redirects to complete)
- Understand why background uses FIFOs (concurrent streaming without blocking shell)
- Test silent commands (cd, variable assignment) - these historically caused hangs
- Test large output - buffering issues can cause incomplete logs
When Reviewing
Correctness checks:
- Verify exit code handling is atomic (write to .tmp then mv)
- Check FIFO cleanup in error paths
- Ensure labelers.done is awaited before reading final output (background mode)
Race condition analysis:
Session execution has a mutex that serializes command execution per session. Before flagging race conditions:
1. Check if operations happen within the same session (mutex protects) 2. Check if operations are per-session vs cross-session (cross-session races are real) 3. Refer to docs/CONCURRENCY.md for the full concurrency model
Common false positives:
- "Concurrent reads/writes to session state" - mutex serializes these
- "FIFO operations might race" - labelers are per-command, not shared
Actual concerns to watch for:
- Cross-session operations without proper isolation
- Cleanup operations that might affect still-running commands
- File operations outside the mutex-protected section
Key Files
packages/sandbox-container/src/session.ts- Session class with exec/execStreampackages/sandbox-container/src/managers/SessionManager.ts- Mutex and lifecyclepackages/sandbox/src/clients/CommandClient.ts- SDK interface to session commands
Related skills
Lark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493k
Lark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16kLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16k
Just ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41Lark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16k
Design An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198kFAQ
Why does foreground exec use temp files?
Bash waits for redirect completion, so temp files capture output reliably in the main shell.
How are stdout and stderr separated in background mode?
Per-line binary prefixes mark stdout and stderr before the log parser reconstructs each stream.
Is session-execution safe to install?
Review the Security Audits panel on this page before installing in production.