nebius/contree-sdk

nebius/contree-sdk

Description: Run code in isolated cloud containers. ConTree gives secure sandboxed execution environments with full root access, network, and persistent images.

Language: Python

License: Apache-2.0

Stars: 5

Forks: 0

Open issues: 0

Created: 2026-01-29T11:56:06Z

Pushed: 2026-05-19T08:59:06Z

Default branch: main

Fork: no

Archived: no

README:

📦 ConTree SDK

SDK for ConTree: Sandboxes That Branch Like Git. ConTree is a container runtime purpose-built to support research on SWE agents, providing reproducible, versioned filesystem state — like Git for container execution, accessible from Python.

👉 [See full feature list and use cases in the documentation →](https://docs.contree.dev/sdk/)

📥 Get Started

Installation

Install the SDK from a PyPi:

pip install contree-sdk

Quick Start

🔀 Async Example

import asyncio
from contree_sdk import Contree

async def main():
# Get client
contree = Contree(token="fake-token")

# Use image by tag
image = await contree.images.use("ubuntu:latest")

# Run command
result = await image.run(shell='echo "Hello from Contree!"')

# Output result
print(result.stdout)

asyncio.run(main())

🔁 Sync Example

from contree_sdk import ContreeSync

def main():
# Get client
contree = ContreeSync(token="fake-token")

# Use image by tag
image = contree.images.use("ubuntu:latest")

# Run command
result = image.run(shell='echo "Hello from Contree!"').wait()

# Output result
print(result.stdout)

main()

Examples

Ready to explore more? Check out our comprehensive examples:

• [Session Management](https://github.com/nebius/contree-sdk/tree/main/examples/session) - Working with persistent sessions and state management
• [Image Operations](https://docs.contree.dev/sdk/python_sdk/images.html) - Advanced image pulling, versioning, and management
• [Branching Workflows](https://docs.contree.dev/sdk/python_sdk/branching.html) - Complex workflow patterns with image branching

Explore all examples in the `examples/` directory

---

Development Setup

Prerequisites

• Python 3.10 - 3.13
• uv package manager

Env setup

git clone git@github.com:nebius/contree-sdk.git
cd contree-sdk
uv sync

Running Checks

Linting and formatting with Ruff:

uv run ruff check .
uv run ruff format .

Type checking with basedpyright:

uv run basedpyright

Running Tests

uv run pytest

Documentation Dev Server

make rtd-dev

---

Table of Contents

• [Installation](#installation)
• [Quick Start](#quick-start)
• [Examples](#examples)
• [Development Setup](#development-setup)
• [Prerequisites](#prerequisites)
• [Environment Setup](#env-setup)
• [Running Checks](#running-checks)
• [Running Tests](#running-tests)
• [Documentation Dev Server](#documentation-dev-server)
• [Quick Start (Advanced)](#-quick-start-advanced)
• [Core Concepts](#-core-concepts)
• [Sessions and Versioning](#sessions-and-versioning)
• [Subprocess-like interface](#subprocess-like-interface)
• [Stable image UUID](#stable-image-uuid)
• [Async/sync clients and objects](#asyncsync-clients-and-objects)
• [Advanced Usage](#advanced-usage)
• [Client configuration](#client-configuration)
• [Objects reusing](#objects-reusing)
• [File uploading](#file-uploading)
• [License](#license)

---

---

🚀 Quick Start (Advanced)

🔀 Async Example

import asyncio
import stat

from pathlib import PurePosixPath

from contree_sdk import Contree
from contree_sdk.utils.models.file import UploadFileSpec
from contree_sdk.sdk.objects.image_fs import ImageFile

async def amain():
# create client
contree = Contree(token="fake-token")

# list images
images = await contree.images()

# use image by tag (no API call, resolved at execution time)
ubuntu_image = await contree.images.use("ubuntu:latest")

# pulling image from a remote registry
busybox_image = await contree.images.oci("docker://docker.io/busybox:latest")

# running command
result0 = await ubuntu_image.run(
command="/app.sh",
args=("arg1", "arg2"),
stdin="input",
env=dict(http_proxy="http://10.20.30.40:1234"),
files=[
UploadFileSpec(source="/local/files/app.sh", mode=stat.S_IXUSR),
UploadFileSpec(
source="/local/files/data_ver1.csv", path=PurePosixPath("/data.csv")
),
],
)
print(result0.stdout)
print(result0.stderr)

# running next command
result1 = await result0.run(shell="echo output.csv | grep something")

# getting files and directories by path
items = await result1.ls("files/path")
print(len(items))

# iterating through files and directories by path
for item in await result1.ls("~"):
print(item.name, item.is_dir)
if item.is_file:
# download file
assert isinstance(item, ImageFile)
await item.download("/local/files/downloaded/")

# using session
session = busybox_image.session()
await session.run(
command="/bin/app",
files=[
UploadFileSpec(source="/local/files/app", path="bin/app", mode=stat.S_IXUSR)
],
)
res = await session.run(command="/bin/cat", args=("result.txt",))
print(res.stdout)

# downloading file from session
await session.download("/tmp/log.jsonl", "/local/logs/session_1.log")

# or simply reading from file
content = await session.read("/tmp/log.jsonl")
print(content.decode())

asyncio.run(amain())

🔁 Sync Example

import stat

from contree_sdk import ContreeSync
from contree_sdk.utils.models.file import UploadFileSpec
from contree_sdk.sdk.objects.image_fs import ImageFileSync

def main():
# Create client
contree = ContreeSync(token="fake-token")

# list images
images = contree.images()

# Use image by tag (no API call, resolved at execution time)
ubuntu_image = contree.images.use("ubuntu:latest")

# Pulling image from a remote registry
busybox_image = contree.images.oci("docker://docker.io/busybox:latest")

# running command
result0 = ubuntu_image.run(
command="/app.sh",
args=("arg1", "arg2"),
stdin="input",
env=dict(http_proxy="http://10.20.30.40:1234"),
files=[
UploadFileSpec(source="/local/files/app.sh", mode=stat.S_IXUSR),…