Skip to content

Commit 8ccf8bf

Browse files
Add guide section for per-command env and cwd options
Add comprehensive guide section showing how to use per-command environment variables and working directory options. Updates troubleshooting to recommend the cwd option as best practice. Changes: - New section on setting environment variables and working directory - Examples showing env and cwd options individually and combined - Clear explanation that values do not persist - Updated troubleshooting to show cwd as best practice Synced from cloudflare/sandbox-sdk PR #204 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent 084eb8a commit 8ccf8bf

File tree

1 file changed

+44
-3
lines changed

1 file changed

+44
-3
lines changed

src/content/docs/sandbox/guides/execute-commands.mdx

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -133,6 +133,42 @@ await sandbox.exec('python /workspace/analyze.py data.csv');
133133
```
134134
</TypeScriptExample>
135135

136+
## Set environment variables and working directory
137+
138+
Use per-command options to temporarily set environment variables or change the working directory for a specific command without affecting the session state:
139+
140+
<TypeScriptExample>
141+
```
142+
// Set environment variables for a single command
143+
const result = await sandbox.exec('python train.py', {
144+
env: {
145+
MODEL_PATH: '/workspace/models',
146+
BATCH_SIZE: '32',
147+
LEARNING_RATE: '0.001'
148+
}
149+
});
150+
151+
// Run command in specific directory
152+
await sandbox.exec('npm run build', {
153+
cwd: '/workspace/my-project'
154+
});
155+
156+
// Combine both options
157+
await sandbox.exec('node server.js', {
158+
env: { NODE_ENV: 'production', PORT: '3000' },
159+
cwd: '/workspace/backend'
160+
});
161+
162+
// Environment variables are scoped to the command only
163+
const check = await sandbox.exec('echo $MODEL_PATH');
164+
console.log(check.stdout); // Empty - MODEL_PATH does not persist
165+
```
166+
</TypeScriptExample>
167+
168+
:::note
169+
Per-command `env` and `cwd` options are temporary and do not persist to the session. For persistent environment variables and working directories, create a [session](/sandbox/api/sessions/) with `createSession()`.
170+
:::
171+
136172
## Best practices
137173

138174
- **Check exit codes** - Always verify `result.success` and `result.exitCode`
@@ -158,14 +194,19 @@ if (!check.success) {
158194

159195
### Working directory issues
160196

161-
Use absolute paths or change directory:
197+
Use the `cwd` option for reliable directory changes:
162198

163199
<TypeScriptExample>
164200
```
165-
// Use absolute path
201+
// Best practice - use cwd option
202+
await sandbox.exec('python script.py', {
203+
cwd: '/workspace/my-app'
204+
});
205+
206+
// Alternative - use absolute path
166207
await sandbox.exec('python /workspace/my-app/script.py');
167208
168-
// Or change directory
209+
// Works but less reliable - change directory in command
169210
await sandbox.exec('cd /workspace/my-app && python script.py');
170211
```
171212
</TypeScriptExample>

0 commit comments

Comments
 (0)