Skip to main content

​
Description

Creates a directory at the specified path. Optionally creates parent directories if they don’t exist.

​
Method Signature

async mkdir(
  path: string,
  options?: { recursive?: boolean; sessionId?: string }
): Promise<MkdirResult>

​
Parameters

​
path
string
required
Absolute path where the directory should be created
​
options
object
Optional configuration for the mkdir operation
​
recursive
boolean
default:false
Whether to create parent directories if they don’t exist (equivalent to mkdir -p)
​
sessionId
string
Session ID to use for this operation. If not provided, the default session is used.

​
Returns

​
MkdirResult
object
Result of the mkdir operation
​
success
boolean
Whether the directory was created successfully
​
path
string
Path to the directory that was created
​
recursive
boolean
Whether the operation was performed recursively
​
timestamp
string
ISO 8601 timestamp of when the operation completed
​
exitCode
number
Exit code from the underlying mkdir command (0 = success)

​
Examples

​
Create a single directory

const result = await sandbox.mkdir('/workspace/new-folder');
console.log(result.success); // true

​
Create nested directories

// Create /workspace/a/b/c even if /workspace/a and /workspace/a/b don't exist
const result = await sandbox.mkdir('/workspace/a/b/c', {
  recursive: true
});
console.log(result.path); // '/workspace/a/b/c'

​
Create directory in a specific session

const session = await sandbox.createSession();
await sandbox.mkdir('/workspace/session-dir', {
  sessionId: session.id
});

​
Create directory before writing files

// Ensure directory exists before writing
await sandbox.mkdir('/workspace/data', { recursive: true });
await sandbox.writeFile('/workspace/data/config.json', JSON.stringify(config));

​
Error Handling

The method throws an error if:
  • The directory already exists (not an error with recursive: true)
  • Parent directories don’t exist (without recursive: true)
  • Insufficient permissions
  • The path is invalid
try {
  // This fails if /workspace/parent doesn't exist
  await sandbox.mkdir('/workspace/parent/child');
} catch (error) {
  console.error('Failed to create directory:', error.message);
  // Use recursive option instead
  await sandbox.mkdir('/workspace/parent/child', { recursive: true });
}

​
Notes

  • Default directory permissions are typically 755 (rwxr-xr-x)
  • Using recursive: true is safe even if the directory already exists
  • The /workspace directory is the default working directory in sandboxes

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us