Sandbox factories

See Your first sandbox 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`

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

str | None

Literal['iam', 'jwt'] | None

Profile | str | None

str | Path | None

type[SyncExecutor | AsyncExecutor] | None

type[SyncExecutor | AsyncExecutor] | None

str | None

SyncStore | AsyncStore | None

SyncStore | AsyncStore | None

float

str | None

dict[str, str] | None

AbstractCommitPolicy | None

AbstractCommitPolicy | None

SyncFileTransfer | AsyncFileTransfer | None

SyncFileTransfer | AsyncFileTransfer | None

dict[str, Any]

ContreeSyncClient | ContreeAsyncClient | None

type[ContreeSyncClient | ContreeAsyncClient] | None

dict[str, Any]

Methods

`connection()`

def connection() -> ConnectionConfig

ConnectionConfig

`resolve_profile()`

def resolve_profile() -> Profile

Profile

`validate()`

def validate(*, asynchronous) -> None

required

None

`session_arguments()`

def session_arguments(store, transfer) -> tuple[dict[str, Any], dict[str, Any]]

required

tuple[dict[str, Any], dict[str, Any]]

`class SyncSandboxSessionContext`

class contree_sdk.sandbox.SyncSandboxSessionContext(config)

Construct a synchronous session and unwind its owned resources.

Methods

`enter()`

def __enter__() -> TypeVar(SyncSessionT, bound= SyncExecutor)

TypeVar(SyncSessionT, bound= SyncExecutor)

TypeVar(SyncSessionT, bound= SyncExecutor)

`class AsyncSandboxSessionContext`

class contree_sdk.sandbox.AsyncSandboxSessionContext(config)

Construct a native async session and join cleanup despite cancellation.

Methods

`aenter()`

async def __aenter__() -> TypeVar(AsyncSessionT, bound= AsyncExecutor)

TypeVar(AsyncSessionT, bound= AsyncExecutor)

TypeVar(AsyncSessionT, bound= AsyncExecutor)

`class SandboxSessionContext`

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()`

def __enter__() -> TypeVar(SyncSessionT, bound= SyncExecutor)

TypeVar(SyncSessionT, bound= SyncExecutor)

TypeVar(SyncSessionT, bound= SyncExecutor)

`aenter()`

async def __aenter__() -> TypeVar(AsyncSessionT, bound= AsyncExecutor)

TypeVar(AsyncSessionT, bound= AsyncExecutor)

TypeVar(AsyncSessionT, bound= AsyncExecutor)

`create_sandbox_session()`

def contree_sdk.sandbox.create_sandbox_session(*, session_type, **kwargs) -> SandboxSessionContext[Any, Any]

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

default:"None"

SandboxSessionContext[Any, Any]

SandboxSessionContext[Any, Any]A composed context. See session_maker for all configuration parameters.

`create_sync_sandbox_session()`

def contree_sdk.sandbox.create_sync_sandbox_session(*, session_type, **kwargs) -> SyncSandboxSessionContext[Any]

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

default:"None"

SyncSandboxSessionContext[Any]

SyncSandboxSessionContext[Any]A synchronous context with the configuration accepted by session_maker.

`create_async_sandbox_session()`

def contree_sdk.sandbox.create_async_sandbox_session(*, session_type, **kwargs) -> AsyncSandboxSessionContext[Any]

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

default:"None"

AsyncSandboxSessionContext[Any]

AsyncSandboxSessionContext[Any]An asynchronous context with the configuration accepted by session_maker.

`session_maker()`

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.

required

default:"None"

default:"60"

default:"None"

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()`

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.

required

default:"None"

default:"'iam'"

Profile

A regular contree-client Profile.

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

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Platform Notices

`class SandboxConfig`

Attributes

Methods

`connection()`

`resolve_profile()`

`validate()`

`session_arguments()`

`class SyncSandboxSessionContext`

Methods

`enter()`

`class AsyncSandboxSessionContext`

Methods

`aenter()`

`class SandboxSessionContext`

Methods

`enter()`

`aenter()`

`create_sandbox_session()`

`create_sync_sandbox_session()`

`create_async_sandbox_session()`

`session_maker()`

`profile_from_args()`

​class SandboxConfig

​Attributes

​Methods

​connection()

​resolve_profile()

​validate()

​session_arguments()

​class SyncSandboxSessionContext

​Methods

​__enter__()

​class AsyncSandboxSessionContext

​Methods

​__aenter__()

​class SandboxSessionContext

​Methods

​__enter__()

​__aenter__()

​create_sandbox_session()

​create_sync_sandbox_session()

​create_async_sandbox_session()

​session_maker()

​profile_from_args()

`class SandboxConfig`

Attributes

Methods

`connection()`

`resolve_profile()`

`validate()`

`session_arguments()`

`class SyncSandboxSessionContext`

Methods

`enter()`

`class AsyncSandboxSessionContext`

Methods

`aenter()`

`class SandboxSessionContext`

Methods

`enter()`

`aenter()`

`create_sandbox_session()`

`create_sync_sandbox_session()`

`create_async_sandbox_session()`

`session_maker()`

`profile_from_args()`