This guide covers building apps that run outside FlowScale using the HTTP transport. You can use any language or framework — Node.js scripts, Express servers, Next.js apps, Python backends calling a Node wrapper, anything that can make HTTP requests.

Prerequisite: A running FlowScale AIOS instance. Default local address: http://localhost:14173.

Installation

npm install @flowscale/sdk
# or
pnpm add @flowscale/sdk

Requires Node.js 18+ (uses the native fetch API).

Authentication

Every request requires a session. Call login() once to get a token, then pass it to createClient(). Tokens are valid for 7 days.

import { login, createClient } from '@flowscale/sdk'

const token = await login({
  baseUrl: '<http://localhost:14173>',
  username: 'admin',
  password: 'your-password',
})

const client = createClient({
  baseUrl: '<http://localhost:14173>',
  sessionToken: token,
})

login() reads the session token from the Set-Cookie response header. This works in Node.js (fetch exposes Set-Cookie). In a browser context, the browser handles the cookie automatically and you do not need to call login() — just make requests with credentials: 'include' against http://localhost:14173 directly.

Persisting the token

import { writeFileSync, readFileSync, existsSync } from 'fs'

const TOKEN_FILE = '.flowscale-token'

async function getToken(): Promise<string> {
  if (existsSync(TOKEN_FILE)) {
    return readFileSync(TOKEN_FILE, 'utf-8').trim()
  }
  const token = await login({
    baseUrl: '<http://localhost:14173>',
    username: 'admin',
    password: process.env.FS_PASSWORD!,
  })
  writeFileSync(TOKEN_FILE, token)
  return token
}

Creating a client

const client = createClient({
  baseUrl: '<http://localhost:14173>',  // required
  sessionToken: token,                 // required

  // Optional:
  timeout: 300_000,    // ms to wait for a tool to finish (default: 5 minutes)
  pollInterval: 2_000, // ms between status polls for API-engine tools (default: 2s)
})

Listing tools

client.tools.list() returns all tools with status = 'production'. Each row is the raw DB record — the key field for running tools is id, and schemaJson (a JSON string) describes the inputs.

const tools = await client.tools.list()

for (const tool of tools) {
  console.log(tool.id, tool.name, tool.description)
}