Use the client without React

Connect to Hyperflow from any JavaScript application without the React UI layer.

Use @hyperflow/client when you have your own UI framework or application state. The client exposes the same HTTP and WebSocket services used by the React packages, but it does not render UI or manage application state for you.

Before you start, obtain apiUrl and wsUrl for your Hyperflow runtime.

1. Install the client

pnpm add @hyperflow/client

For a Vite browser application, also install and register @hyperflow/vite. It prepares the SharedWorker used by the WebSocket transport.

pnpm add -D @hyperflow/vite

vite.config.ts

import { defineConfig } from 'vite'
import { hyperflowVitePlugin } from '@hyperflow/vite'

export default defineConfig({
  plugins: [hyperflowVitePlugin()],
})

2. Initialize the client

Initialize the singleton once, where your application starts. Then start the WebSocket connection.

src/hyperflow.ts

import { hyperflow } from '@hyperflow/client'

await hyperflow.init({
  apiUrl: 'https://runtime.example.com/api/v1',
  wsUrl: 'wss://runtime.example.com/api/v1/ws',
})

await hyperflow.ws.start()

Replace the example URLs with the values provided for your environment. For a same-origin setup, use { apiUrl: '/api/v1', wsUrl: '/api/v1/ws' }.

3. Read with HTTP and change state with WebSocket

Use httpSession for reads and operations that only exist over HTTP. Use wsSession for session mutations and live events.

// Read the current sessions over HTTP.
const sessionList = await hyperflow.httpSession.listSessions()

// Create a session over WebSocket, then receive updates for it.
const session = await hyperflow.wsSession.createSession()
hyperflow.wsSession.subscribeSession(session.id)

const unsubscribe = hyperflow.wsSession.onSessionEvent(session.id, (event) => {
  // Update your application's state from the ordered server event.
  console.log(event)
})

// Add a user message and ask the active agent to act.
await hyperflow.wsSession.createItem(session.id, {
  type: 'message',
  role: 'user',
  content: [{ type: 'text', text: 'Hello, Hyperflow.' }],
})
hyperflow.wsSession.startAct(session.id)

// Run these when the screen or application is no longer using the session.
unsubscribe()
hyperflow.wsSession.unsubscribeSession(session.id)
hyperflow.ws.stop()

Do not use HTTP mutations when an equivalent wsSession method exists. WebSocket methods preserve the ordering required for session updates and streamed agent output.

Browser, Node, and SSR

In browsers, tokens are stored in localStorage by default. For Node.js or server-side rendering, provide non-browser token storage explicitly:

import { hyperflow, memoryTokenStorage } from '@hyperflow/client'

await hyperflow.init({
  apiUrl: 'https://runtime.example.com/api/v1',
  wsUrl: 'wss://runtime.example.com/api/v1/ws',
  tokenStorage: memoryTokenStorage(),
})

Keep credentials and token refresh logic in your application boundary, not in shared presentation code.

Service selection

Need	Use
List, fetch, usage, tool approval, background-task operations	`hyperflow.httpSession`
Create, update, delete, session items, agent acts, subscriptions	`hyperflow.wsSession`
Login, logout, current user	`hyperflow.auth`
Runtime resources, models, configuration	`hyperflow.runtime`, `hyperflow.modelsCatalog`, `hyperflow.config`

Next steps

Read the REST API reference for HTTP endpoints.
Read the WebSocket API reference for session events and streaming.
Choose Build a custom skin when you want the React headless layer as well.