The Hive Manual
Everything you need to use the Pollinations CLI, the web app, and Pollina IDE. All tools are 100% client-side — your keys and data never leave your browser.
📦 Installation
Install the CLI globally via npm:
npm install -g @bluegaminggm/pollinations-cliVerify the install:
pollinations --helppollinations text "Summarise this file" -f ./notes.txt --streampollinations image "cyberpunk bee hive" --width 1024🌐 Web App Overview
The web app at pollinations-cli-web.vercel.app is a browser companion to the CLI. It exposes five main areas:
/baseMultimodal workspace — text, image, audio, video, batch generation
/chatMulti-session AI chat with model switching and history
/idePollina IDE — full in-browser agentic coding environment
/docsThis page — full reference documentation
/securityPrivacy policy and data flow transparency
/contactGitHub, Discord, npm and other links
🐝 Pollina IDE
Pollina IDE is an in-browser AI coding environment built on a multi-agent swarm architecture. It maintains a virtual filesystem in IndexedDB and uses the Pollinations API to run agents that read, write, and test code on your behalf.
Getting Started
- Navigate to /ide
- Accept the beta notice
- Sign in with GitHub (optional, required only for repo push) or continue anonymously
- Create a new project — choose a framework and name it
- Type a task in the chat and hit Enter
How the Agent Loop Works
Each message goes through a multi-turn ReAct loop capped at 20 iterations. The Coder agent streams its response, emits a single JSON tool call at the end of each turn, the system executes it, feeds the result back, and the loop continues until the agent writes a plain-text summary with no tool call.
Agent loop diagram
User message → Coder (streams) → tool call JSON detected
→ Tool executor → result injected as next user turn
→ Coder (silent) → next tool call or final summary
→ Critic reviews final output (if files were written)
🧠 Swarm Roles
The IDE swarm has four configurable roles. Each can be assigned any model from the Pollinations model catalogue via the Swarm button in the IDE toolbar.
Main agent. Streams responses, emits tool calls, writes all files. Default: qwen-coder.
Answers design questions via consult_architect tool. Default: deepseek.
Reviews code after the Coder finishes. Receives live web search results as ground truth if a search was run. Default: openai.
Search-grounded model used for web_search tool calls. Must support live search. Default: gemini-search. Results are cached in the memory bank.
The Artist is a fifth implicit agent — it runs in parallel with the Coder on web-framework projects and writes CSS/SCSS/SVG assets. It uses the Coder model and fires silently with no UI output.
🔧 Tool System
The Coder emits a single JSON tool call per response turn. The system validates it, runs a syntax check (Ghost Runtime), and executes it through the atomic transaction queue.
| Tool | What it does |
|---|---|
| read_file | Read any file from the virtual filesystem before modifying it |
| write_file | Create or overwrite a file — runs Ghost Runtime syntax check first |
| move_file | Rename or move a file atomically |
| delete_file | Remove a file from the virtual filesystem |
| list_files | List all files, optionally filtered by directory |
| shell_exec | Log a command to the terminal (virtual execution in browser) |
| generate_image | Generate an image via Pollinations and save to the filesystem |
| web_search | Dispatch a live web search to the Researcher model; results cached |
| consult_architect | Ask the Architect agent for design guidance |
Ghost Runtime
Before every write_file call on JS/TS/JSX/TSX files, the code is run through a lightweight static syntax checker using new Function(). This parses the code as a function body without executing it — catching syntax errors before they corrupt the project. The check takes under 1ms.
Tool Call Parsing
The parser runs four stages in order until one succeeds:
- Pre-processor: strips
<think>blocks, XML wrappers, markdown fences, and normalises inline JSON - Strict: brace-depth scanner +
JSON.parse - Repair: character-by-character walk that fixes literal newlines inside string values
- XML: handles
<function=tool_name>wrappers emitted by some models - Adapter: last resort — asks the model to reformat and re-emit just the JSON
Privacy & Storage
Everything is stored locally. Nothing reaches any server we control. See the full breakdown at /security.
- pollina_key — API key
- pollina_gh_user — GitHub avatar cache
- pollina_ide_v2 — All projects, files, history, config
- → gen.pollinations.ai (AI requests)
- → GitHub OAuth (optional sign-in only)
⚙️ Environment Variables
Set these in Vercel → Project → Settings → Environment Variables:
| Variable | Required | Purpose |
|---|---|---|
| NEXT_PUBLIC_GITHUB_CLIENT_ID | For IDE GitHub sign-in | OAuth App client ID — create at github.com/settings/apps |
| GITHUB_CLIENT_SECRET | For IDE GitHub sign-in | OAuth App secret — server-side only, never exposed to client |
🚀 Roadmap
Web-CLI Bridge
Cloud session sync, cache sharing, and remote deletion between CLI and web app.
Full GitHub Integration
Import any GitHub repo directly into Pollina IDE for autonomous architecture mapping and refactoring.
Visual Agent Orchestration
Drag-and-drop pipeline builder for constructing multi-agent swarm workflows without code.