AI & Intelligence

BlockWerk features a powerful AI assistant that helps you build, analyze, and troubleshoot your simulation diagrams. By default, the app uses a built-in proxy to provide basic AI functionality. However, for the best and most private experience, we recommend using your own AI provider ("Bring Your Own AI").

Why Bring Your Own AI (BYOAI)?

Complete Control: Effortlessly switch between direct AI interaction, Web AI (ChatGPT/Claude), and external MCP tools.
Privacy: When using your own key (BYOK) or a local model, your data is sent directly from your browser to the AI provider. No intermediate servers are involved.
Better Models: Use state-of-the-art models like Gemini 1.5 Pro, GPT-4o, or Claude 3.5 Sonnet directly.

The Bridge Selector: Choose your Workflow

At the top of the AI Assistant panel, you'll find the Bridge Selector. This determines how BlockWerk communicates with AI models:

1. Direct AI (Recommended)

The AI interacts directly with the simulation engine. This is the fastest way to build or modify diagrams.

Proxy Mode: Use our free Gemini proxy (no setup required).
BYOK Mode: Add your own API key for maximum speed and privacy.

2. Web AI (Blueprint Mode)

If you prefer using the web interface of ChatGPT, Claude.ai, or Gemini:

Click Copy Context for Web AI. All current diagram information is copied to your clipboard.
Paste this into your AI's chat and ask for a modification.
If it provides a JSON code block, copy it, paste it into the Web AI tab, and click Apply Blueprint.

3. AI Bridge (MCP)

Let an external AI drive this canvas — a web chat such as ChatGPT, Claude.ai or

Mistral, or a desktop tool such as Claude Desktop or Cursor.

Click Connect AI in the AI panel.
Choose where your AI runs: In a web chat or On my computer.
Click Copy link (web chat) or Copy config (desktop). That click also opens the

connection — there is no separate start button.

Paste it:

- Web chat: as a custom / remote MCP connector. On claude.ai that is

Settings → Connectors → Add custom connector; leave the OAuth fields blank.

- Desktop: into the config file the panel names, then restart the tool.

The panel shows "Waiting for your AI to connect…" and flips over as soon as the first

command arrives, listing the most recent calls.

Worth knowing:

The connection belongs to this tab. Close it and the link is gone; connect again in the

new tab (or use "Already set up? Open the connection").

The link carries a device token, which grants access to your canvas for as long as the tab

is open. Do not share it or put it in a screenshot. If it leaks, the ⟳ button next to Copy

revokes it and mints a new one.

The Session ID under Advanced is not a pairing code — it is this tab's encryption key.

Never paste it into a chat; pairing always goes through the link above.

Destructive actions (clearing the canvas, deleting a block) ask for your approval in the tab

first. The AI waits until you click.

Getting a Free Gemini API Key (Recommended)

Google's Gemini currently offers a generous free tier for developers via AI Studio, which is perfect for BlockWerk.

Visit the Google AI Studio API Key Page.
Sign in with your Google account.
Click Create API key.
Copy the generated key.
In BlockWerk, go to Settings > AI & Intelligence.
Select Gemini as your provider and paste your key.

Running AI Locally (Private & Free)

If you have a powerful computer, you can run AI models locally. This is 100% private and free.

Using Ollama

Download and install Ollama.
Run a model in your terminal: ollama run llama3 (or mistral, gemma).
In BlockWerk, select Ollama as your provider.
Ensure the Custom URL is set to http://localhost:11434.

Using LM Studio

Download and install LM Studio.
Download a model and start the Local Server.
Select LM Studio in BlockWerk.
Set the Custom URL to http://localhost:1234.

Other Free Providers (BYOAI)

In addition to Gemini, you can use other providers that offer a free tier for developers.

Groq (Super Fast & Llama 3)

Go to the Groq Cloud Console.
Create a free API key.
Select Groq in BlockWerk.
Enter your key and choose a Model ID (e.g., llama3-70b-8192).

OpenRouter (Universal Access)

OpenRouter provides a universal API for hundreds of AI models, including many free variants.

Go to OpenRouter.
Create an API key.
Select OpenRouter in BlockWerk and enter your API key.
Provide a Model ID (e.g., google/gemini-pro-1.5 or meta-llama/llama-3-8b-instruct:free).

Hugging Face (Serverless Inference)

Hugging Face offers thousands of free open-source models via their Serverless API.

Go to your Hugging Face Settings.
Create an Access Token (read).
Select Hugging Face in BlockWerk and paste your token.
Provide the Model ID of the model you wish to use (e.g., mistralai/Mistral-7B-v0.1).

Troubleshooting

CORS Errors: Some local configurations might block browser requests. For Ollama, you may need to set the environment variable OLLAMA_ORIGINS="*" before starting the service.
Invalid Key: Ensure there are no extra spaces when pasting your API key.
Model Not Found: If using local models, ensure the model is actually running and the server is active.