# 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/)_

### [**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.thinking-machines.ai/cookbook/api-reference/sandbox/sandboxresult/)_

### [**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.thinking-machines.ai/cookbook/api-reference/sandbox/sandboxresult/)_

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

Clean up the sandbox.

**Returns:** _None_