Skip to main content

Dart 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 Dart SDK is not available on To use the SDK, you must use the Pieces Dart SDK GitHub repository when adding the dependency to your project.


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. Add the SDK dependency: Add the SDK dependency to your Dart project by adding the following to your pubspec.yaml file:


Getting Started

We will create a Dart script to test the connection to the Pieces OS server.


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 main.dart file and add the following code:

import 'package:pieces_os_client/api.dart';

Future<void> main() async {
final platform = Platform.operatingSystem;
// Defining the port based on the operating system. For Linux, the port is 5323, and for macOS/Windows, the port is 1000.
final port = platform == 'linux' ? 5323 : 1000;

final configuration = Configuration();
// The `basePath` defaults to http://localhost:1000, however we need to change it to the correct port based on the operating system.
configuration.basePath = 'http://localhost:$port';

// Initialize the Pieces ApiClient
final apiClient = ApiClient(configuration);
// Create an instance of the WellKnownApi class
final apiInstance = WellKnownApi(apiClient);

try {
// Retrieve the (wellknown) health of the Pieces OS
final result = await apiInstance.getWellKnownHealth();
print('The response of WellKnownApi().getWellKnownHealth:');
print(result); // Response: ok
} catch (e) {
print('Exception when calling WellKnownApi->getWellKnownHealth: $e\n');

Run the following command to execute the script:

dart main.dart

Next Steps

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

For more information on the Dart SDK, refer to the Dart SDK Repo for detailed documentation.