Skip to Content
docsTutorialsClient Basics

Last Updated: 3/9/2026


Skip to main content

Client Basics

Learn how to connect to a running Pie server and interact with inferlets.

Prerequisites

  • Pie server running (pie serve)
  • Client library installed

Python Client

Installation

pip install pie-clientpip install pie-client

Basic Usage

import asyncio import asyncio from pie import PieClient from pie import PieClient async def main(): async def main(): async with PieClient("ws://127.0.0.1:8080") as client: async with PieClient("ws://127.0.0.1:8080") as client: # Authenticate (required even if auth is disabled) # Authenticate (required even if auth is disabled) await client.authenticate("username") await client. authenticate("username") # Launch an inferlet from the registry # Launch an inferlet from the registry instance = await client.launch_instance_from_registry( instance = await client. launch_instance_from_registry( "text-completion", "text-completion", ["--prompt", "Hello, world!"] ["--prompt", "Hello, world!"] ) ) # Receive output # Receive output while True: while True: event, message = await instance.recv() event, message = await instance. recv() if event.name == "Stdout": if event. name == "Stdout": print(message, end="", flush=True) print(message, end = "", flush = True) elif event.name == "Completed": elif event. name == "Completed": break break elif event.name == "Exception": elif event. name == "Exception": print(f"Error: {message}") print(f"Error: {message} ") break break asyncio.run(main()) asyncio. run(main())

Sending Messages

For interactive inferlets:

async with PieClient("ws://127.0.0.1:8080") as client: async with PieClient("ws://127.0.0.1:8080") as client: await client.authenticate("username") await client. authenticate("username") instance = await client.launch_instance_from_registry("chat") instance = await client. launch_instance_from_registry("chat") # Send a message # Send a message await instance.send("What is the capital of France?") await instance. send("What is the capital of France?") # Receive response # Receive response event, response = await instance.recv() event, response = await instance. recv() print(response) print(response)

Upload Custom Inferlet

async with PieClient("ws://127.0.0.1:8080") as client: async with PieClient("ws://127.0.0.1:8080") as client: await client.authenticate("username") await client. authenticate("username") # Upload the Wasm binary # Upload the Wasm binary with open("my_inferlet.wasm", "rb") as f: with open("my_inferlet.wasm", "rb") as f: await client.upload_program(f.read()) await client. upload_program(f. read()) # Get the program hash (blake3) # Get the program hash (blake3) import hashlib import hashlib program_hash = "..." # Compute blake3 hash program_hash = "..." # Compute blake3 hash # Launch # Launch instance = await client.launch_instance(program_hash, ["--arg", "value"]) instance = await client. launch_instance(program_hash, ["--arg", "value"])

JavaScript Client

Installation

npm install @pie-project/clientnpm install @pie-project/client

Basic Usage

import { PieClient } from '@pie-project/client'; import { PieClient } from '@pie-project/client'; const client = new PieClient('ws://127.0.0.1:8080'); const client = new PieClient('ws://127.0.0.1:8080'); async function main() { async function main() { await client.connect(); await client. connect(); await client.authenticate('username'); await client. authenticate('username'); const instance = await client.launchInstanceFromRegistry( const instance = await client. launchInstanceFromRegistry( 'text-completion', 'text-completion', ['--prompt', 'Hello, world!'] ['--prompt', 'Hello, world!'] ); ); while (true) { while (true) { const { event, msg } = await instance.recv(); const { event, msg } = await instance. recv(); if (event === 'Stdout') { if (event === 'Stdout') { process.stdout.write(msg); process. stdout. write(msg); } else if (event === 'Completed') { } else if (event === 'Completed') { break; break; } else if (event === 'Exception') { } else if (event === 'Exception') { console.error('Error:', msg); console. error('Error:', msg); break; break; } } } } await client.close(); await client. close(); } } main(); main();

Sending Messages

const instance = await client.launchInstanceFromRegistry('chat'); const instance = await client. launchInstanceFromRegistry('chat'); // Send a message // Send a message await instance.send('What is 2 + 2?'); await instance. send('What is 2 + 2?'); // Receive response // Receive response const { event, msg } = await instance.recv(); const { event, msg } = await instance. recv(); console.log(msg); console. log(msg);

Event Types

Both clients receive events from inferlets:

EventDescription
MessageText message from the inferlet
StdoutStreaming stdout output
StderrStreaming stderr output
BlobBinary data
CompletedInferlet finished successfully
AbortedInferlet was aborted
ExceptionInferlet raised an exception
ServerErrorServer-side error
OutOfResourcesResource limit reached

Authentication

Pie supports public key authentication:

from pie import PieClient, ParsedPrivateKey from pie import PieClient, ParsedPrivateKey key = ParsedPrivateKey.from_file("~/.ssh/id_ed25519") key = ParsedPrivateKey. from_file("~/.ssh/id_ed25519") async with PieClient("ws://127.0.0.1:8080") as client: async with PieClient("ws://127.0.0.1:8080") as client: await client.authenticate("username", key) await client. authenticate("username", key)

For development with --no-auth:

await client.authenticate("any_username") # No key needed await client. authenticate("any_username") # No key needed

Next Steps