> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenfactory.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Execution contracts

See [Customize the SDK](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/customization.md) for hook ordering, ownership, and implementation obligations.
`RunRequest` describes one command. Executor contracts let adapters use a custom backend.

Public command values and execution contracts for integrations.

## `class RunRequest`

```python theme={null}
class contree_sdk.execution.RunRequest(*, command, shell, args, env, cwd, stdin, stdin_open, files, timeout, disposable, truncate_output_at, preserve_env, hostname, uid, gid, resources_limits, networking)
```

Command configuration passed through the session’s public extension hooks.

Use `dataclasses.replace` to change a request. Arguments and environment
are copied at construction. File sources and stdin remain caller-owned.
Exactly one of `command` and `shell` must be supplied. Results are saved
by default; use `disposable=True` to leave session history unchanged.

### Attributes

**command** `str | None`

**shell** `str | None`

**args** `tuple[str, ...]`

**env** `Mapping[str, str] | None`

**cwd** `str | None`

**stdin** `str | bytes | Path | Readable[str] | Readable[bytes] | AsyncReadable[str] | AsyncReadable[bytes] | None`

str | bytes | Path | [`Readable`](./files#contree_sdk.files.Readable)\[str] | [`Readable`](./files#contree_sdk.files.Readable)\[bytes] | [`AsyncReadable`](./files#contree_sdk.files.AsyncReadable)\[str] | [`AsyncReadable`](./files#contree_sdk.files.AsyncReadable)\[bytes] | None

**stdin\_open** `bool`

**files** `list[str | Path | UploadFileSpec] | dict[str, str | Path | bytes | UploadFileSpec] | None`

list\[str | Path | [`UploadFileSpec`](./files#contree_sdk.files.UploadFileSpec)] | dict\[str, str | Path | bytes | [`UploadFileSpec`](./files#contree_sdk.files.UploadFileSpec)] | None

**timeout** `float | timedelta | None`

**disposable** `bool`

**truncate\_output\_at** `int | None`

**preserve\_env** `bool`

**hostname** `str | None`

**uid** `int | None`

**gid** `int | None`

**resources\_limits** `InstanceResourcesLimits | None`

**networking** `InstanceNetworking | None`

**title** `str`

**timeout\_seconds** `float | None`

## `class OperationContext`

```python theme={null}
class contree_sdk.execution.OperationContext(request, session_id, image_uuid, parent_id, branch, files, attachments, detached, node_id, created_at, position_version, session_cwd, session_env)
```

The effective request and history position captured before remote execution.

### Attributes

**request** `RunRequest`

[`RunRequest`](./execution#contree_sdk.execution.RunRequest)

**session\_id** `str`

**image\_uuid** `str`

**parent\_id** `str | None`

**branch** `str | None`

**files** `tuple[str, ...]`

**attachments** `tuple[StagedFile, ...]`

tuple\[[`StagedFile`](./files#contree_sdk.files.StagedFile), ...]

**detached** `bool`

**node\_id** `str`

**created\_at** `float`

**position\_version** `int`

**session\_cwd** `str | None`

**session\_env** `Mapping[str, str]`

## `class SyncExecutor`

```python theme={null}
class contree_sdk.execution.SyncExecutor()
```

Execution and file access required by synchronous framework adapters.

Implementations own their lifecycle. Adapters do not close executors.
Successful execution returns the client’s InstanceResult, including nonzero
exit codes. read\_file returns exact bytes or raises a client API exception.

### Attributes

**session\_id** `str`

### Methods

#### `execute()`

```python theme={null}
@abstractmethod
def execute(request) -> InstanceResult
```

**request** *required*

**returns** `InstanceResult`

#### `read_file()`

```python theme={null}
@abstractmethod
def read_file(path) -> bytes
```

**path** *required*

**returns** `bytes`

#### `write_file()`

```python theme={null}
def write_file(path, content) -> None
```

Write bytes to an absolute path, creating its parent directories.

Returns after the write is applied to the executor’s filesystem. It does
not merely stage a file or upload a blob. Persistence follows execute().
The default runs mkdir and cat through execute() with binary stdin.
Override this method to use another file-transfer mechanism. An override
must coordinate with the executor’s commands and snapshot lifecycle.

Invalid paths raise ValueError; a failed write raises FileWriteError.
Transport errors, timeouts, and cancellation propagate unchanged.

**path** *required*

**content** *required*

**returns** `None`

## `class AsyncExecutor`

```python theme={null}
class contree_sdk.execution.AsyncExecutor()
```

Native asynchronous execution and file access for framework adapters.

### Attributes

**session\_id** `str`

### Methods

#### `execute()`

```python theme={null}
def execute(request) -> InstanceResult
```

**request** *required*

**returns** `InstanceResult`

#### `read_file()`

```python theme={null}
def read_file(path) -> bytes
```

**path** *required*

**returns** `bytes`

#### `write_file()`

```python theme={null}
async def write_file(path, content) -> None
```

Write bytes with the same contract as SyncExecutor.write\_file.

The default awaits execute() with binary stdin. Override with native
async file transfer, coordinating with commands and snapshot lifecycle.
Returns after application, not after staging or blob upload. Invalid paths
raise ValueError; a failed write raises FileWriteError. Transport errors,
timeouts, and cancellation propagate unchanged.

**path** *required*

**content** *required*

**returns** `None`

Public lifecycle contracts for operation and subprocess implementations.

## `class SubprocessContract`

```python theme={null}
class contree_sdk.session.contracts.SubprocessContract()
```

Waitable event stream for one subprocess. Iteration and wait share completion state.

### Attributes

**spid** `int`

### Methods

#### `wait()`

```python theme={null}
@abstractmethod
def wait(*, timeout) -> InstanceResult
```

**timeout** (default: None)

**returns** `InstanceResult`

#### `pipe_to()`

```python theme={null}
@abstractmethod
def pipe_to(*, stdout, stderr) -> InstanceResult
```

**stdout** (default: None)

**stderr** (default: None)

**returns** `InstanceResult`

## `class AsyncSubprocessContract`

```python theme={null}
class contree_sdk.session.contracts.AsyncSubprocessContract()
```

Waitable event stream for one subprocess. Iteration and wait share completion state.

### Attributes

**spid** `int`

### Methods

#### `wait()`

```python theme={null}
def wait(*, timeout) -> InstanceResult
```

**timeout** (default: None)

**returns** `InstanceResult`

#### `pipe_to()`

```python theme={null}
def pipe_to(*, stdout, stderr) -> InstanceResult
```

**stdout** (default: None)

**stderr** (default: None)

**returns** `InstanceResult`

## `class OperationContract`

```python theme={null}
class contree_sdk.session.contracts.OperationContract()
```

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

### Attributes

**uuid** `str`

**context** `OperationContext | None`

[`OperationContext`](./execution#contree_sdk.execution.OperationContext) | None

**response** `OperationResponse | None`

### Methods

#### `add_observer()`

```python theme={null}
def add_observer(observer) -> None
```

Register an observer before starting the shared operation reader.

A None event marks EOF, with an optional stream error. Observers must
not consume events or wait for this operation. Implementations without
this optional facility reject registration.

**observer** *required*

**returns** `None`

#### `events()`

```python theme={null}
@abstractmethod
def events(*, since, spid, timeout) -> Iterator[OperationEvent]
```

**since** (default: None)

**spid** (default: None)

**timeout** (default: None)

**returns** `Iterator[OperationEvent]`

#### `status()`

```python theme={null}
@abstractmethod
def status(*, inflight) -> OperationResponse
```

**inflight** (default: False)

**returns** `OperationResponse`

#### `send_stdin()`

```python theme={null}
@abstractmethod
def send_stdin(data, *, spid, close) -> None
```

**data** *required*

**spid** (default: 1)

**close** (default: True)

**returns** `None`

#### `pipe_stdin()`

```python theme={null}
@abstractmethod
def pipe_stdin(chunks, *, spid, close, chunk_size) -> StdinResult
```

**chunks** *required*

**spid** (default: 1)

**close** (default: True)

**chunk\_size** (default: 65536)

**returns** `StdinResult`

[`StdinResult`](./session#contree_sdk.session.StdinResult)

#### `signal()`

```python theme={null}
@abstractmethod
def signal(sig, *, spid) -> None
```

**sig** (default: None)

**spid** (default: 1)

**returns** `None`

#### `cancel()`

```python theme={null}
@abstractmethod
def cancel() -> None
```

**returns** `None`

#### `wait()`

```python theme={null}
@abstractmethod
def wait(*, timeout) -> InstanceResult
```

**timeout** (default: None)

**returns** `InstanceResult`

#### `run()`

```python theme={null}
@abstractmethod
def run(command, *, shell, args, env, cwd, uid, gid, stdin, stdin_open, truncate_output_at) -> SubprocessContract
```

**command** *required*

**shell** (default: False)

**args** (default: ())

**env** (default: None)

**cwd** (default: None)

**uid** (default: None)

**gid** (default: None)

**stdin** (default: None)

**stdin\_open** (default: False)

**truncate\_output\_at** (default: None)

**returns** `SubprocessContract`

[`SubprocessContract`](./execution#contree_sdk.session.contracts.SubprocessContract)

#### `shutdown()`

```python theme={null}
@abstractmethod
def shutdown() -> None
```

**returns** `None`

## `class AsyncOperationContract`

```python theme={null}
class contree_sdk.session.contracts.AsyncOperationContract()
```

An operation lifecycle. wait stores response before returning; cleanup preserves primary errors.

### Attributes

**uuid** `str`

**context** `OperationContext | None`

[`OperationContext`](./execution#contree_sdk.execution.OperationContext) | None

**response** `OperationResponse | None`

### Methods

#### `add_observer()`

```python theme={null}
def add_observer(observer) -> None
```

Register an observer before starting the shared operation reader.

A None event marks EOF, with an optional stream error. Observers must
not consume events or wait for this operation. Implementations without
this optional facility reject registration.

**observer** *required*

**returns** `None`

#### `events()`

```python theme={null}
@abstractmethod
def events(*, since, spid, timeout) -> AsyncIterator[OperationEvent]
```

**since** (default: None)

**spid** (default: None)

**timeout** (default: None)

**returns** `AsyncIterator[OperationEvent]`

#### `status()`

```python theme={null}
def status(*, inflight) -> OperationResponse
```

**inflight** (default: False)

**returns** `OperationResponse`

#### `send_stdin()`

```python theme={null}
def send_stdin(data, *, spid, close) -> None
```

**data** *required*

**spid** (default: 1)

**close** (default: True)

**returns** `None`

#### `pipe_stdin()`

```python theme={null}
def pipe_stdin(chunks, *, spid, close, chunk_size) -> StdinResult
```

**chunks** *required*

**spid** (default: 1)

**close** (default: True)

**chunk\_size** (default: 65536)

**returns** `StdinResult`

[`StdinResult`](./session#contree_sdk.session.StdinResult)

#### `signal()`

```python theme={null}
def signal(sig, *, spid) -> None
```

**sig** (default: None)

**spid** (default: 1)

**returns** `None`

#### `cancel()`

```python theme={null}
def cancel() -> None
```

**returns** `None`

#### `wait()`

```python theme={null}
def wait(*, timeout) -> InstanceResult
```

**timeout** (default: None)

**returns** `InstanceResult`

#### `run()`

```python theme={null}
def run(command, *, shell, args, env, cwd, uid, gid, stdin, stdin_open, truncate_output_at) -> AsyncSubprocessContract
```

**command** *required*

**shell** (default: False)

**args** (default: ())

**env** (default: None)

**cwd** (default: None)

**uid** (default: None)

**gid** (default: None)

**stdin** (default: None)

**stdin\_open** (default: False)

**truncate\_output\_at** (default: None)

**returns** `AsyncSubprocessContract`

[`AsyncSubprocessContract`](./execution#contree_sdk.session.contracts.AsyncSubprocessContract)

#### `shutdown()`

```python theme={null}
def shutdown() -> None
```

**returns** `None`