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 contree_sdk.sandbox.SandboxConfig(image, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, session_type=None, session_id=None, node_id=None, store=None, cache_ttl=60, cwd=None, env=None, commit_policy=None, file_transfer=None, session_kwargs=<factory>, client=None, client_type=None, client_kwargs=<factory>)

image: str | None

url: str | None = None

project: str | None = None

token: str | None = None

auth_type: Optional[Literal['iam', 'jwt']] = None

profile: Profile | str | None = None

config_path: str | Path | None = None

session_type: type[SyncExecutor | AsyncExecutor] | None = None

session_id: str | None = None

node_id: str | None = None

store: SyncStore | AsyncStore | None = None

cache_ttl: float = 60

cwd: str | None = None

env: dict[str, str] | None = None

commit_policy: AbstractCommitPolicy | None = None

file_transfer: SyncFileTransfer | AsyncFileTransfer | None = None

session_kwargs: dict[str, Any]

client: ContreeSyncClient | ContreeAsyncClient | None = None

client_type: type[ContreeSyncClient | ContreeAsyncClient] | None = None

client_kwargs: dict[str, Any]

connection()

Return type:

ConnectionConfig

resolve_profile()

Return type:

Profile

validate(*, asynchronous)

Return type:

None

session_arguments(store, transfer)

Return type:

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

class contree_sdk.sandbox.SyncSandboxSessionContext(config)

Construct a synchronous session and unwind its owned resources.

__enter__()

Return type:

TypeVar(SyncSessionT, bound= SyncExecutor)

class contree_sdk.sandbox.AsyncSandboxSessionContext(config)

Construct a native async session and join cleanup despite cancellation.

async __aenter__()

Return type:

TypeVar(AsyncSessionT, bound= AsyncExecutor)

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.

__enter__()

Return type:

TypeVar(SyncSessionT, bound= SyncExecutor)

async __aenter__()

Return type:

TypeVar(AsyncSessionT, bound= AsyncExecutor)

contree_sdk.sandbox.create_sandbox_session(*, session_type=None, session_kwargs=None, **kwargs)

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

Pass constructor options for the selected class through session_kwargs. Other keyword arguments configure the factory or its client.

Return type:

SandboxSessionContext[Any, Any]

Returns:

A composed context. See session_maker for all configuration parameters.

contree_sdk.sandbox.create_sync_sandbox_session(*, session_type=None, session_kwargs=None, **kwargs)

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

Pass constructor options for the selected class through session_kwargs. Other keyword arguments configure the factory or its client.

Return type:

SyncSandboxSessionContext[Any]

Returns:

A synchronous context with the configuration accepted by session_maker.

contree_sdk.sandbox.create_async_sandbox_session(*, session_type=None, session_kwargs=None, **kwargs)

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

Pass constructor options for the selected class through session_kwargs. Other keyword arguments configure the factory or its client.

Return type:

AsyncSandboxSessionContext[Any]

Returns:

An asynchronous context with the configuration accepted by session_maker.

contree_sdk.sandbox.session_maker(context_type, /, *, image=None, url=None, project=None, token=None, auth_type=None, profile=None, config_path=None, session_type=None, session_id=None, node_id=None, store=None, cache_ttl=60, cwd=None, env=None, commit_policy=None, file_transfer=None, session_kwargs=None, client=None, client_type=None, **client_kwargs)

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. Created clients use RetryPolicy() unless retry is supplied; retry=None disables retries.

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.

Return type:

TypeVar(ContextT)

Returns:

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

contree_sdk.connection.profile_from_args(*, token, url=None, project=None, auth_type='iam')

Build an explicit client profile without reading or writing configuration.

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

Return type:

Profile

Returns:

A regular contree-client Profile.

Raises:

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