On-premises & self-hosted

There is no onPremises() adapter, and that is the point: on-premises is not a vendor, it is the absence of one. Every port on this site is already filled by something that runs on a machine you own — a model on your GPU, a corpus in your Postgres, sessions in a file, telemetry on a disk, secrets in your vault. This page is the map: service by service, what fills it, and what each one genuinely does not do.

Start local, stay local, pay only where you must

The workflow the whole library is built around reads, on this column, as a ladder. Each rung is one line of change, and you can stop at any of them.

Nothing about rungs 1–3 is a toy path. Rung 3 is a production deployment shape, and the honest labels below say exactly which parts of it have been seen working in one.

Service → adapter map

LLM — three ways to keep the model inside the perimeter

Ollama, for a machine with a model on it:

import { ollama } from 'agentfootprint/providers';

const provider = ollama('llama3.2');                                  // localhost:11434
const remote  = ollama('llama3.2', { baseUrl: 'http://gpu-01:11434' }); // or OLLAMA_HOST

It is a first-class adapter rather than a baseURL alias, because Ollama's own failures deserve their own words: nothing answering at that address, or a model that is not pulled on that machine, are two different things and both are named (OllamaUnavailableError). Deep dive: Ollama.

Anything OpenAI-compatible — vLLM, llama.cpp's server, TGI, LM Studio, or the corporate gateway that fronts all of them — is the baseURL option:

import { openai } from 'agentfootprint/providers';

const provider = openai({
  model: 'llama-3.3-70b',
  baseURL: 'https://llm-gateway.corp.internal/v1',
  apiKey: process.env.GATEWAY_KEY,     // many gateways want any non-empty string
});

A custom baseURL means the adapter treats the endpoint as OpenAI-COMPATIBLE rather than as OpenAI itself: capabilities real OpenAI declares are not assumed of a gateway that merely speaks its wire format. That distinction is why .outputSchema({ strategy: 'tool-forced' }) refuses at run start against a provider that has not declared it carries forced tool choice — an absence is a no, never a maybe.

Your own runtime is two methods. LLMProvider is { name, complete, stream? }, stream optional; the MockProvider source is the reference implementation. See Custom provider.

Stores — the corpus stays on your disk

The ranking axis and all seven stores are on Memory & stores; the on-premises picks are three:

import { sqliteVectorStore, pgVectorStore, staticVectorStore } from 'agentfootprint/memory';

const one   = sqliteVectorStore({ file: './corpus.db' });   // one machine, zero deps
const yours = pgVectorStore({ connectionString: process.env.PG_URL });
const built = staticVectorStore(bundle);                    // corpus as a build artifact

sqliteVectorStore runs on Node's built-in node:sqlite — nothing to install, nothing to operate, exact cosine over a resident matrix, and a documented ceiling of 50,000 chunks, which is a ceiling rather than a cliff because it is written down. pgVectorStore inherits the backups, failover, access control and migrations your Postgres already has, which for a regulated on-prem shop is usually the deciding argument. Both refuse a vector that meets an index built by a different embedder (EmbedderMismatchError) — the failure that otherwise presents as retrieval got worse.

For conversation memory, RedisStore if you already run one, InMemoryStore if the process is the boundary. For the artifact claim-check store, s3Artifacts and gcsArtifacts (see AWS / Google Cloud) work against an S3-compatible on-prem object store — MinIO and the like — through the client option: your own endpoint, your own path style, the same five verbs. See Artifacts.

Embeddings — a model on the machine, or no model at all

import { localEmbedder, staticEmbedder } from 'agentfootprint/providers';

const local  = localEmbedder();    // transformers.js — MiniLM-class, ~23 MB, on CPU
const static_ = staticEmbedder();  // model2vec — no neural forward pass at all

Both run offline after their first model fetch, which matters twice: an air-gapped host needs the model files staged with the build, and an embedder that never leaves the machine means the corpus never leaves it either — the usual reason a document set cannot be indexed by a hosted API. openaiEmbedder takes the same baseURL treatment when your gateway serves embeddings. See Embedders.

Hosting — the shape that is field-validated

import { standingAgent, nodeHost, sqliteSessions } from 'agentfootprint/hosting';

const handle = await standingAgent({
  agent,
  sessions: sqliteSessions({ file: '/var/lib/agent/sessions.db' }),
  host: nodeHost({ port: 8080 }),
});

Three ports, one composer: hydrate → resume-or-fresh → persist → reply. sqliteSessions holds conversations and paused runs in one table on node:sqlite, so a human-in-the-loop question survives a restart with no service to run beside the agent. httpHost({ wire }) is the door when the runtime dictates its own HTTP contract; nodeHost is a configuration of it.

This is the shape the label above refers to. Everything on Hosting & runtime applies unchanged — durability modes, the resume loop, the PendingAsk a person answers.

Where the parallelism comes from here

From this process, or from your own fleet. There is no platform underneath an on-premises box handing each session its own container, so serving more than one person at a time is a choice you make explicitly:

const handle = await standingAgent({
  agentFactory: () => buildAgent(),        // one agent per ACTIVE session
  sessions: sqliteSessions({ file: '/var/lib/agent/sessions.db' }),
  host: nodeHost({ port: 8080 }),
  maxActiveSessions: 100,
});

{ agent } serves every session from one instance and serializes globally — correct, and the right default for an internal tool with a handful of users. { agentFactory } runs sessions in parallel inside this one process, bounded and LRU-evicted, which is the shape a box with real concurrent users wants.

Scaling past one process is the third row of the concurrency table: N workers behind your load balancer, each with its own pool. That one needs a session store every worker can read, and sqliteSessions is explicitly one machine, one writer — so a multi-process deployment on-premises means Redis or Postgres behind the two-method SessionLifecycle port, which you write (no redisSessions ships; the sketch is on the hosting page).

Code execution — isolation, not a sandbox

import { localCodeRunner } from 'agentfootprint/providers';

const runner = localCodeRunner({ timeoutMs: 10_000 });

The name is localCodeRunner, never sandboxedCodeRunner, and the difference is the security posture rather than modesty. A child process gives you a separate heap, a kill-on-timeout ceiling, no inherited stdin, and an environment allowlist — your shell's secrets are not in the model's reach. It does not give you a filesystem jail, a network jail, or memory limits. So: a development loop, a trusted-input pipeline, a machine you would be relaxed about a shell script running on — and a real sandbox (gVisor, Firecracker, a container with no egress) behind the same CodeRunner port when the input is not trusted. The tool code does not change. In-process eval / node:vm is refused outright, because Node's own documentation says vm is not a security mechanism.

Why run code at all: summarize prose, compute data. A 40,000-row export belongs in a process, not in a context window. See Tools & gateways.

Telemetry — a collector if you run one, a file if you do not

otelObservability({ tracer }) takes your tracer, so any OTLP collector you already operate — Tempo, Jaeger, Grafana Alloy, a vendor-agnostic OTel Collector — receives the run as spans and span events under gen_ai.*. That is the first choice whenever a collector exists.

Plenty of deployments have none. fileObservability is the sink for those: NDJSON on a local disk, one JSON.stringify(event) per line, in the same envelope cloudwatchObservability puts in a log event — so a query written against one reads the other, and Filebeat / Fluent Bit / Vector / jq all read it already.

import { fileObservability } from 'agentfootprint/observe';

const telemetry = agent.enable.observability({
  strategy: fileObservability({
    path: '/var/log/agentfootprint/events.ndjson',
    maxBytes: 64 * 1024 * 1024,   // a safety ceiling — see below
    // eventTypes: ['agentfootprint.agent.turn_end', 'agentfootprint.error.fatal'],
  }),
});

process.on('SIGTERM', async () => { await agent.shutdown(); });   // flushes

FileObservabilityOptions is the whole surface — path (required), maxBytes, maxBufferEvents, maxBufferBytes, flushIntervalMs, eventTypes, onError — plus _fs, a FileSinkFs test seam that swaps the five filesystem calls this adapter makes, which is how the rotation policy is asserted without a real disk.

Four things it is honest about:

• Buffered, not synchronous. exportEvent serializes and returns; batches are appended on a size trigger, a timer, and flush(). A hard kill loses at most the buffer — the price of keeping telemetry out of agent-loop latency. agent.shutdown() flushes, as do the handle and a closing standingAgent.
• Rotation is ONE generation. With maxBytes set, a batch that would cross the ceiling renames the file to <path>.1, replacing any previous .1, and starts fresh. No .2, no compression, no schedule, no cross-process coordination. It exists so an unattended agent cannot fill a disk, and for nothing else — retention is a log-management daemon's job, and omitting maxBytes (the default) means this adapter never renames anything, which is the right choice when logrotate already owns the file.
• Nothing is bounded or redacted on the way out. A payload that must not be on that disk must not reach the strategy: narrow it with eventTypes (it becomes the strategy's relevantEventTypes, so the dispatcher does not even forward the rest), with tier / sampleRate, or with a footprintjs RedactionPolicy upstream. For a record bounded by construction, auditExport({ payloadMode: 'bounded' }) is the adapter that does that job.
• An unwritable path is refused at construction, naming the path — not at the first event, hours later, into nobody's console. Write failures after that reach onError (a rate-limited console.error by default) and the batch is dropped rather than requeued, so a disk that has been full for an hour cannot grow the buffer without bound.

Compose them when you want both:

import { composeObservability, otelObservability, fileObservability } from 'agentfootprint/observe';

agent.enable.observability({
  strategy: composeObservability([
    otelObservability({ tracer }),
    fileObservability({ path: '/var/log/agentfootprint/events.ndjson' }),
  ]),
});

For a tamper-evident record rather than a dashboard, auditExport() hash-chains every event and verifyAuditBundle names the exact record that broke. Full port detail: Observability sinks.

Who the run was for (9.11.0)

run({ identity }) puts the caller's principal and tenant on every event of the run (EventMeta.principal / EventMeta.tenant), which is what turns the stream into a who → what → when audit record.

await agent.run(message, {
  sessionId,
  identity: { tenant: 'acme', principal: 'alice@acme.test', conversationId },
});

This is column-independent — the same field, the same rule, the same code path on AWS and on your own machines. The only difference between the columns is which sink is reading it, and the envelope-serializing sinks (agentcoreObservability, cloudwatchObservability, fileObservability, auditExport) all carry it without knowing it exists. otelObservability places it deliberately as two agentfootprint.* span attributes (principal.id and tenant.id) on the run span; xrayObservability does not map it. Stamped only from an identity a caller NAMED — never from a sessionId, never invented. Detail: Observability sinks.

Credentials — your vault, read over its own HTTP API

staticTokens is the dev provider and is genuinely enough for a small fixed set of service tokens supplied by your orchestrator. When the secrets live in a vault, vaultCredentials reads them — no SDK, one GET per resolution through the runtime's own fetch, against HashiCorp Vault or anything Vault-API-compatible (OpenBao, and the Vault-API modes of several managed stores).

import { vaultCredentials } from 'agentfootprint/security';

const credentials = vaultCredentials({
  address: 'https://vault.internal:8200',   // https, or say `allowHttp` out loud
  mount: 'secret',                          // the KV v2 mount, default 'secret'
  paths: { github: 'ci/github', warehouse: 'ci/postgres' },
  // token: …  ← or the VAULT_TOKEN environment variable
});

Agent.create({ provider, model, credentials }).build();

The tool code does not change from the staticTokens version — same port, same ctx.credential!.toHeaders(). VaultCredentialsOptions carries address, token, auth, mount, namespace, the path mapping (paths or resolve), toCredential, apiKeyHeader, timeoutMs, allowHttp, id — and _fetch, the test seam that stands in for the network.

V1 is deliberately one shape, and every other shape is refused by name.

Those refusals are field gates rather than opinions. An auth method nobody has exercised against a real cluster would be a guess wearing an adapter's clothes, so each refusal names what it would take — tell us your auth shape is a field report, not an issue title.

A secret's fields become a credential by the first rule that matches, so a secret written the ordinary way needs no configuration:

toCredential(secret, service) is the seam for a shop whose field names are its own; returning undefined falls back to the table.

Everything else — an internal IdP, a Kubernetes secret projected into the pod, a config server — is one getCredential method behind the same port. See Identity & credentials.

Tools — a local process, or an internal server

import { mcpClient } from 'agentfootprint/providers';

const local    = mcpClient({ transport: { command: 'python', args: ['./tools/server.py'] } });
const internal = mcpClient({ transport: { url: 'https://tools.corp.internal/mcp' } });

Stdio for a tool server that runs beside the agent (nothing on the network at all); Streamable HTTP for one your platform team operates. McpHttpTransport accepts your own fetch, which is how a request that must be signed (mTLS, an internal HMAC scheme, a proxy that wants its own header) is served — a signature is computed from the request, so it cannot be decided at connect time. Serving the other direction, mcpServe exposes your agent as an MCP tool to the rest of the estate. See Tools & gateways and MCP client.

What is NOT here

Honest gaps, so nobody discovers them at integration time:

• No Kubernetes-native anything. No operator, no CRD, no service-account auth. The library is a Node dependency; the pod, the probe and the secret mount are yours.
• No secret-manager adapter besides Vault, and Vault only in its V1 shape above. Everything else is the CredentialProvider port — one method.
• No permission gating of the memory pipeline. PermissionRequest carries memory_read / memory_write, and since 9.11.0 they are enforced for a TOOL that declares them — but no memory stage builds a permission request. Memory is isolated by MemoryIdentity scoping, which is a different mechanism.
• No metrics exporter. ObservabilityCapabilities has a metrics flag and no shipped strategy sets it; counters come from the event stream, or from your OTel pipeline downstream of otelObservability.
• No log-retention policy. fileObservability rotates one generation as a disk-safety ceiling. Retention, compression and shipping belong to the daemon you already run.
• No air-gapped model distribution. localEmbedder and staticEmbedder fetch their model files once; staging them into an air-gapped image is your build's job.

Status

Next

• Infrastructure — ports & adapters — the ports, the decision table, the translation boundary
• Ollama — the local-model provider in full
• Hosting & runtime — the standing agent and the resume loop
• Observability sinks — the port fileObservability implements
• Identity & credentials — the port vaultCredentials implements
• AWS & Bedrock AgentCore — one cloud column, filled the same way
• Google Cloud & Gemini — the other one: gemini() where this page uses ollama(), and the same ports everywhere else