Skip to main content

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

    dependencies {
    implementation 'app.pieces.pieces-os-client:pieces-os-client:1.2.2'

Getting Started


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

import app.pieces.pieces_os_client.infrastructure.*
import app.pieces.pieces_os_client.models.*
import app.pieces.pieces_os_client.apis.*

val platform = System.getProperty("").toLowerCase()
val port = if (platform.contains("linux")) 5323 else 1000

val configuration = Configuration().apply {
basePath = "http://localhost:$port"

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

try {
// Retrieve the (wellknown) health of the Pieces OS
val result: kotlin.String = apiInstance.getWellKnownHealth()
println("The response of WellKnownApi().getWellKnownHealth:")
println(result) // Response: ok
} catch (e: ClientException) {
println("4xx response calling WellKnownApi#getWellKnownHealth")
} catch (e: ServerException) {
println("5xx response calling WellKnownApi#getWellKnownHealth")

Run the following commands to compile and execute the code:

kotlinc main.kt -include-runtime -d main.jar
java -jar main.jar

Next Steps

If you've made it this far, that means you've successfully connected to your local Pieces OS server using our Kotlin 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 Kotlin SDK, refer to the Kotlin SDK Repo for detailed documentation.