Skip to main content
File sync and async execution patterns.

​
File Sync

Two ways to inject files into containers:
MethodUse CaseCaching
rsyncDirectories, multiple filesYes (3-tier)
uploadSingle files, generated contentNo

​
rsync (Preferred)

{"tool": "rsync", "args": {
  "source": "/project",
  "destination": "/app",
  "exclude": ["__pycache__", ".git", ".venv", "node_modules"]
}}
Returns directory_state_id for use in run. Three-tier caching: Local cache → Cache by hash → Server dedup → Upload. Most files resolve from cache. Reuse across runs: The directory_state_id is valid for the session. Only re-sync when files change.

​
upload (Single Files)

{"tool": "upload", "args": {"content": "print('hello')"}}
Reference in run via files parameter: 
{"files": {"/app/script.py": "file-uuid"}}

​
Async Execution

ModeParameterBehavior
Syncwait=true (default)Blocks until complete
Asyncwait=falseReturns operation_id immediately

​
Parallel Pattern

// Launch async
{"command": "python exp_a.py", "wait": false}  // Returns op-1
{"command": "python exp_b.py", "wait": false}  // Returns op-2
{"command": "python exp_c.py", "wait": false}  // Returns op-3

// Wait for all
{"tool": "wait_operations", "args": {"operation_ids": ["op-1", "op-2", "op-3"]}}

​
wait_operations Modes

  • "all" - Wait for all operations to complete
  • "any" - Return when first operation completes

​
Operation States

StateDescription
PENDINGQueued, not started
EXECUTINGRunning
SUCCESSCompleted successfully
FAILEDCompleted with error
CANCELLEDCancelled by user

​
When to Use Async

Use wait=false when:
  • Running 2+ independent operations
  • Operations are long-running (>10s)
Use wait=true when:
  • Running a single operation
  • Operations must be sequential