Secure, Fast, and Extensible Sandbox runtime for AI agents.
name: file-operations description: Use OpenSandbox file commands to read, write, upload, download, search, replace, move, delete, and inspect files or directories inside a sandbox. Trigger when users want exact sandbox file manipulation commands instead of generic shell guidance.
OpenSandbox File Operations
Manipulate sandbox files with osb file commands. Choose the operation mode first, then use the matching verification step. Do not mix sandbox-internal edits with host-to-sandbox transfer commands casually.
When To Use
- the user wants to read or write a file inside a sandbox
- the user needs to upload a local file into a sandbox or download a sandbox file back to the host
- the user wants to search, replace, move, chmod, or inspect paths
- the user needs directory creation or cleanup
Config Gate
Run this first:
osb config show -o json
If domain is missing, stop and set it before file commands:
osb config set connection.domain <host:port> -o json
osb config show -o json
If auth is required and api_key is missing, stop and set it before file commands:
osb config set connection.api_key <api-key> -o json
osb config show -o json
Operation Modes
Treat these as distinct categories:
- sandbox-only content operations
cat,write,replace,mv,mkdir,rm,rmdir,info,chmod - host-to-sandbox transfer
upload - sandbox-to-host transfer
download - discovery before modification
search, theninfo
If the path is uncertain, search first. If the file boundary crosses between host and sandbox, use upload or download instead of write or cat.
Golden Paths
Write and verify inside the sandbox:
osb file write <sandbox-id> /workspace/app.txt -c "hello" -o json
osb file cat <sandbox-id> /workspace/app.txt -o raw
Upload from host and verify in the sandbox:
osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
osb file cat <sandbox-id> /workspace/local.txt -o raw
Search before editing:
osb file search <sandbox-id> /workspace --pattern "*.py" -o json
osb file info <sandbox-id> /workspace/main.py -o json
Sandbox-Only File Edits
Read and write:
osb file cat <sandbox-id> /path/to/file -o raw
osb file write <sandbox-id> /path/to/file -c "hello" -o json
Use write with -c/--content when the new content is known directly. If the content should come from stdin, omit -c and pipe or paste the content into the command.
Edit existing content:
osb file replace <sandbox-id> /path/to/file --old old --new new -o json
osb file mv <sandbox-id> /old/path /new/path -o json
Prefer replace for small text substitutions and mv for rename/path changes. Do not rewrite a full file when a targeted replace is enough.
Create directories:
osb file mkdir <sandbox-id> /workspace/output -o json
osb file mkdir <sandbox-id> /workspace/a /workspace/b --mode 755 -o json
Host <-> Sandbox Transfer
Host to sandbox:
osb file upload <sandbox-id> ./local.txt /remote/path/local.txt -o json
Sandbox to host:
osb file download <sandbox-id> /remote/path/result.json ./result.json -o json
Rules:
- use
uploadwhen the source file is on the host - use
downloadwhen the destination should be written to the host filesystem - downloads replace regular files only on success; failures and interruptions preserve the existing regular file
- existing devices and named pipes receive data directly; failures can leave partial output
- stdout aliases such as
/dev/stdoutstream file bytes without a success message in any output format; errors go to stderr, and failures can leave partial output - use
writeandcatonly when the operation stays entirely inside the sandbox
Metadata and Permissions
Inspect metadata:
osb file info <sandbox-id> /path/to/file -o json
osb file info <sandbox-id> /path/one /path/two -o json
Search by pattern:
osb file search <sandbox-id> /workspace --pattern "*.py" -o json
Set permissions:
osb file chmod <sandbox-id> /path/to/script --mode 755 -o json
osb file chmod <sandbox-id> /path/to/file --mode 644 --owner root --group root -o json
Use info after chmod when the user needs to confirm mode, ownership, or timestamps changed as expected.
Destructive Operations
Delete files or directories only after verifying the target path:
osb file info <sandbox-id> /workspace/tmp.txt -o json
osb file rm <sandbox-id> /workspace/tmp.txt -o json
osb file search <sandbox-id> /workspace --pattern "old-*" -o json
osb file rmdir <sandbox-id> /workspace/old-dir -o json
Rules:
- prefer
infowhen the exact path is known - prefer
searchwhen the path is uncertain - do not suggest
rmorrmdiruntil the target has been verified - after
mv,rm, orrmdir, verify the new state withinfoorsearch
Failure Semantics
uploadanddownloadhave host filesystem side effects; treat them as cross-boundary operationsdownloadreplaces regular files on success and writes directly to devices and named pipes, so be explicit about the destination- permission or ownership failures are usually path/runtime permission issues, not a reason to switch away from
osb file - if multiple file commands fail unexpectedly, check sandbox health before assuming a file-command bug
Response Pattern
Structure the answer as:
- exact
osb filecommand - which operation mode it uses
- the next verification command if the workflow continues
Keep command examples concrete and ready to paste.
Minimal Closed Loops
Write and verify:
osb file write <sandbox-id> /workspace/app.txt -c "hello" -o json
osb file cat <sandbox-id> /workspace/app.txt -o raw
Upload and verify:
osb file upload <sandbox-id> ./local.txt /workspace/local.txt -o json
osb file cat <sandbox-id> /workspace/local.txt -o raw
Replace and verify:
osb file replace <sandbox-id> /workspace/app.txt --old hello --new world -o json
osb file cat <sandbox-id> /workspace/app.txt -o raw
Change permissions and inspect:
osb file chmod <sandbox-id> /workspace/script.sh --mode 755 -o json
osb file info <sandbox-id> /workspace/script.sh -o json
Create a directory and inspect it:
osb file mkdir <sandbox-id> /workspace/output -o json
osb file info <sandbox-id> /workspace/output -o json
Move a file and verify the new path:
osb file mv <sandbox-id> /workspace/app.txt /workspace/archive/app.txt -o json
osb file info <sandbox-id> /workspace/archive/app.txt -o json
Delete and verify removal:
osb file info <sandbox-id> /workspace/tmp.txt -o json
osb file rm <sandbox-id> /workspace/tmp.txt -o json
osb file search <sandbox-id> /workspace --pattern "tmp.txt" -o json
Best Practices
- prefer
searchbefore modification when the path is not certain - prefer
infobefore destructive actions - prefer
replaceover full rewrites for small text changes - prefer
uploadanddownloadonly for host boundary crossings - prefer explicit verification after
mv,chmod,rm, andrmdir