Execute Shell Commands

Run shell commands directly in your sandbox environment.

sandbox.execute(
    command: str,
    timeout: int = 10000,
    streaming: bool = False,
    callback: Optional[Callable[[dict], None]] = None
) -> ExecuteResult

Parameters

commandstringrequired

Shell command to execute (e.g., ls -la, python -V).

timeoutint

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

streamingbool

Enable real-time streaming of stdout/stderr as command 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 command.

stderrstr

Standard error from the command.

returncodeint

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

commandstr

The original command that was executed.

Examples

Basic Example

from concave import Sandbox

sbx = Sandbox.create()

result = sbx.execute("uname -a")
print(f"Output: {result.stdout}")
print(f"Exit code: {result.returncode}")

sbx.delete()

File Operations

from concave import Sandbox

sbx = Sandbox.create()

sbx.execute("echo 'Hello World' > /tmp/test.txt")
result = sbx.execute("cat /tmp/test.txt")
print(result.stdout)  # Hello World

sbx.delete()

With Timeout

from concave import Sandbox, SandboxTimeoutError

sbx = Sandbox.create()

try:
    result = sbx.execute("sleep 5", timeout=2000)
except SandboxTimeoutError as e:
    print(f"Timed out: {e}")
finally:
    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']}")

# Stream output in real-time as command executes
result = sbx.execute(
    "for i in 1 2 3; do echo \"Line $i\"; sleep 1; done",
    streaming=True,
    callback=on_event
)

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

Exceptions

SandboxValidationErrorException

Raised when the command is empty or invalid.

SandboxNotFoundErrorException

Raised when the sandbox no longer exists.

SandboxTimeoutErrorException

Raised when command execution exceeds the timeout duration.

SandboxConnectionErrorException

Raised when unable to connect to the sandbox service.

Error Handling

from concave import (
    Sandbox,
    SandboxValidationError,
    SandboxTimeoutError
)

sbx = Sandbox.create()

try:
    result = sbx.execute("invalid command")
    print(result.stdout)
except SandboxValidationError as e:
    print(f"Invalid command: {e}")
except SandboxTimeoutError as e:
    print(f"Command timed out: {e}")
finally:
    sbx.delete()