# tinker_cookbook.sandbox.SandboxInterface

## *class* [**tinker_cookbook.sandbox.SandboxInterface**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L27)(*Protocol*)

Interface for a sandbox.

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

### *property* [**sandbox_id**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L35)

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

**Returns:** *str*

### [**send_heartbeat**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L39)(*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**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L39) (*int*)

**Returns:** *None*

### [**run_command**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L46)(*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**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L48) (*str*) – Shell command string to execute.
- [**workdir**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L49) (*str | None*) – Working directory for the command.
- [**timeout**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L50) (*int*) – Timeout in seconds.
- [**max_output_bytes**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L51) (*int | None*) – Cap stdout/stderr at this many bytes. When None, implementation uses its default (e.g. 128 KB).

**Returns:** *[SandboxResult](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/sandbox/sandboxresult/index.md)*

### [**read_file**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L67)(*path*, *max_bytes*, *timeout*)

Read the content of a file from the sandbox.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L68) (*str*) – Path to the file in the sandbox.
- [**max_bytes**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L68) (*int | None*) – If set, only read up to this many bytes from the file.
- [**timeout**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L68) (*int*) – Timeout in seconds for the read operation.

**Returns:** *[SandboxResult](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/sandbox/sandboxresult/index.md)*

### [**write_file**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L79)(*path*, *content*, *executable*, *timeout*)

Write content to a file in the sandbox.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L80) (*str*) – Destination path inside the sandbox.
- [**content**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L80) (*str | bytes*) – File content (str or bytes).
- [**executable**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L80) (*bool*) – If True, make the file executable.
- [**timeout**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L80) (*int*) – Timeout in seconds.

**Returns:** *[SandboxResult](https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/sandbox/sandboxresult/index.md)*

### [**cleanup**](https://github.com/thinking-machines-lab/tinker-cookbook/blob/main/tinker_cookbook/sandbox/sandbox_interface.py#L92)()

Clean up the sandbox.

**Returns:** *None*