Host options

createHarnessHost has many options, and their names do not always tell you if you need them. Most apps need only one or two. A local app, like a coding agent on your own computer, needs none.

The host is the part of your server that runs the sessions. A session is one conversation with your agent. The host keeps the state of each session, runs its turns, and gives clients its events.

Start with no options#

On your own computer, with one user, create the host with no options:

import { createHarnessHost, defineHarness } from '@tanstack/ai-harness'
import { openaiText } from '@tanstack/ai-openai'

const assistant = defineHarness({
  name: 'acme/assistant',
  adapter: openaiText('gpt-6.1-sol'),
})

const host = createHarnessHost()

await using session = await host.open(assistant, { threadId: 'my-first-chat' })
const turn = await session.send('Hello!')
console.log(turn.text)

This host keeps everything in memory. When the process stops, the sessions are gone. At the start, the host writes one warning about this to its logger (the console by default). There is no login check, so every call acts for the one local user.

Find the options that you need#

Find your situation below. Add only the options of that situation.

Most servers need these two first:

• The sessions must stay after a restart. Add persistence. See Durable sessions.
• More than one person uses the app. Add access. Each call then needs the user that it acts for. See Access and tenants.

The other options are for some apps only:

• You run more than one server. Give every server the same persistence. If your agents use files on the disk of a server, add ownership. See Deploy a harness.
• Users bring their own API keys. Add credentials, so the keys stay after a restart. See Where the keys are stored.
• You want traces and metrics. Add observability. See Trace runs and report operations.
• You want the warnings in your own logger. Add logger, for example in a full-screen terminal UI. See Send the warnings to your own logger.

A server for many users usually starts like this:

import { createHarnessHost, membersOnly } from '@tanstack/ai-harness'
import { memoryPersistence } from '@tanstack/ai-persistence'

const host = createHarnessHost({
  // Use a store on your own database in production.
  persistence: memoryPersistence(),
  access: {
    // Your own login check. Return null when nobody is logged in.
    getUser: async ({ request }) => {
      const id = request.headers.get('x-user-id')
      return id ? { id } : null
    },
    rules: membersOnly(),
  },
})

Send the warnings to your own logger#

By default, the harness writes its warnings and errors to the console. In a full-screen terminal UI, these lines break the screen. On a server, they do not match the format of your other logs. Give the host your own logger. This one writes each line to a file:

import { appendFileSync } from 'node:fs'
import { inspect } from 'node:util'
import { createHarnessHost } from '@tanstack/ai-harness'

// Write each line to a file, so the terminal UI keeps its screen.
function toFile(level: string, message: string, meta?: Record<string, unknown>) {
  // An error in the meta prints with its stack.
  const details = meta ? ` ${inspect(meta)}` : ''
  appendFileSync('harness.log', `${new Date().toISOString()} ${level} ${message}${details}\n`)
}

const host = createHarnessHost({
  logger: {
    debug: (message, meta) => toFile('debug', message, meta),
    info: (message, meta) => toFile('info', message, meta),
    warn: (message, meta) => toFile('warn', message, meta),
    error: (message, meta) => toFile('error', message, meta),
  },
})

logger takes a Logger from @tanstack/ai. Its four methods are debug, info, warn, and error. Each method gets a message and an optional meta object. The harness puts an error in the meta as { error }. On Node, the default new ConsoleLogger() prints the meta with console.dir.

On a server, call your own logger in each method. This one uses pino:

import pino from 'pino'
import { createHarnessHost } from '@tanstack/ai-harness'

// pino prints the stack of an error only under its `errorKey`, `err` by default.
// The harness puts the error under `error`.
const log = pino({ errorKey: 'error' })

const host = createHarnessHost({
  logger: {
    debug: (message, meta) => log.debug(meta, message),
    info: (message, meta) => log.info(meta, message),
    warn: (message, meta) => log.warn(meta, message),
    error: (message, meta) => log.error(meta, message),
  },
})

The harness writes these to your logger:

• Every warning and error of the host and its sessions, also from createHarnessWorker and createHarnessHandler.
• The errors of the model calls of a session: the turn, ctx.model.chat, and the calls of child agents. These calls write no other debug output.
• The warnings of plugins, for example mcp(), codeMode(), and skills(). A plugin writes to your logger with ctx.logger. See Write warnings to the host logger.

If a method of your logger throws, or returns a promise that rejects, that line is lost. The harness goes on.

All options#

Each option is optional. Leave out an option to get its default.

Some words in this table:

• Log: the record of everything that happened in a session. The host reads it again after a restart.
• Snapshot: a saved copy of the state of a session, so the host does not read the full log to open it.
• Tenant: an organization in your app. With access, the sessions of one tenant stay apart from the sessions of other tenants.

What you have now#

You know which options your app needs. A local app runs with createHarnessHost(). A server adds persistence and access first, and more options only when it needs them.