Skip to main content

Python SDK


The Pieces SDK is a powerful code engine package designed for writing applications on top of Pieces OS. It facilitates communication with a locally hosted server to enable features such as copilot chats, asset saving, and more.


The Pieces SDK has the following system requirements:


To get started with the Pieces SDK, follow these steps:

  1. Download Pieces OS: Pieces OS serves as the primary backend service, providing essential functionality for the SDK. Download the appropriate version for your operating system:

  2. Install the PyPI Package: Use pip to install the Pieces SDK package:

    pip install pieces-os-client

Getting Started

First, we will create a Python script to test the connection to the Pieces OS server. This involves creating a file to store your configuration info and a file to test the connection.


It's important to note that the localhost port for Pieces OS is different based on the operating system.

For Linux, you should use localhost:5323.

For macOS and Windows, you should use localhost:1000.

Create a file and add this code to confirm you have installed the correct package:
import pieces_os_client
import platform

# Defining the port based on the operating system. For Linux, the port is 5323, and for macOS/Windows, the port is 1000.
platform_info = platform.platform()
if 'Linux' in platform_info:
port = 5323
port = 1000

# The `basePath` defaults to http://localhost:1000, however we need to change it to the correct port based on the operating system.
configuration = pieces_os_client.Configuration(host=f"http://localhost:{port}")

# Initialize the Pieces ApiClient
api_client = pieces_os_client.ApiClient(configuration)

# Enter a context with an instance of the ApiClient
with pieces_os_client.ApiClient(configuration) as api_client:
# Create an instance of the WellKnownApi class
api_instance = pieces_os_client.WellKnownApi(api_client)

# Retrieve the (wellknown) health of the Pieces OS
api_response = api_instance.get_well_known_health()
print("The response of WellKnownApi().get_well_known_health:")
print(api_response) # Response: ok
except Exception as e:
print("Exception when calling WellKnownApi->get_well_known_health: %s\n" % e)

Run the following command to execute the script:


Next Steps

If you've made it this far, that means you've successfully connected to your local Pieces OS server using our Python SDK! You can now explore the various endpoints available in the SDK to build your application on top of Pieces OS.

Click the Next → button below to dive deeper into the Python SDK documentation.