---
id: contree-sdk
version: "0.3.6"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# contree-sdk — SDK for ConTree container runtime with versioned filesystem state

License: permissive · Maintenance: active · Downloads: 578.2K/mo

## What it is and what it does

ConTree SDK is a Python client for ConTree, a container runtime designed to support reproducible, versioned execution environments. It exposes both async and sync APIs to run commands, manage images, handle file uploads/downloads, and maintain persistent sessions within containers. The core abstraction treats container filesystem state like Git: you can branch, version, and reproduce execution contexts deterministically.

The SDK depends on httpx for HTTP communication, aiofiles for async file I/O, cattrs for serialization, strenum for enum handling, and typing-extensions for modern type hints. It's actively maintained but in pre-alpha, so the API may change. Use it when you need reproducible, versioned container execution from Python—particularly for research on software engineering agents or workflows requiring deterministic state snapshots.

Use it for:

- Run reproducible commands in versioned container environments for SWE agent research and testing.
- Manage persistent sessions with automatic version tracking across multiple command executions.
- Upload local files to containers, execute workflows, and download results programmatically.
- Branch container filesystem state and explore divergent execution paths like Git branches.
- Integrate container-based sandboxing into Python applications with async/sync flexibility.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Python SDK for ConTree, a container runtime that provides versioned, reproducible filesystem state for container execution with both async and sync interfaces.

Yes, if you need reproducible, versioned container execution from Python and are comfortable with a pre-alpha API. The low install friction, active maintenance, and permissive license make it a reasonable choice for research and agent development. Verify that the ConTree runtime service meets your infrastructure needs before committing to production use.

## Install

pip install contree-sdk
uv add contree-sdk
poetry add contree-sdk

## Installing contree-sdk

Before you install: Low install friction with a pure-Python wheel and five lightweight dependencies. Active maintenance with a recent release (14 days old). Pre-alpha status means the API surface may shift.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; you must include a copy of the license and state significant changes.

Quickstart:

pip install contree-sdk

from contree_sdk import Contree
import asyncio

async def main():
    contree = Contree(token="your-token")
    image = await contree.images.use("ubuntu:latest")
    result = await image.run(shell='echo "Hello"')
    print(result.stdout)

asyncio.run(main())

Requires Python 3.10–3.14; ConTree token needed to authenticate with the container runtime service.

Verify before relying:

- Whether ConTree runtime service is self-hosted or cloud-managed, and what infrastructure setup is required.
- Performance characteristics and latency for typical workloads (command execution, file transfer).
- Stability guarantees and breaking-change policy during pre-alpha phase.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 578.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

container runtime sdk python, versioned filesystem containers, reproducible sandbox execution, async container management, git-like container state, container-runtime, async-first, reproducible-execution

[View on SkillFed](https://skillfed.io/packages/contree-sdk) · [View on PyPI](https://pypi.org/project/contree-sdk/)