Skip to content

Conversation

@agents-git-bot
Copy link
Contributor

@agents-git-bot agents-git-bot bot commented Nov 20, 2025

Summary

Documents new env and cwd parameters added to command execution methods in the Cloudflare Sandbox SDK.

Changes

API Documentation (sandbox/api/commands.mdx)

  • Added env and cwd parameters to exec() method documentation
  • Added env and cwd parameters to execStream() method documentation
  • Added example showing per-command environment variables and working directory usage

Execute Commands Guide (sandbox/guides/execute-commands.mdx)

  • Added new section "Set environment variables and working directory" with comprehensive examples
  • Updated "Working directory issues" troubleshooting section to recommend the cwd option as best practice
  • Clarified that per-command settings do not persist to the session

Context

These parameters allow customizing command execution on a per-command basis:

  • env: Environment variables merged with session environment (per-command only)
  • cwd: Working directory that overrides session working directory (per-command only)

This provides flexibility for different command contexts without affecting the broader session state.

Source

🤖 Synced from cloudflare/sandbox-sdk PR #204

Original PR Title: add environment variables and working directory support to command exec

@github-actions
Copy link
Contributor

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern Owners
/src/content/docs/sandbox/ @whoiskatrin, @ghostwriternr, @cloudflare/pcx-technical-writing, @cloudflare/ai-agents

@agents-git-bot agents-git-bot bot added the documentation Documentation edits label Nov 20, 2025
@agents-git-bot
Copy link
Contributor Author

Updated documentation to reflect the new per-command env and cwd options added in cloudflare/sandbox-sdk#204.

Changes

Commands API (/sandbox/api/commands/)

Updated exec() method documentation:

  • Added env parameter - per-command environment variables that do not persist
  • Added cwd parameter - per-command working directory that does not persist
  • Added comprehensive examples showing:
    • Setting per-command environment variables
    • Using custom working directory for a command
    • Demonstrating that values are scoped and do not persist

Updated execStream() method documentation:

  • Added env parameter
  • Added cwd parameter
  • Added example showing per-command options with streaming execution

Added clarifying note:

  • Explains the difference between per-command options (temporary) and session-level configuration (persistent)
  • Links to session documentation for persistent configuration

Why This Matters

This PR adds an important new capability - developers can now pass temporary environment variables and change directories for individual command executions without affecting the session state. This is useful for:

  • Testing with different configurations
  • Running commands in specific directories without changing session state
  • Temporarily setting environment variables for a single operation

The documentation clearly shows the scoping behavior with examples to prevent confusion.

@agents-git-bot
Copy link
Contributor Author

✅ Documentation sync complete!

Files Updated

1. /sandbox/api/commands.mdx (API Reference)

  • Added env and cwd parameters to exec() method
  • Added env and cwd parameters to execStream() method
  • Added comprehensive examples showing per-command options
  • Added note explaining difference between per-command and session-level options

2. /sandbox/guides/execute-commands.mdx (How-to Guide)

  • Added new section "Set environment variables and working directory" with examples
  • Updated "Working directory issues" troubleshooting to recommend cwd option as best practice
  • Added note clarifying that per-command options do not persist

Key Documentation Points

Per-command options are temporary - The env and cwd options apply only to that specific command execution and do not affect session state

Use cases include:

  • Testing with different configurations
  • Running commands in specific directories without changing session state
  • Temporarily setting environment variables for a single operation

For persistent configuration - Use session-level options with createSession() instead

Ready for review! 🚀

@agents-git-bot
Copy link
Contributor Author

Added comprehensive documentation for all startProcess() options including timeout, processId, encoding, and autoCleanup parameters.

Document new env and cwd parameters for exec(), execStream(), and
startProcess() methods. These options allow temporary per-command
overrides of session/sandbox-level settings without persisting changes.

- Updated commands.mdx with env and cwd parameters for exec() and execStream()
- Added example showing usage of env and cwd options
- Updated startProcess() documentation with complete options list
- Updated environment-variables.mdx to include execStream() example

Related PR: cloudflare/sandbox-sdk#204

Generated with Claude Code

Co-Authored-By: Claude <[email protected]>
@agents-git-bot
Copy link
Contributor Author

Updated documentation to include:

  • Added env and cwd parameters to exec() and execStream() methods
  • Added example showing usage of env and cwd options in exec()
  • Updated startProcess() documentation with complete options list
  • Updated environment-variables.mdx to include execStream() example for per-command env variables

The documentation now accurately reflects the API changes from cloudflare/sandbox-sdk#204.

@cloudflare cloudflare deleted a comment from Nattaworn159 Nov 25, 2025
Remove timeout from execStream() and timeout/encoding/autoCleanup
from startProcess() to match actual SDK implementation.

These parameters were accepted by the SDK but not used in the
execution flow, causing potential confusion for users.
@ghostwriternr ghostwriternr requested review from a team and ghostwriternr as code owners November 25, 2025 11:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants