tinker_cookbook.sandbox.SandboxInterface

class tinker_cookbook.sandbox.SandboxInterface (Protocol)

Interface for a sandbox.

Implementations must provide: run_command, read_file, write_file, send_heartbeat, and cleanup.

property sandbox_id

Identifier for the sandbox instance (e.g. Modal object_id).

Returns: str

send_heartbeat (timeout)

Send a heartbeat to keep the sandbox alive.

If the sandbox server does not support heartbeat, this method can be a no-op.

Parameters:

• timeout ( int)

Returns: None

run_command (command, workdir, timeout, max_output_bytes)

Run a command in the sandbox.

Setting workdir=None will run the command in the default WORKDIR set in the container image (Dockerfile).

Parameters:

• command ( str) – Shell command string to execute.
• workdir ( str | None) – Working directory for the command.
• timeout ( int) – Timeout in seconds.
• max_output_bytes ( int | None) – Cap stdout/stderr at this many bytes. When None, implementation uses its default (e.g. 128 KB).

Returns: SandboxResult

read_file (path, max_bytes, timeout)

Read the content of a file from the sandbox.

Parameters:

• path ( str) – Path to the file in the sandbox.
• max_bytes ( int | None) – If set, only read up to this many bytes from the file.
• timeout ( int) – Timeout in seconds for the read operation.

Returns: SandboxResult

write_file (path, content, executable, timeout)

Write content to a file in the sandbox.

Parameters:

• path ( str) – Destination path inside the sandbox.
• content ( str | bytes) – File content (str or bytes).
• executable ( bool) – If True, make the file executable.
• timeout ( int) – Timeout in seconds.

Returns: SandboxResult

cleanup()

Clean up the sandbox.

Returns: None