Last Updated: 3/9/2026

JavaScript Client

A JavaScript client for interacting with the Pie server.

Installation


npm install @pie-project/client

Quick Start


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

PieClient

The main client class for connecting to a Pie server.

Constructor


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');
 
await client.connect();
await client.authenticate('username');
 
// Upload a custom inferlet
const wasmBytes = await fs.promises.readFile('my_inferlet.wasm');
await client.uploadProgram(wasmBytes);
 
// Check if already uploaded
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');
 
// Send a message
await instance.send('What is the meaning of life?');
 
// Receive response
const { event, msg } = await instance.recv();
console.log(msg);
 
// Terminate when done
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) {
    const { event, msg } = await instance.recv();
    
    switch (event) {
        case 'Stdout':
            process.stdout.write(msg);
            break;
        case 'Stderr':
            console.error(msg);
            break;
        case 'Completed':
            console.log('\nDone!');
            return;
        case 'Exception':
            throw new Error(`Inferlet error: ${msg}`);
        case 'ServerError':
            throw new Error(`Server error: ${msg}`);
    }
}

Detached Instances

Launch instances that persist after disconnection:


// Launch detached
const instance = await client.launchInstanceFromRegistry(
    'long-task',
    [],
    true  // detached
);
const instanceId = instance.instanceId;
 
// Disconnect
await client.close();
 
// Later, reconnect and attach
const client2 = new PieClient('ws://127.0.0.1:8080');
await client2.connect();
await client2.authenticate('username');
 
const attached = await client2.attachInstance(instanceId);
const { event, msg } = await attached.recv();

Browser Usage

The client works in browsers with WebSocket support:


<script type="module">
import { PieClient } from '@pie-project/client';
 
const client = new PieClient('ws://localhost:8080');
await client.connect();
// ...
</script>

Error Handling


try {
    await client.connect();
    await client.authenticate('username');
} catch (error) {
    if (error.message.includes('ECONNREFUSED')) {
        console.error('Server not running');
    } else {
        console.error('Connection error:', error);
    }
}