ConTree SDK

Use one sandbox session to run commands, read and write files, search contents, and list directories. Save the filesystem as an image when you need to continue later or try a different approach.

This checkout contains the breaking 0.5 development API. Install it locally:

pip install -e .
# Include async transport and SQLite support when needed:
pip install -e ".[async]"

Use a sandbox session

The five tools are run, read_file, write_file, grep, and list_dir. Initialize the session from a token or from a saved profile. Use an image available on your endpoint.

Sync

"""Use the five sandbox tools in one session."""

from contree_sdk import create_sandbox_session


def main() -> None:
    with create_sandbox_session(image="tag:alpine:latest") as sandbox_session:
        # Write a file in the sandbox.
        sandbox_session.write_file("/work/message.txt", b"Hello from ConTree!\n")

        # Run a command and print its output.
        result = sandbox_session.run("cat", args=["/work/message.txt"])
        print(result.stdout)

        # Read the file as bytes.
        content = sandbox_session.read_file("/work/message.txt")
        print(content.decode())

        # Search file contents.
        matches = sandbox_session.grep("Hello", path="/work/message.txt")
        print(matches)

        # List the directory with file metadata.
        directory = sandbox_session.list_dir("/work")
        print(directory)


main()

Async

import asyncio

from contree_sdk import create_sandbox_session


async def main() -> None:
    async with create_sandbox_session(image="tag:alpine:latest") as sandbox_session:
        # Write a file in the sandbox.
        await sandbox_session.write_file("/work/message.txt", b"Hello from ConTree!\n")

        # Run a command and print its output.
        result = await sandbox_session.run("cat", args=["/work/message.txt"])
        print(result.stdout)

        # Read the file as bytes.
        content = await sandbox_session.read_file("/work/message.txt")
        print(content.decode())

        # Search file contents.
        matches = await sandbox_session.grep("Hello", path="/work/message.txt")
        print(matches)

        # List the directory with file metadata.
        directory = await sandbox_session.list_dir("/work")
        print(directory)


asyncio.run(main())

The command and file read both print Hello from ConTree!. The search prints /work/message.txt:1:Hello from ConTree!, and the listing shows metadata for message.txt.

The default LazySession (AsyncLazySession for async code) starts a VM on the first command and reuses it for later commands. After 10 idle seconds, it saves the filesystem and stops the VM automatically. The next command starts a new VM from those saved files. Processes and memory do not survive a snapshot. Normal context exit also saves pending changes.

To save after each command, select session_type=ContreeSession for Sync or session_type=ContreeAsyncSession for Async. Each command then uses a separate VM. See the complete save-after-every-command examples.

Follow a workflow

The documentation includes API references and failure-handling examples. The mini-swe-agent 2.4.6 bundled adapter needs a port before it can use this API; see the compatibility note.

Develop and test

uv sync --extra dev --extra docs
uv run pytest

The regular test run executes the Python scenarios in README and docs/ through markdown-pytest. The SDK and stores run normally; fixtures supply transport responses. No server credentials are required. See contributing for checks and how to add a scenario.

Licensed under Apache 2.0. Report vulnerabilities through the process in SECURITY.md.

Standalone programs with embedded tests are in examples/sync/ and examples/async/. See the examples guide for prerequisites and execution commands.