Run commands

Use sandbox.run() to execute a command and collect its output. After installing LithosBox, run this example with lithosbox python:

from lithosbox import LithosBox

box = LithosBox()
sandbox = box.sandboxes.create()

result = sandbox.run(["python3", "-c", "print(6 * 7)"]).check()
print(result.stdout)

The result contains stdout, stderr, and exit_code. A nonzero exit code does not raise an exception unless you call .check(). The examples below continue with the same sandbox.

Choose a command format

Pass a string when you want shell features such as pipes and redirects:

sandbox.run("mkdir -p /work && printf 'hello\n' > /work/message.txt").check()
print(sandbox.run("cat /work/message.txt | tr a-z A-Z").check().stdout)

Pass a list when arguments contain filenames, user input, or other values that should be treated literally. Each list item is a separate argument:

message = "hello; this is text"
result = sandbox.run(["printf", "%s\n", message]).check()
print(result.stdout)

Use stdin to send input to a command:

result = sandbox.run(["wc", "-c"], stdin=b"hello").check()
print(result.stdout)

Keep shell state

A regular run() starts a new shell. Files persist, but changes to the working directory or environment variables do not carry into the next call. Use a session for commands that share shell state:

with sandbox.session() as shell:
    shell.run("mkdir -p /work && cd /work").check()
    shell.run("export GREETING=hello").check()
    result = shell.run('printf "%s from %s\n" "$GREETING" "$PWD"').check()
    print(result.stdout)

Closing a session ends its shell. A session keeps state between commands; it does not increase the time allowed for an individual command.

Stream output from a long command

Use stream=True to see a command’s output while it runs. There is no time limit: the command runs until it exits (or until an optional timeout, in seconds), and the call returns an iterator of events right away.

for event in sandbox.run("pytest -q", stream=True):
    if event.kind == "output":
        print(event.fd, event.data.decode(errors="replace"), end="")
    elif event.kind == "exit":
        print("exit code:", event.exit_code, "reason:", event.reason)

Each output event carries raw bytes (event.data) from stdout or stderr (event.fd), in the order the command wrote them. Split lines yourself; a character can span two events. The last event is always exit, with exit_code and a reason: exited, killed, timeout, oom, or sandbox_gone / lost when the sandbox was deleted, stopped or restarted. The output waits in the sandbox, not in the connection, so a dropped connection costs nothing: the iterator reconnects and continues where it left off. Another process can pick the stream up from the same point with sandbox.exec(exec_id=stream.exec_id, from_seq=stream.next_seq, stream=True). stream.kill() stops the command. The sandbox keeps the most recent 8 MiB of a command’s output (less in sandboxes under 512 MiB) and keeps it for 5 minutes after the command ends. A reader that stays away while a command writes more than that sees a gap event naming what it missed; the command itself is never slowed down. Up to 16 streamed commands can run in a sandbox at once. A running streamed command keeps the sandbox awake. Streaming is not available in sessions. Sandboxes created before streaming existed answer 409 with a message saying so; create a new sandbox.

Start a background job

Use background=True for a server or worker that should keep running after the call. It accepts a shell string and returns after the job starts. For a long command whose output you want as it runs, use stream=True instead. Redirect output to a file so you can read it later.

sandbox.files.write(
    "/work/job.py",
    "import time\ntime.sleep(2)\nprint('Job finished')\n",
)
sandbox.run(
    "python3 /work/job.py > /work/job.log 2>&1; echo $? > /work/job.exit",
    background=True,
).check()

Check the result in a later call:

if sandbox.files.exists("/work/job.exit"):
    exit_code = int(sandbox.files.read("/work/job.exit").strip())
    print("Exit code:", exit_code)
    print(sandbox.files.read("/work/job.log"))

A successful start does not mean the job completed successfully. Check its exit file or application status before using the result. A background job that is working (using CPU, holding a connection, or waiting on a timer) keeps the sandbox awake; you do not need a keep-alive loop. A job that is only waiting for input sleeps with the sandbox and continues when it wakes. background=True does not accept stdin or return a process ID. Write input to a file first. If you need to stop the job individually, have it record its process ID and use that ID in a later command.

Command limits

Synchronous run() and session calls allow about 110 seconds. The figure is derived from the platform’s 120-second request budget at the public edge: the command is stopped slightly earlier so you get a clear error rather than a dropped connection. Use stream=True for longer commands. Each argument can contain at most 131,071 bytes, and stdin can contain up to 4 MiB per call. Each output stream is limited to 16 MiB. Sandboxes below 1 GiB RAM can truncate earlier, as can text that expands when JSON-encoded. Check result.truncated before relying on a large result; use files for binary output or larger results. See Work with files for transfer options. When you have collected your results and no longer need the sandbox:

sandbox.delete()
box.close()

Getting Started

Reference

Guides

Choose a command format

Keep shell state

Stream output from a long command

Start a background job

Command limits

​Choose a command format

​Keep shell state

​Stream output from a long command

​Start a background job

​Command limits

Choose a command format

Keep shell state

Stream output from a long command

Start a background job

Command limits