Quickstart

Requirements

• Node.js $\geq$ v22.17
• npm $\geq$ v10.9

Step-by-step

mkdir qvac-examples
cd qvac-examples
npm init -y && npm pkg set type=module

npm i @qvac/sdk

{
  "loggerLevel": "info",
  "loggerConsoleOutput": true,
  "httpDownloadConcurrency": 3,
  "httpConnectionTimeoutMs": 10000
}

// The SDK prints no logs by default. To see its client and server logs, run with
// QVAC_CONFIG_PATH pointing at a config that sets "loggerConsoleOutput": true
// (see the Quickstart docs).
import { loadModel, LLAMA_3_2_1B_INST_Q4_0, completion, unloadModel, } from "@qvac/sdk";
try {
    // Load a model into memory
    const modelId = await loadModel({
        modelSrc: LLAMA_3_2_1B_INST_Q4_0,
        onProgress: (p) => {
            const mb = (n) => (n / 1e6).toFixed(1);
            const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
            if (p.percentage >= 100)
                process.stderr.write("\n");
        },
    });
    // You can use the loaded model multiple times
    const history = [
        {
            role: "user",
            content: "Explain quantum computing in one sentence",
        },
    ];
    const result = completion({ modelId, history, stream: true });
    for await (const token of result.tokenStream) {
        process.stdout.write(token);
    }
    // Unload model to free up system resources
    await unloadModel({ modelId });
}
catch (error) {
    console.error("✖", error);
    process.exit(1);
}

QVAC_CONFIG_PATH=./qvac.config.json node quickstart.js

Running examples

Follow these instructions to run any example in this documentation:

• All examples are self-contained, runnable JavaScript scripts. Use the qvac-examples workspace created in this quickstart to store and run them as you explore this documentation.
• Run each example with the indicated compatible JavaScript environment. QVAC supports multiple environments (Node.js, Bare, and Expo). The examples are written in Node style and run on Node.js or Bun directly; to run them on Bare, see Running on Bare.
• More examples can be found in the SDK examples directory.
• Some examples need companion files — sample audio, an image, or a config — that aren't part of the embedded code. These can be found in the same examples directory.
• Some examples also provide a TypeScript version. If you want to run TS directly, install the required dev dependencies:

  npm i -D tsx typescript

Running on Bare

To run an example on Bare:

1. Provide a process global. Install bare-process and set it before using the SDK:

   import process from "bare-process";
   globalThis.process = process;

2. Register the plugins the example uses — Bare runs in-process and nothing auto-registers. See Runtime registration on Bare.

Here is the quickstart adapted for Bare:

// The Bare quickstart. Bare has no `process` global and does not spawn a worker,
// so two setup steps come first: install bare-process as the `process` global,
// then register the plugins this example uses via `plugins([...])`.

import bareProcess from "bare-process";
import { plugins, LLAMA_3_2_1B_INST_Q4_0 } from "@qvac/sdk";
import { llmPlugin } from "@qvac/sdk/llamacpp-completion/plugin";

(globalThis as unknown as { process: typeof bareProcess }).process = bareProcess;

const { loadModel, completion, unloadModel } = plugins([llmPlugin]);

// From here it is the same as the Node quickstart.
const modelId = await loadModel({ modelSrc: LLAMA_3_2_1B_INST_Q4_0 });

const history = [
  { role: "user", content: "Explain quantum computing in one sentence" },
];
const result = completion({ modelId, history, stream: true });
for await (const token of result.tokenStream) {
  process.stdout.write(token);
}

await unloadModel({ modelId, autoClose: true });

For running QVAC on Bare in production, we recommend @qvac/bare-sdk — a slim, Bare-only assembly where you select addons and register plugins explicitly. It also sets up the bare module shims that examples using fs and similar modules rely on.