dev.club — where best developers and top companies connect.

dev.club — where best developers and top companies connect.Invite only

Request invite

Ollama JavaScript Library

The Ollama JavaScript library provides the easiest way to integrate your JavaScript project with Ollama.

Getting Started

npm i ollama

Usage

import ollama from 'ollama'

const response = await ollama.chat({
  model: 'llama3.1',
  messages: [{ role: 'user', content: 'Why is the sky blue?' }],
})
console.log(response.message.content)

Browser Usage

To use the library without node, import the browser module.

import ollama from 'ollama/browser'

Streaming responses

Response streaming can be enabled by setting stream: true, modifying function calls to return an AsyncGenerator where each part is an object in the stream.

import ollama from 'ollama'

const message = { role: 'user', content: 'Why is the sky blue?' }
const response = await ollama.chat({
  model: 'llama3.1',
  messages: [message],
  stream: true,
})
for await (const part of response) {
  process.stdout.write(part.message.content)
}

Cloud Models

Run larger models by offloading to Ollama’s cloud while keeping your local workflow.

You can see models currently available on Ollama's cloud here.

Run via local Ollama

  1. Sign in (one-time):
ollama signin
  1. Pull a cloud model:
ollama pull gpt-oss:120b-cloud
  1. Use as usual (offloads automatically):
import { Ollama } from 'ollama'

const ollama = new Ollama()
const response = await ollama.chat({
  model: 'gpt-oss:120b-cloud',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  stream: true,
})
for await (const part of response) {
  process.stdout.write(part.message.content)
}

Cloud API (ollama.com)

Access cloud models directly by pointing the client at https://ollama.com.

  1. Create an API key, then set the OLLAMA_API_KEY environment variable:
export OLLAMA_API_KEY=your_api_key
  1. Generate a response via the cloud API:
import { Ollama } from 'ollama'

const ollama = new Ollama({
  host: 'https://ollama.com',
  headers: { Authorization: 'Bearer ' + process.env.OLLAMA_API_KEY },
})

const response = await ollama.chat({
  model: 'gpt-oss:120b',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  stream: true,
})

for await (const part of response) {
  process.stdout.write(part.message.content)
}

API

The Ollama JavaScript library's API is designed around the Ollama REST API

chat

ollama.chat(request)

generate

ollama.generate(request)

pull

ollama.pull(request)

push

ollama.push(request)

create

ollama.create(request)

Note: The files parameter is not currently supported in ollama-js.

delete

ollama.delete(request)

copy

ollama.copy(request)

list

ollama.list()

show

ollama.show(request)

embed

ollama.embed(request)

ollama.webSearch(request)

web fetch

ollama.webFetch(request)

ps

ollama.ps()

version

ollama.version()

abort

ollama.abort()

This method will abort all streamed generations currently running with the client instance. If there is a need to manage streams with timeouts, it is recommended to have one Ollama client per stream.

All asynchronous threads listening to streams (typically the for await (const part of response)) will throw an AbortError exception. See examples/abort/abort-all-requests.ts for an example.

systemone

import ollama from 'ollama'

const response = await ollama.systemone({
  model: 'nimble',
  state: 'Our checkout has returned 500 errors since 9am.',
  questions: {
    team: {
      type: 'choice',
      instructions: 'Which team should handle this ticket?',
      criteria: { billing: 'Payments and refunds', technical: 'Software errors' },
    },
  },
})
console.log(response.answers.team)

System One uses POST /v1/systemone and returns one JSON response; streaming is not supported. It runs locally with decision models such as nimble (Ollama v0.35.0 or later) or clef (v0.35.1 or later), and in the cloud with clef:cloud (through Ollama v0.40.5 or later, or directly against ollama.com).

Clef also reads images (v0.40.0 or later locally): pass images as Uint8Arrays, base64 strings, or (in Node) file paths, shared by all questions. Cloud requests accept up to 4 PNG, JPEG, or WebP images (each at most 4 MiB and 16 megapixels, 8 MiB total).

state and question instructions accept text, JSON objects, or arrays. Questions are evaluated in their supplied order:

In the cloud, question ids may only contain ASCII letters, digits, _, ., and -, up to 100 characters, and a request may ask up to 64 questions.

Responses contain model, answers, and usage.input_tokens / usage.output_tokens. Confidence measures probability concentration, not calibrated correctness. Token usage comes from the server; output tokens are not necessarily zero. Optional keep_alive accepts seconds or a duration string. Requests use the client's existing host, headers, and HTTP error handling. The server validates its body and model context limits without truncating input.

Available on the default client and new Ollama() from both ollama and ollama/browser. Both entry points export SystemOneRequest, SystemOneResponse, and the question/answer types. Browser requests follow the server's normal CORS rules. See the combined question example.

Custom client

A custom client can be created with the following fields:

import { Ollama } from 'ollama'

const ollama = new Ollama({ host: 'http://127.0.0.1:11434' })
const response = await ollama.chat({
  model: 'llama3.1',
  messages: [{ role: 'user', content: 'Why is the sky blue?' }],
})

Custom Headers

You can set custom headers that will be included with every request:

import { Ollama } from 'ollama'

const ollama = new Ollama({
  host: 'http://127.0.0.1:11434',
  headers: {
    Authorization: 'Bearer <api key>',
    'X-Custom-Header': 'custom-value',
    'User-Agent': 'MyApp/1.0',
  },
})

Building

To build the project files run:

npm run build

Join libs.tech

...and unlock some superpowers

GitHub

We won't share your data with anyone else.