Last Updated: 3/9/2026
JavaScript Client
A JavaScript client for interacting with the Pie server.
Installation
npm install @pie-project/clientnpm install @pie-project/clientQuick Start
import { PieClient } from '@pie-project/client'; import { PieClient } from '@pie-project/client'; async function main() { async function main() { const client = new PieClient('ws://127.0.0.1:8080'); const client = new PieClient('ws://127.0.0.1:8080'); try { try { 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; } } } } } finally { } finally { await client.close(); await client. close(); } } } } main(); main();PieClient
The main client class for connecting to a Pie server.
Constructor
new PieClient(serverUri) new PieClient(serverUri)| Parameter | Type | Description |
|---|---|---|
serverUri | string | WebSocket URI (e.g., "ws://127.0.0.1:8080") |
Methods
| Method | Returns | Description |
|---|---|---|
connect() | Promise<void> | Establish WebSocket connection |
close() | Promise<void> | Close the connection |
authenticate(username) | Promise<void> | Authenticate with server |
uploadProgram(bytes) | Promise<void> | Upload a WASM program |
programExists(hash) | Promise<boolean> | Check if program exists |
launchInstance(hash, args, detached) | Promise<Instance> | Launch by hash |
launchInstanceFromRegistry(name, args, detached) | Promise<Instance> | Launch from registry |
attachInstance(instanceId) | Promise<Instance> | Attach to existing instance |
listInstances() | Promise<Array> | List running instances |
terminateInstance(instanceId) | Promise<void> | Terminate an instance |
ping() | Promise<void> | Check connectivity |
Example
const client = new PieClient('ws://127.0.0.1:8080'); const client = new PieClient('ws://127.0.0.1:8080'); await client.connect(); await client. connect(); await client.authenticate('username'); await client. authenticate('username'); // Upload a custom inferlet
// Upload a custom inferlet const wasmBytes = await fs.promises.readFile('my_inferlet.wasm'); const wasmBytes = await fs. promises. readFile('my_inferlet.wasm'); await client.uploadProgram(wasmBytes); await client. uploadProgram(wasmBytes); // Check if already uploaded
// Check if already uploaded const exists = await client.programExists(programHash); const exists = await client. programExists(programHash);Instance
Represents a running program instance.
Properties
| Property | Type | Description |
|---|---|---|
instanceId | string | Unique instance identifier |
Methods
| Method | Returns | Description |
|---|---|---|
send(message) | Promise<void> | Send a string message |
recv() | Promise<{event, msg}> | Receive next event |
terminate() | Promise<void> | Request termination |
Example
const instance = await client.launchInstanceFromRegistry('chat'); const instance = await client. launchInstanceFromRegistry('chat'); // Send a message
// Send a message await instance.send('What is the meaning of life?'); await instance. send('What is the meaning of life?'); // Receive response
// Receive response const { event, msg } = await instance.recv(); const { event, msg } = await instance. recv(); console.log(msg); console. log(msg); // Terminate when done
// Terminate when done await instance.terminate(); await instance. terminate();Event Types
Events returned by instance.recv():
| Event | Description |
|---|---|
Message | Text message from instance |
Stdout | Streaming stdout output |
Stderr | Streaming stderr output |
Blob | Binary data received |
Completed | Instance finished successfully |
Aborted | Instance was aborted |
Exception | Instance raised an exception |
ServerError | Server-side error |
OutOfResources | Resource limit reached |
Handling Events
while (true) {while (true) { const { event, msg } = await instance.recv(); const { event, msg } = await instance. recv(); switch (event) { switch (event) { case 'Stdout': case 'Stdout': process.stdout.write(msg); process. stdout. write(msg); break; break; case 'Stderr': case 'Stderr': console.error(msg); console. error(msg); break; break; case 'Completed': case 'Completed': console.log('\nDone!'); console. log('\nDone!'); return; return; case 'Exception': case 'Exception': throw new Error(`Inferlet error: ${msg}`); throw new Error(`Inferlet error: ${msg}`); case 'ServerError': case 'ServerError': throw new Error(`Server error: ${msg}`); throw new Error(`Server error: ${msg}`); } } } }Detached Instances
Launch instances that persist after disconnection:
// Launch detached
// Launch detached const instance = await client.launchInstanceFromRegistry( const instance = await client. launchInstanceFromRegistry( 'long-task', 'long-task', [], [], true // detached true
// detached ); ); const instanceId = instance.instanceId; const instanceId = instance. instanceId; // Disconnect
// Disconnect await client.close(); await client. close(); // Later, reconnect and attach
// Later, reconnect and attach const client2 = new PieClient('ws://127.0.0.1:8080'); const client2 = new PieClient('ws://127.0.0.1:8080'); await client2.connect(); await client2. connect(); await client2.authenticate('username'); await client2. authenticate('username'); const attached = await client2.attachInstance(instanceId); const attached = await client2. attachInstance(instanceId); const { event, msg } = await attached.recv(); const { event, msg } = await attached. recv();Browser Usage
The client works in browsers with WebSocket support:
<script type="module">< script type =" module"> import { PieClient } from '@pie-project/client'; import { PieClient } from '@pie-project/client'; const client = new PieClient('ws://localhost:8080'); const client = new PieClient('ws://localhost:8080'); await client.connect(); await client. connect(); // ...
// ... </script> </ script>Error Handling
try {try { await client.connect(); await client. connect(); await client.authenticate('username'); await client. authenticate('username'); } catch (error) {} catch (error) { if (error.message.includes('ECONNREFUSED')) { if (error. message. includes('ECONNREFUSED')) { console.error('Server not running'); console. error('Server not running'); } else { } else { console.error('Connection error:', error); console. error('Connection error:', error); } } } }