> ## 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.

# Sandbox factories

See [Your first sandbox](https://docs.tokenfactory.nebius.com/sandboxes/sdk/python_sdk/getting-started.md) for complete sync/async programs and connection rules.
All three factory functions accept the configuration parameters of `session_maker`.

Connect the SDK abstractions through a simple, extensible sandbox interface.

ConTree’s stateless execution model differs from a classic stateful sandbox:
filesystem state passes between executions through images and snapshots. This
module assembles clients, sessions, stores, and policies to provide a
familiar sandbox workflow without requiring users to connect each component.

The default lazy session reuses a VM between commands. Snapshots preserve files,
but do not preserve running processes or memory. Advanced users can select or
extend session classes, supply components, and configure policies while keeping
control over execution, state, and resource ownership.

## `class SandboxConfig`

```python theme={null}
class contree_sdk.sandbox.SandboxConfig(image, url, project, token, auth_type, profile, config_path, session_type, session_id, node_id, store, cache_ttl, cwd, env, commit_policy, file_transfer, session_kwargs, client, client_type, client_kwargs)
```

### Attributes

**image** `str | None`

**url** `str | None`

**project** `str | None`

**token** `str | None`

**auth\_type** `Literal['iam', 'jwt'] | None`

**profile** `Profile | str | None`

**config\_path** `str | Path | None`

**session\_type** `type[SyncExecutor | AsyncExecutor] | None`

type\[[`SyncExecutor`](./execution#contree_sdk.execution.SyncExecutor) | [`AsyncExecutor`](./execution#contree_sdk.execution.AsyncExecutor)] | None

**session\_id** `str | None`

**node\_id** `str | None`

**store** `SyncStore | AsyncStore | None`

[`SyncStore`](./store#contree_sdk.store.SyncStore) | [`AsyncStore`](./store#contree_sdk.store.AsyncStore) | None

**cache\_ttl** `float`

**cwd** `str | None`

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

**commit\_policy** `AbstractCommitPolicy | None`

[`AbstractCommitPolicy`](./session#contree_sdk.session.AbstractCommitPolicy) | None

**file\_transfer** `SyncFileTransfer | AsyncFileTransfer | None`

[`SyncFileTransfer`](./files#contree_sdk.files.SyncFileTransfer) | [`AsyncFileTransfer`](./files#contree_sdk.files.AsyncFileTransfer) | None

**session\_kwargs** `dict[str, Any]`

**client** `ContreeSyncClient | ContreeAsyncClient | None`

**client\_type** `type[ContreeSyncClient | ContreeAsyncClient] | None`

**client\_kwargs** `dict[str, Any]`

### Methods

#### `connection()`

```python theme={null}
def connection() -> ConnectionConfig
```

**returns** `ConnectionConfig`

#### `resolve_profile()`

```python theme={null}
def resolve_profile() -> Profile
```

**returns** `Profile`

#### `validate()`

```python theme={null}
def validate(*, asynchronous) -> None
```

**asynchronous** *required*

**returns** `None`

#### `session_arguments()`

```python theme={null}
def session_arguments(store, transfer) -> tuple[dict[str, Any], dict[str, Any]]
```

**store** *required*

**transfer** *required*

**returns** `tuple[dict[str, Any], dict[str, Any]]`

## `class SyncSandboxSessionContext`

```python theme={null}
class contree_sdk.sandbox.SyncSandboxSessionContext(config)
```

Construct a synchronous session and unwind its owned resources.

### Methods

#### `__enter__()`

```python theme={null}
def __enter__() -> TypeVar(SyncSessionT, bound= SyncExecutor)
```

**returns** `TypeVar(SyncSessionT, bound= SyncExecutor)`

TypeVar(SyncSessionT, bound= [`SyncExecutor`](./execution#contree_sdk.execution.SyncExecutor))

## `class AsyncSandboxSessionContext`

```python theme={null}
class contree_sdk.sandbox.AsyncSandboxSessionContext(config)
```

Construct a native async session and join cleanup despite cancellation.

### Methods

#### `__aenter__()`

```python theme={null}
async def __aenter__() -> TypeVar(AsyncSessionT, bound= AsyncExecutor)
```

**returns** `TypeVar(AsyncSessionT, bound= AsyncExecutor)`

TypeVar(AsyncSessionT, bound= [`AsyncExecutor`](./execution#contree_sdk.execution.AsyncExecutor))

## `class SandboxSessionContext`

```python theme={null}
class contree_sdk.sandbox.SandboxSessionContext(config)
```

Compose sync and async contexts with one shared, single-use boundary.

Construction performs no I/O. Entry chooses the context mode explicitly.
Re-entry, nesting, and switching modes on the same object are rejected.

### Methods

#### `__enter__()`

```python theme={null}
def __enter__() -> TypeVar(SyncSessionT, bound= SyncExecutor)
```

**returns** `TypeVar(SyncSessionT, bound= SyncExecutor)`

TypeVar(SyncSessionT, bound= [`SyncExecutor`](./execution#contree_sdk.execution.SyncExecutor))

#### `__aenter__()`

```python theme={null}
async def __aenter__() -> TypeVar(AsyncSessionT, bound= AsyncExecutor)
```

**returns** `TypeVar(AsyncSessionT, bound= AsyncExecutor)`

TypeVar(AsyncSessionT, bound= [`AsyncExecutor`](./execution#contree_sdk.execution.AsyncExecutor))

## `create_sandbox_session()`

```python theme={null}
def contree_sdk.sandbox.create_sandbox_session(*, session_type, **kwargs) -> SandboxSessionContext[Any, Any]
```

Create a single-use context supporting both with and async with.

**session\_type** (default: None)

\*\***kwargs**

**returns** `SandboxSessionContext[Any, Any]`

[`SandboxSessionContext`](./sandbox#contree_sdk.sandbox.SandboxSessionContext)\[Any, Any]

A composed context. See session\_maker for all configuration parameters.

## `create_sync_sandbox_session()`

```python theme={null}
def contree_sdk.sandbox.create_sync_sandbox_session(*, session_type, **kwargs) -> SyncSandboxSessionContext[Any]
```

Create a sync-only context; its default session is LazySession.

**session\_type** (default: None)

\*\***kwargs**

**returns** `SyncSandboxSessionContext[Any]`

[`SyncSandboxSessionContext`](./sandbox#contree_sdk.sandbox.SyncSandboxSessionContext)\[Any]

A synchronous context with the configuration accepted by session\_maker.

## `create_async_sandbox_session()`

```python theme={null}
def contree_sdk.sandbox.create_async_sandbox_session(*, session_type, **kwargs) -> AsyncSandboxSessionContext[Any]
```

Create an async-only context; its default session is AsyncLazySession.

**session\_type** (default: None)

\*\***kwargs**

**returns** `AsyncSandboxSessionContext[Any]`

[`AsyncSandboxSessionContext`](./sandbox#contree_sdk.sandbox.AsyncSandboxSessionContext)\[Any]

An asynchronous context with the configuration accepted by session\_maker.

## `session_maker()`

```python theme={null}
def contree_sdk.sandbox.session_maker(context_type, /, *, image, url, project, token, auth_type, profile, config_path, session_type, session_id, node_id, store, cache_ttl, cwd, env, commit_policy, file_transfer, session_kwargs, client, client_type, **client_kwargs) -> TypeVar(ContextT)
```

Prepare a sync/async sandbox context without opening connections or a VM.

Without session\_type, entry selects LazySession or AsyncLazySession. Explicit
classes must implement SyncExecutor or AsyncExecutor and match the context
mode. Lazy subclasses receive a base session; other classes receive a client
and the standard ContreeSession constructor keywords. session\_kwargs adds
arguments to the selected class, never to the underlying lazy base session.
Factory-managed arguments take priority over duplicates in session\_kwargs.

Connection arguments, an explicit profile/config\_path, and a borrowed client
are separate sources. Without an explicit source, use the client’s environment
profile, then its default INI resolution. client\_kwargs is forwarded unchanged
to the selected client’s from\_profile constructor.

The default lazy policy snapshots after 10 idle seconds. Normal exit saves
pending work; exceptional exit discards unsaved work. Snapshots retain files,
not running processes. ContreeSession and ContreeAsyncSession save each command
by default in a separate VM. Pass disposable=True to leave their history unchanged.

**context\_type** *required*

**image** (default: None)

**url** (default: None)

**project** (default: None)

**token** (default: None)

**auth\_type** (default: None)

**profile** (default: None)

**config\_path** (default: None)

**session\_type** (default: None)

**session\_id** (default: None)

**node\_id** (default: None)

**store** (default: None)

**cache\_ttl** (default: 60)

**cwd** (default: None)

**env** (default: None)

**commit\_policy** (default: None)

**file\_transfer** (default: None)

**session\_kwargs** (default: None)

**client** (default: None)

**client\_type** (default: None)

\*\***client\_kwargs**

**returns** `TypeVar(ContextT)`

A single-use context owning its created client, memory store, and session.
Supplied clients, stores, and file transfers remain caller-owned.

## `profile_from_args()`

```python theme={null}
def contree_sdk.connection.profile_from_args(*, token, url, project, auth_type) -> Profile
```

Build an explicit client profile without reading or writing configuration.

The default configuration uses the client’s endpoint when URL is omitted.

**token** *required*

**url** (default: None)

**project** (default: None)

**auth\_type** (default: 'iam')

**returns** `Profile`

A regular contree-client Profile.

**raises**

**ValueError** – Credentials, URL, or authentication type are invalid.