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

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. 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:

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 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. 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:

// 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 that implements the generate function:

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 relays AI operations to the editor with full validation and undo support.
• All mutations flow through 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}