Run Code

Execute Python and JavaScript code securely in isolated sandboxes.

sandbox.run(
    code: str,
    timeout: int = 10000,
    language: str = "python" | "javascript",
    streaming: bool = False,
    callback: Optional[Callable[[dict], None]] = None
) -> RunResult

Parameters

codestringrequired

Python code to execute. Can be a single line or multi-line script.

timeoutint

Timeout in milliseconds. Default: 10000 (10s), 300000 (5min) with streaming=True.

languagestring

Programming language to use. Supported values: python (default) or javascript.

streamingbool

Enable real-time streaming of stdout/stderr as code executes. Defaults to False.

callbackcallable

Optional callback function invoked for each streaming event when streaming=True.

def on_event(event: dict) -> None:
    # event: {
    #   "type": "stdout"|"stderr"|"exit",
    #   "data": "...",
    #   "code": int
    # }
    pass

Returns

stdoutstr

Standard output from the code execution.

stderrstr

Standard error from the code execution.

returncodeint

Exit code from the execution (0 = success, non-zero = error).

codestr

The original code that was executed.

languagestr

The language that was executed ("python" or "javascript").

Examples

Basic Example

from concave import Sandbox

sbx = Sandbox.create()

result = sbx.run("print('Hello from Python!')")
print(result.stdout)  # Hello from Python!

sbx.delete()

JavaScript Code

from concave import Sandbox

sbx = Sandbox.create()

result = sbx.run(
    "console.log('Hello from Node.js!')",
    language="javascript"
)
print(result.stdout)  # Hello from Node.js!

sbx.delete()

Node.js is slower than Python in our benchmarks. Prefer language="python" for performance.

Multi-Line Code

from concave import Sandbox

sbx = Sandbox.create()

code = """
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))
"""

result = sbx.run(code)
print(result.stdout)  # 55

sbx.delete()

Error Handling

from concave import Sandbox

sbx = Sandbox.create()

result = sbx.run("print(1/0)")

if result.returncode != 0:
    print(f"Error: {result.stderr}")
else:
    print(result.stdout)

sbx.delete()

Streaming Output

from concave import Sandbox

sbx = Sandbox.create()

def on_event(event: dict):
    if event["type"] == "stdout":
        print(f"[OUT] {event['data']}")
    elif event["type"] == "stderr":
        print(f"[ERR] {event['data']}")
    elif event["type"] == "exit":
        print(f"[EXIT] code={event['code']}")

code = """
import time
for i in range(5):
    print(f"Processing step {i+1}/5")
    time.sleep(1)
print("Complete!")
"""

# Stream output in real-time as code executes
result = sbx.run(code, streaming=True, callback=on_event)

print(f"\nFinal output:\n{result.stdout}")
sbx.delete()

Long-Running Task with Progress

from concave import Sandbox
import time

sbx = Sandbox.create()

start_time = time.time()
progress_lines = []

def on_progress(event: dict):
    elapsed = time.time() - start_time
    if event["type"] == "stdout":
        progress_lines.append(event["data"])
        print(f"[{elapsed:.1f}s] {event['data']}")

code = """
import sys
import time

# Simulate data processing
for i in range(10):
    print(f"Processing batch {i+1}/10...")
    sys.stdout.flush()
    time.sleep(0.5)
    
print("Processing complete!")
"""

result = sbx.run(
    code,
    streaming=True,
    callback=on_progress,
    timeout=60000  # 1 minute
)

print(f"\nProcessed {len(progress_lines)} status updates")
print(f"Exit code: {result.returncode}")
sbx.delete()

Exceptions

SandboxValidationErrorException

Raised when the code is empty or language is unsupported (only "python" and "javascript" are supported).

SandboxNotFoundErrorException

Raised when the sandbox no longer exists.

SandboxTimeoutErrorException

Raised when code execution exceeds the timeout duration.

SandboxConnectionErrorException

Raised when unable to connect to the sandbox service.