Getting Started

This guide will help you get up and running with ConTree SDK. By the end of this guide, you’ll understand how to create clients, work with images, and run your first commands.

Configuration

contree_sdk performs no auth, transport, or configuration of its own — Contree/ContreeSync just take an already-constructed contree_client.base.ContreeAsyncClient/ContreeSyncClient (e.g. from contree_client.httpx) as their first argument. Credentials, base URL, timeouts, and retries are entirely contree_client’s concern, configured directly when you build that client:

from contree_client.httpx import ContreeAsyncClient

api_client = ContreeAsyncClient("YOUR-NEBIUS-API-KEY", base_url="https://your-instance.of.contree")

contree_client clients can also be built from a saved profile with from_profile(), which resolves credentials in this order: an explicit profile argument, then the CONTREE_PROFILE environment variable, then the active profile recorded in the profile config file ($CONTREE_HOME/auth.ini, defaulting to ~/.config/contree/auth.ini):

from contree_client.httpx import ContreeAsyncClient

api_client = ContreeAsyncClient.from_profile()

Creating a Client

The first step is to create a ConTree client. You can choose between async and sync versions depending on your application needs. Here’s how to create a client and verify the connection by listing available images:

Async
Sync

sdk = Contree(api_client)

# Get images (to verify that connection works)
await sdk.images()

See Contree for all client options.

# The caller owns the passed client's transport lifecycle.
sdk = ContreeSync(api_client)

# Get images (to verify that connection works)
sdk.images()

See ContreeSync for all client options.

Working with Images

Images are the foundation of ConTree. The simplest way to reference an image is by tag using images.use(), which creates an image object without making an API call:

Async
Sync

image = await contree.images.use("ubuntu:latest")
result = await image.run(shell="echo hello")

image = contree.images.use("ubuntu:latest")
result = image.run(shell="echo hello").wait()

To resolve a tag or UUID upfront via an API call, use images.use(strict=True). To import from an external registry (or return an existing image if already imported), use images.oci(). See Working with Images for a full overview of available methods, examples, and what you can pass as a reference.

Running Commands

Once you have an image, you can run commands inside it. Each command execution creates a new version of the image with your changes.

Basic Command Execution

You can run various shell commands and handle their output:

Async
Sync

sdk = Contree(api_client)
image = await sdk.images.use("busybox:latest")
print(f"Using {image=}")

result = await image.run(shell="echo 'Hello World'")
print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

result = await image.run(shell="pwd")
print(f"Current directory: {result.stdout=}, {result.exit_code=}")

result = await image.run(shell="ls -la")
print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

result = await image.run(shell="cat -", stdin="Hello from stdin\n")
print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

result = await image.run(shell="echo 'Error message' >&2; exit 1")
print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

See run() for all command execution options.

sdk = ContreeSync(api_client)
image = sdk.images.use("busybox:latest")
print(f"Using {image=}")

result = image.run(shell="echo 'Hello World'").wait()
print(f"Simple echo: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

result = image.run(shell="pwd").wait()
print(f"Current directory: {result.stdout=}, {result.exit_code=}")

result = image.run(shell="ls -la").wait()
print(f"Directory listing: {result.stdout=}, {result.exit_code=}")

result = image.run(shell="cat -", stdin="Hello from stdin\n").wait()
print(f"Cat with stdin: {result.stdout=}, {result.exit_code=}")

result = image.run(shell="echo 'Error message' >&2; exit 1").wait()
print(f"Error command: {result.stdout=}, {result.stderr=}, {result.exit_code=}")

See run() for all command execution options.

Understanding the Results

When you run a command, you get back a result object that contains:

stdout: Standard output from the command
stderr: Standard error from the command
exit_code: The exit code (0 for success, non-zero for errors)
uuid: The UUID of the new image version created by this command

Get Started

Inference

Observability

Post-training

Data Lab

Sandboxes

Teams & Access Management

Other Capabilities

Integrations

Platform Notices

Configuration

Creating a Client

Working with Images

Running Commands

Basic Command Execution

Understanding the Results

​Configuration

​Creating a Client

​Working with Images

​Running Commands

​Basic Command Execution

​Understanding the Results

Configuration

Creating a Client

Working with Images

Running Commands

Basic Command Execution

Understanding the Results