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.

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

# Get client
client = Contree(token=token)

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

See Contree for all client options.

Sync

# Get client
client = ContreeSync(token=token)

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

See ContreeSync for all client options.

Working with Images

Images are the foundation of Contree. You can pull existing images from registries or work with images that are already available in your Contree environment.

Pulling Images

You can pull images in several ways - by UUID, by tag, and from external registries:

Async

print(f"Selected {image_uuid=}")
print(f"Selected {image_tag=}")

print("\nPulling by UUID:")
result = await client.images.pull(image_uuid)
print(f"Pull by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nPulling by tag:")
result = await client.images.pull(image_tag)
print(f"Pull by tag: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nImporting public image:")
result = await client.images.pull("docker://ghcr.io/linuxserver/code-server:latest")
print(f"Import public: {result.uuid=}, {result.tag=}, {result.state=}")

See pull() for all image pulling options.

Sync

print(f"Selected {image_uuid=}")
print(f"Selected {image_tag=}")

print("\nPulling by UUID:")
result = client.images.pull(image_uuid)
print(f"Pull by UUID: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nPulling by tag:")
result = client.images.pull(image_tag)
print(f"Pull by tag: {result.uuid=}, {result.tag=}, {result.state=}")

print("\nImporting public image:")
result = client.images.pull("docker://ghcr.io/linuxserver/code-server:latest")
print(f"Import public: {result.uuid=}, {result.tag=}, {result.state=}")

See pull() for all image pulling options.

Image Sources

You can pull images from several sources:

• By tag: "ubuntu:latest" - Pull from your Contree registry

• By UUID: "550e8400-e29b-41d4-a716-446655440000" - Pull a specific image version

• Docker Hub: "docker://docker.io/busybox:latest" - Import from Docker Hub

• Other registries: "docker://ghcr.io/user/image:tag" - Import from other Docker registries

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

image = await client.images.pull("busybox:latest")
print(f"Pulled {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.

Sync

image = client.images.pull("busybox:latest")
print(f"Pulled {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