Last Updated: 3/9/2026
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-clientBasic 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/clientBasic 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:
| Event | Description |
|---|---|
Message | Text message from the inferlet |
Stdout | Streaming stdout output |
Stderr | Streaming stderr output |
Blob | Binary data |
Completed | Inferlet finished successfully |
Aborted | Inferlet was aborted |
Exception | Inferlet raised an exception |
ServerError | Server-side error |
OutOfResources | Resource 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