# Instatic AI Agent Integration with Claude, OpenAI, and Ollama: A Complete Technical Guide

> Integrate Instatic AI agents with Claude, OpenAI, and Ollama using our provider-agnostic framework. Drive visual editor programmatically with this complete technical guide.

- Repository: [CoreBunch/Instatic](https://github.com/CoreBunch/Instatic)
- Tags: how-to-guide
- Published: 2026-08-02

---

**Instatic provides a built‑in, provider‑agnostic AI agent framework that lets you drive the visual editor programmatically using Claude, OpenAI, Ollama, or any HTTP‑compatible model through a unified driver architecture.**

The Instatic visual editor ships with a first‑class AI integration layer that connects external language models directly to the page mutation engine. Unlike platforms that rely on heavy SDKs, Instatic uses thin HTTP drivers located in `server/ai/drivers/` to communicate with AI providers via raw REST and SSE streams.

## Provider‑Agnostic Driver Architecture

All AI communication lives under **`server/ai/drivers/`**. Each driver implements a thin wrapper around the provider’s REST endpoint using raw HTTP/SSE, deliberately avoiding third‑party SDKs like `@anthropic-ai/sdk` or `@openai/agents`. This design keeps the bundle size minimal and makes it trivial to swap between cloud providers or self‑hosted inference servers such as Ollama.

The architecture treats every provider equally. Whether you are calling Claude’s Messages API, OpenAI’s Chat Completions, or a local Ollama instance, the driver returns a standardized operation list that the editor understands. Changing providers requires only updating the **`INSTATIC_AI_PROVIDER`** environment variable and supplying the matching endpoint URL and API key—no code changes necessary.

## Unified HTTP Client for AI Communication

Drivers and UI code share the same transport layer via **[`src/core/http/apiRequest.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/http/apiRequest.ts)**. This helper centralizes credential injection, request/response validation using TypeBox schemas, and error handling through a single `ApiError` class.

When an AI driver needs to fetch completions, it calls:

```typescript
import { apiRequest } from '@core/http';

const { operations } = await apiRequest('/ai/generate', {
  method: 'POST',
  json: { prompt },
  schema: PromptResponseSchema, // TypeBox schema for validation
});

```

This guarantees that AI traffic follows the same authentication, logging, and retry policies as the rest of the application.

## MCP Bridge for Editor Control

Instatic exposes the editor over a Model‑Context‑Protocol (MCP) server at **`/_instatic/mcp`**. The bridge defined in **[`server/ai/mcp/editorBridge.ts`](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/editorBridge.ts)** forwards AI‑generated operations to the same mutation engine that powers the canvas UI.

Because the bridge uses the internal mutation API, AI edits automatically respect validation rules, permission checks, and undo/redo history. An AI agent cannot bypass schema validation or edit locked components— it operates under the exact same constraints as a human user.

## Mutation Engine Integration

All edits—whether human‑driven or AI‑driven—flow through **[`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts)**. This single source of truth exposes functions like **`mutateActiveTree`** and **`applyTreeOperation`**, which the AI bridge invokes after parsing the model’s response.

When the AI returns a list of tree operations (add node, update prop, wrap component), the bridge dispatches them via:

```typescript
// Inside the MCP bridge or a UI component
mutateActiveTree((tree) => applyTreeOperation(tree, aiGeneratedOperation));

```

This ensures AI changes are fully reversible through the command history and trigger the same side effects (re‑rendering, validation, persistence) as manual edits.

## Implementing a Custom Ollama Driver

Adding support for a local Ollama server requires minimal code. Create a new file in [`server/ai/drivers/ollama.ts`](https://github.com/CoreBunch/Instatic/blob/main/server/ai/drivers/ollama.ts) that implements the generate function:

```typescript
import { apiRequest } from '@core/http';
import { PromptResponseSchema } from '../schemas';

export async function ollamaGenerate(prompt: string) {
  // Ollama exposes a simple POST /api/generate endpoint
  const { operations } = await apiRequest('http://localhost:11434/api/generate', {
    method: 'POST',
    json: { prompt },
    schema: PromptResponseSchema, // Reuse the same schema as OpenAI/Claude drivers
  });
  return operations;
}

```

Once registered in the driver registry, setting `INSTATIC_AI_PROVIDER=ollama` automatically routes all AI calls to your local instance.

## Security and Sandboxing

All AI driver code executes on the server side within the same **QuickJS‑WASM sandbox** used by user plugins. The driver does **not** receive filesystem or network access unless explicitly granted by the site owner via permission manifests. This preserves the security model described in the plugin system documentation, ensuring that even if a model returns malicious instructions, the execution environment remains constrained.

## Summary

- **Provider‑agnostic drivers** in `server/ai/drivers/` enable switching between Claude, OpenAI, and Ollama without code changes.
- **`apiRequest`** in `src/core/http/` unifies HTTP transport, validation, and error handling for all AI communication.
- The **MCP bridge** at [`server/ai/mcp/editorBridge.ts`](https://github.com/CoreBunch/Instatic/blob/main/server/ai/mcp/editorBridge.ts) relays AI operations to the editor with full validation and undo support.
- All mutations flow through **[`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts)**, ensuring AI edits respect the same rules as human actions.
- **QuickJS‑WASM sandboxing** keeps AI execution secure and isolated from the host system.

## Frequently Asked Questions

### How do I switch from OpenAI to Claude in Instatic?

Change the **`INSTATIC_AI_PROVIDER`** environment variable to your desired provider (e.g., `claude` or `anthropic`) and update the corresponding endpoint URL and API key in your environment configuration. Because the drivers share a common interface in `server/ai/drivers/`, no application code changes are required.

### Can I use a local Ollama instance instead of cloud APIs?

Yes. The provider‑agnostic architecture supports any HTTP‑compatible endpoint. Create a driver file in `server/ai/drivers/` that calls your local Ollama server at `http://localhost:11434/api/generate`, reuse the standard `PromptResponseSchema` for validation, and set `INSTATIC_AI_PROVIDER` to your custom driver name.

### Are AI‑generated edits undoable in the visual editor?

Yes. Because the MCP bridge dispatches AI operations through **`mutateActiveTree`** and **`applyTreeOperation`** defined in [`src/core/page-tree/mutations.ts`](https://github.com/CoreBunch/Instatic/blob/main/src/core/page-tree/mutations.ts), they enter the same command history as manual edits. Users can undo AI changes using the standard undo shortcut or history panel.

### Does Instatic require the official OpenAI or Anthropic SDKs?

No. The repository explicitly bans heavy SDKs like `@anthropic-ai/sdk` and `@openai/agents`. All drivers use the internal **`apiRequest`** helper from `src/core/http/` to communicate via raw REST/SSE, keeping dependencies minimal and giving you full control over the HTTP stack.