CEREBRO

CEREBRO is a local-first, tool-using AI agent and multi-instance mission-control system. It combines a terminal REPL, a browser GUI, local or hosted model routing, workspace tools, persistent memory, autonomous planning, defensive safety controls, and an authenticated coordination mesh for multiple CEREBRO processes.

The project is intentionally self-contained. The core runtime and dashboard use the Python standard library; provider SDKs and media/science packages are optional enhancements.

Highlights

Interactive terminal agent with streaming responses and rich Markdown rendering.
Localhost mission-control GUI with chat sessions, live activity, Model Studio, Collaboration Hub, state panels, configuration editing, and self-improvement controls.
Multimodal GUI composer: click, paste, or drag images into a prompt and send them to a vision-capable model.
High-quality Natural/Neural Read Aloud plus continuous full-duplex Live Voice, with Windows host-audio fallback and pace control up to 2.00×.
Evidence links travel as structured turn metadata in a collapsed Sources control; they are never appended to the answer, spoken aloud, or injected into conversational memory.
Live web grounding: questions about DARPA programs, agency initiatives, solicitations, and other current public facts automatically retrieve open-web sources (preferring official .mil/.gov pages) and fail closed instead of inventing details from model memory. The GUI tags those turns with a Live web chip and populates Sources.
Validated conversational answers with topic-aware follow-ups, grammatical action routing, explicit count/format checks, truncation detection, unsupported-statistic rejection, and invisible corrective retries.
Strategic cognition: domain-aware adaptive reasoning contracts, multi-horizon deliberation, assumption lattices, reasoning-quality scoring, epistemic posture, decision memos, pressure-test / pre-mortem failure analysis, and unified strategic briefs (tools + process contracts).
Mission-control visual system 5.4: accent skins (Cyan, Aurora, Ember, Obsidian, Signal, Plasma), Deep Think / live-web / pressure-test composer chrome, Earth atlas load recovery, and smoother agent-message presentation.
CEREBRO Earth: interactive 3D social-intelligence globe with dense precip/cloud map, multi-horizon outlook (15–120m), action queue (one-click mission steps), ops board, impact matrix, nowcast HUD, decision package, alert ladder, risk corridors, auto-brief, and intelligence-pack export. Stage HUD uses non-overlapping docks. Staging rim is full-globe only for unlocated peers.
Google Earth handoff for opening a selected instance location in the full Google Earth web experience.
Local models through LM Studio, Ollama, or a CEREBRO-managed llama.cpp/GGUF server.
Hosted models through OpenAI-compatible APIs plus native Anthropic support.
Large, runtime-discovered tool registry for code, files, research, networking, media, planning, memory, assurance, and coordination.
Learned tool routing: recorded outcomes re-rank which tools are offered for each request, so selection sharpens with use.
Multi-instance discovery, authenticated peer links, capability advertisements, task delegation, shared memory, and coordination boards.
Checkpointed self-improvement with validation, rollback, regression guards, quality-diversity exploration, and failure memory.
Prompt-injection defenses, tool-risk classification, write authorization gates, secret redaction, loop governors, and audit logs.

Repository layout

Path	Purpose
`agent.py`	Main runtime, CLI/REPL, model transport, tools, memory, coordination, GUI bridge, and self-tests
`cerebro_gui.py`	Standalone stdlib HTTP/SSE dashboard and browser application
`cognitive_workspace.py`	Bounded global-workspace implementation used for evidence-aware reasoning
`codename_generator.py`	Deterministic, provenance-aware codename generation and reservation
`semantic_snapshot.py`	Semantic Python/source snapshots and related code intelligence
`.agent_config.json`	Primary local configuration
`tests/`	Pytest regression suite

Runtime state is stored beside the code in .agent_* files. See Persistence for the important records.

Requirements

Python 3.11 or newer is recommended.
A chat model endpoint:
- LM Studio on http://localhost:1234/v1,
- Ollama on http://localhost:11434/v1,
- CEREBRO-managed llama.cpp/GGUF, or
- a configured hosted provider.
A modern browser for the mission-control GUI.

The base agent and GUI do not require a web framework. Optional capabilities detect their packages at runtime and return an installation hint when unavailable.

Common optional packages include:

python -m pip install openai anthropic pillow pytest

Other features may use numpy, scipy, pandas, matplotlib, pypdf, cryptography, sounddevice, faster-whisper, opencv-python, yt-dlp, or imageio-ffmpeg. Install only what you need.

Quick start

1. Configure a model

The checked-in configuration defaults to LM Studio. Start LM Studio, load a chat model, and enable its local server. CEREBRO can discover the loaded model automatically.

For Ollama:

ollama serve
ollama pull llama3.1
python agent.py

Inside CEREBRO, ask it to use Ollama, or edit .agent_config.json:

{
  "provider": "ollama",
  "default_model": "llama3.1"
}

For a hosted provider, set its API-key environment variable and select the matching provider/model. For example:

$env:OPENAI_API_KEY = "..."
python agent.py

{
  "provider": "openai",
  "default_model": "gpt-4o"
}

Do not commit API keys. Prefer the provider's api_key_env setting.

2. Start the terminal agent

python agent.py

Run one prompt without entering the REPL:

python agent.py --run-prompt "Summarize this repository and identify its entrypoints"

3. Start the GUI

python agent.py --gui

The default address is http://127.0.0.1:8766/. CEREBRO opens it automatically unless --no-browser is supplied.

python agent.py --gui --gui-host 127.0.0.1 --gui-port 8766 --no-browser

The GUI binds to loopback by default and generates a new authentication token for every launch.

Mission-control GUI

The dashboard is a three-pane application:

Agent Chat — multiple named chat sessions, streaming replies, per-turn traces, transcript export, deep-think mode, and image attachments.
Activity — live local tool activity plus events tailed from sibling windows and run logs.
State panels — findings, tasks, memory, failures, strategy, cycle ledger, self-improvement, Collaboration Hub, CEREBRO Earth, tools, and Model Studio/configuration.

The server-to-browser channel uses Server-Sent Events. The browser automatically reconnects and replays missed buffered events. Client actions use token-authenticated JSON requests.

GUI session transcripts are restored into the model's recent-conversation context when the server restarts. Follow-up questions such as “What else should I know about this device?” therefore retain the subject shown in the preceding chat turn instead of being treated as unrelated standalone prompts.

When a factual answer has external grounding, the answer bubble remains clean. Validated links are stored separately on the turn and appear under a collapsed Sources control. Automatic speech, Live Voice, manual read-aloud, desktop notifications, and the model-visible conversation receive only the answer itself. Source metadata persists with the GUI transcript so grounded follow-ups can continue after a restart without hiding URLs inside prose.

The conversational control plane distinguishes an operational command from a conceptual mention, so questions about testing, servers, files, or networks do not accidentally enter the tool runtime. Elliptical continuations such as "what should we do instead?", "which option?", and "now state the main tradeoff" keep the established topic. Before a model answer reaches the transcript or voice queue, CEREBRO verifies minimum substance, bounded verbosity, requested item counts and formats, topic continuity, complete Markdown/code, and obvious unsupported percentages. Rejected drafts are corrected privately; after repeated failure, CEREBRO fails closed instead of speaking a stale or misleading candidate.

Every substantive turn also receives an adaptive reasoning contract. CEREBRO classifies the task as trivial, standard, complex, or high-risk and scales its tool-step budget accordingly. Harder work automatically requires explicit success criteria, alternative hypotheses or approaches, tool-backed evidence, proportionate validation, and a statement of residual uncertainty. High-risk work additionally requires an independent check of the highest-impact assumption, reversible execution, and authorization before consequential actions. Time-sensitive requests require current-source verification. Configure this with adaptive_reasoning_control and adaptive_reasoning_step_budgets.

Self-consistency and ensemble reasoning use contradiction-aware consensus rather than raw word overlap. Cerebro extracts decisive numeric, boolean, and explicit-choice conclusions; detects negation conflicts; uses complete-link clustering to prevent similarity chains from merging incompatible answers; and reports both agreement and the margin over the runner-up cluster. This avoids false confidence when multiple drafts use similar language but reach different conclusions.

Distributed work uses explainable intelligent placement. rank_peers_for_task scores accepting peers by semantic overlap with advertised roles, capability tags, and forged tools; learned reliability; actual live delegated workload; tool breadth; and network locality. Remote peers remain eligible but surface their approval cost. delegate_to_best_peer uses this ranking automatically, while run_distributed_team re-ranks every subtask with projected load so specialized peers receive matching work without creating hotspots. The cluster status reports live delegated workload, and the task ledger distinguishes in-flight, awaiting-remote-approval, and completed work.

Collaboration is failure-aware. Recent execution outcomes produce a Bayesian peer-health score, three consecutive failures open a routing circuit, and stale capability advertisements lose weight. delegate_task_with_failover tries ranked peers sequentially for read-only or explicitly idempotent work. It pauses instead of duplicating a task when remote approval is pending, and it suppresses retries for state-changing work unless the caller explicitly certifies idempotency.

run_distributed_workflow executes bounded multi-peer dependency graphs. It rejects missing dependencies, duplicate ids, self-dependencies, and cycles before dispatch; runs independent nodes in parallel waves; routes every node by capability and health; and blocks downstream work when prerequisites fail unless the workflow explicitly permits degraded continuation. Dependency outputs are bounded, labeled as untrusted data rather than instructions, and accompanied by SHA-256 lineage hashes. Every node reports its declared dependencies, execution state, routing attempts, and provenance.

Adaptive workspace layout

On desktop-width screens, drag the divider between Agent Chat and Activity to resize those panes, and drag the horizontal divider to resize the bottom state panel. The proportions are saved in browser local storage and restored on the next launch. The dividers also support arrow keys when focused; double-click a divider to reset its axis.

The Layout control can independently show or hide Agent Chat, Activity, and the bottom panels. Each pane also has a square focus control for a distraction-free full-workspace view. Balanced, Conversation, Operations, Earth command, and Minimal presets make common arrangements one click away. Smart reveal temporarily restores a relevant hidden pane when a turn starts, an error arrives, or the Earth view is selected. Visibility, proportions, and smart-layout preferences persist locally. Ctrl+Shift+1, Ctrl+Shift+2, and Ctrl+Shift+3 toggle the three panes, while Escape exits focus mode.

Read agent replies aloud

Select the speaker control in the header to automatically read each new CEREBRO reply. The Voice studio restores every voice exposed by the browser and makes Best available prefer Natural, Neural, Premium, and Enhanced voices. Windows' installed OneCore voices remain available as explicit choices and as a reliability fallback. Pace is adjustable from 0.75× to 2.00×; warmth, live preview, pause, and stop are also included, and long responses are divided into natural sentence-sized segments for reliable playback. Every completed response has its own speaker icon for manual playback, even when automatic reading is off; select the same icon again to stop it.

Browser speech is the normal high-quality output path. CEREBRO leaves a short settling window after speechSynthesis.cancel() before starting another utterance, preventing the cancel/restart race introduced by Live mode. A missing start event, synthesis error, or abnormally premature completion triggers Windows host-audio fallback. No ChatGPT or OpenAI voice API is used.

Control	Behavior
Header speaker	Toggles automatic playback for newly completed non-Live replies
Response speaker icon	Reads or stops that individual response without changing the automatic-playback preference
Preview voice	Speaks a fixed sample using the selected voice, pace, and warmth
Pace	Adjusts browser and fallback speech from 0.75× to 2.00× and persists locally
Warmth	Adjusts speech pitch and persists locally
Pause / Resume / Stop	Controls the current browser or Windows-fallback playback

The Voice list contains all voices reported by the browser plus installed Windows OneCore voices. Best available ranks Natural, Neural, Premium, Enhanced, Microsoft, and Google voices, then chooses the highest-quality candidate. Some browser Natural/Neural voices may be supplied online by the browser or operating-system vendor even though CEREBRO itself does not call a voice API.

Full-duplex Live Voice

Select Live in the header or composer, or press Ctrl+Shift+V, to start a continuous browser-native voice session. Live Voice keeps the microphone open while CEREBRO is speaking and automatically submits completed speech. A candidate reply is held until the response-quality gate accepts it, preventing a discarded retry or cut-off draft from being spoken; the accepted reply is then delivered to the existing sentence-segmented speech queue immediately.

Live Voice includes:

simultaneous listening and playback using the voice selected in the Voice studio;
barge-in, which stops the current audio and requests cancellation of the interrupted CEREBRO turn when new user speech is detected;
acoustic echo cancellation, noise suppression, automatic gain control, and an input-level meter;
transcript-based echo filtering to avoid submitting CEREBRO's own speaker output as a new user request;
an audible-start watchdog that retries the completed response once when a browser queues streamed speech but never begins playback;
automatic microphone recovery when browser recognition ends or briefly disconnects;
microphone mute without stopping CEREBRO playback; and
command-palette actions plus a persistent barge-in preference.

This mode uses SpeechRecognition, speechSynthesis, and getUserMedia supplied by the browser, with Windows host audio available when browser synthesis genuinely fails. It does not use the ChatGPT Voice or OpenAI Realtime API. Depending on the browser and operating system, speech recognition or a selected browser voice may itself be implemented by the browser vendor as an online service.

Image prompts

The GUI accepts up to four images per turn. Each image may be at most 8 MB.

Supported formats:

PNG
JPEG
GIF
WebP
BMP

Attach images in any of three ways:

select Image in the composer;
drag image files onto the composer; or
paste an image from the clipboard.

An attachment preview appears before sending and can be removed independently. Image-only turns are supported; CEREBRO uses “Describe the attached image or images” as the default prompt. After submission, the composer reports how many images the server accepted and delivered to the model request.

Uploads are validated twice:

the GUI server checks the filename extension, encoded request size, decoded size, and file signature;
the model transport re-confines every referenced path to .agent_gui_uploads before reading it.

The model transport converts attachments at the final provider boundary:

OpenAI and OpenAI-compatible providers receive image_url data blocks;
Anthropic receives native base64 image source blocks.

Use a vision-capable model. Text-only models may reject a turn containing an image. Examples in the default catalog include GPT-4o, GPT-4o mini, Gemini vision models, Llama 4 Maverick/Scout, and other provider-specific multimodal models.

Uploaded images remain in .agent_gui_uploads so transcripts can refer to stable workspace paths. Delete files from that directory when they are no longer needed.

CEREBRO Earth

The CEREBRO Earth tab contains an interactive orthographic globe rendered on an HTML canvas. It uses pinned D3 Geo/TopoJSON libraries and published Natural Earth-derived 110m world geometry bundled in web_assets/, so the map remains accurate and works without a CDN at runtime.

Drag to orbit.
Scroll or use the − / + controls to zoom exponentially from the strategic globe down to 512× local inspection. Drag sensitivity scales with zoom so city- and street-area navigation remains controllable; select the zoom readout to return to 1×.
Select an instance marker, horizon indicator, orbital signal, or sidebar card to smoothly center or inspect it.
Select Frame network to focus a mapped signal, or pause/resume the automatic orbit.
Select Open Google Earth to open the selected coordinates in Google Earth Web.
Enter latitude/longitude manually, or select Use device GPS, then Save location.

The tab is also a geographic social command surface. It shows the current CEREBRO instance, live connected peers, live same-workspace CEREBRO processes discovered from CMD, and previously authenticated remote operator profiles even when their transport route is offline. Callsign, operator identity, headline, availability, network scope, route count, trust tier, unread operator chat, and remote-compute policy are first-class signals; it never invents coordinates for remote machines.

Use the Social layer control to show or hide operator presence, then filter the horizon to All, Local, LAN, Remote, or Offline. Selecting a profile reveals an explicit consent matrix and provides direct handoffs to inert operator chat or the secure sharing workflow. Social visibility and chat do not authorize payload receipt: conversations, data, and task proposals still require recipient acceptance, while remote compute remains approval-gated unless that peer was explicitly preapproved. Known offline profiles remain visible in the staging ring so operators are discoverable without implying that they are reachable or authorized.

Mission Control 3.5 turns the Earth rail into three purpose-built workspaces: Network for operator presence and consent, Intelligence for prioritized incidents and evidence, and Layers & position for location, mission presets, camera/source intelligence, orbital analysis, and search. The compact primary toolbar keeps the globe unobstructed; Layers expands the full sensor stack only when needed, and the live DATA ribbon is dynamically placed beneath it so the two surfaces never overlap. Smart focus explains and selects the most actionable target in a deterministic order: unread operator traffic, the highest-severity and highest-confidence active incident, the best reachable collaboration route, then the local network frame.

Location resolution follows these rules:

The current instance reads .agent_user_location.json.
New peer handshakes advertise the peer's saved location.
Capability/status advertisements can also provide a location.
Same-machine loopback peers inherit the local device location when an older peer version does not advertise coordinates.
Long-running CMD instances publish a token-free heartbeat in .agent_instances and an authenticated loopback control endpoint. Mission Control automatically links them and shows them as green local-CMD signals.
A connected peer with no advertised location and a known remote profile that is currently offline remain unmistakably visible in the social staging ring and sidebar. Neither is assigned invented coordinates; once a live peer advertises a valid location, its signal moves onto the globe.

Mapped signals use bright pins and persistent labels on the visible hemisphere. Signals on the far hemisphere remain discoverable as clickable horizon indicators; selecting one rotates it into view. Co-located instances are clustered at one coordinate and receive a count badge.

Coordinates are self-advertised telemetry, not independently verified physical locations. Saving a location makes those coordinates available to authenticated connected CEREBRO peers. Do not save a precise location if you do not want it shared through the peer mesh.

The built-in globe is Google Earth-style visualization, not an embedded copy of Google Earth imagery and not a Google API client. The explicit handoff button opens the official Google Earth site.

Earth's live-data controls include a source-health ribbon for Starlink, civilian and defense ADS-B, AIS, documented Flock camera metadata, terrestrial weather, and NOAA space weather. Each source reports live, degraded, cached, or offline status; the aggregate data-quality score makes partial outages visible at a glance, and selecting a source badge retries it. Successful responses are stored as last-known-good snapshots in .agent_earth_feed_cache, so temporary outages and Windows/application network-policy denials do not blank the map after a restart. When live access is blocked, Earth uses the cached snapshot with a clear stale-data warning and never exposes raw socket errors in the interface.

Select Flock cameras or the Cameras mission preset to render a zoom-adaptive clustered layer of community-documented Flock Safety ALPR locations. The default source is the weekly OpenStreetMap planet index served by QLever, queried with the documented DeFlock tags surveillance:type=ALPR and a manufacturer value containing Flock. CEREBRO preserves an OpenStreetMap source link for every point, shows the documented total separately from the deterministic 25,000-point display sample, and provides agency/city/OSM-ID search plus observer-relative nearest-camera focus. Selecting a camera automatically enters 96× local inspection; at 8× and closer, clusters resolve into individual markers and any numeric or cardinal OSM direction/camera:direction value becomes an arrow pointing clockwise from true north. Use Inspect orientation or the global Camera zoom control to return to that view. The data is licensed under ODbL 1.0 with attribution to OpenStreetMap contributors. It is community mapping—not an authoritative or complete census—and individual records or orientations may be missing, stale, or inaccurate.

The orbital toolbar distinguishes CEREBRO's 21 modeled Relays from Live satellites. The live layer now loads automatically from the restart-cached CelesTrak Starlink GP catalog—currently more than ten thousand propagated records—while adaptive rendering displays thousands of current positions in a normal command viewport without turning the orbital shell into a solid mass. Sunlight state, true orbital paths, observer-horizon filtering, route simulation, coverage, conjunction screening, and satellite search continue to operate on the loaded catalog.

CEREBRO never calls Flock's private API, invents coordinates, or exposes imagery and plate reads. A trusted operator can override the public index by copying flock_cameras.example.geojson to .agent_flock_cameras.geojson, or by setting CEREBRO_FLOCK_CAMERA_GEOJSON to an explicit local path or HTTPS GeoJSON endpoint. Override feeds accept only GeoJSON Point features whose access/visibility is public or authorized; useful properties are label, agency, jurisdiction, camera_type, direction, status, precision (exact, intersection, block, or approximate), access, source_title, source_url, published_at, and verified_at. The sanitized metadata and its provenance are available at /api/earth/flock-cameras.

Select Weather to toggle a dedicated terrestrial forecast layer independently of Space wx. Earth samples 40 globally distributed Open-Meteo forecast cells and visualizes current condition, temperature, precipitation, cloud cover, humidity, wind, and gust severity directly on the globe. Projected wind vectors show near-term direction of travel, severe cells pulse and expose temperatures, and every cell can be hovered for evidence details or selected to center the camera. The layer refreshes on a ten-minute cadence, degrades safely to its restart-persistent cache, and is also available through the Weather mission preset and /api/earth/weather.

Wildfires, Quakes, and Natural are independent, persistent layers backed by NASA EONET, USGS, GDACS, and other normalized observations. Natural covers storms, floods, volcanoes, landslides, and other non-fire/non-earthquake hazards. Each toolbar control reports its live count, dedicated mission presets isolate a hazard family, and Crisis combines every natural hazard with terrestrial weather. Layer visibility changes the globe without removing evidence from the intelligence ranking.

Select Command view to devote the full workspace to Earth while retaining a one-click exit. Dense hazards are clustered into severity-colored glyphs with event counts, remain locked to the current camera frame during rotation, and can be selected directly to open the highest-priority incident represented by the glyph. Constellation rendering automatically adjusts its fidelity to the available canvas area while preserving selected and hovered satellites. The intelligence rail ranks incidents by severity, confidence, acknowledgement state, and exposure of CEREBRO peers or watch areas. It also provides critical/exposure/source-quality/forecast metrics, free-text incident filtering, and Focus top risk to rotate directly to the highest-priority mapped event.

The global header carries an always-available operational pulse derived from Earth's explainable risk posture, exposed assets, incident count, and source quality. Select it from any workspace panel to open Earth and focus the highest-priority mapped incident. The same action, all hazard toggles, Model Studio, Collaboration Hub, Agent Ensemble, and the Crisis preset are available through the Ctrl+K command palette. Mission Control 3.4 carries a persistent operational context ribbon for the active workspace, model route, mesh population, intelligence posture, queue, and execution state. Its global Next action deterministically prioritizes an unreachable model route, remote-compute approval, unread operator chat, critical Earth intelligence, active execution, or the prepared composer; the same recommendation is always first in the command palette. Every workspace has a concise purpose header and keyboard-accessible tab semantics; chat adds role-labelled messages, one-click copy controls, adaptive prompt sizing, live model/reasoning feedback, intelligent empty-state starters, and a Latest control when reading older turns. A quiet activity stream now explains what it monitors and temporarily gives chat more room until matching events arrive, while respecting manual pane sizing. The unified glass-depth surface remains responsive down to narrow screens with reduced-motion fallbacks.

Earth intelligence copilot

Earth command now includes a deterministic intelligence layer that remains useful when no model is configured. It normalizes USGS earthquakes, NASA EONET natural events, GDACS disasters, NOAA aviation hazards, optional viewport weather from Open-Meteo, live mobility feeds, and the existing space-weather/orbital layers into source-timestamped observations and explainable incidents.

The v2 cross-domain graph also normalizes authenticated CEREBRO instance telemetry and NOAA geomagnetic conditions. It correlates terrestrial hazards with nearby instances and treats severe geomagnetic storms as global peer, Starlink, GNSS, HF, and orbital-risk events.
A continuously recomputed operational risk posture combines severity, confidence, watch/peer exposure, and degraded-feed penalties into a transparent 0–100 score with nominal, guarded, elevated, high, and critical states. Per-feed freshness and source-quality scores remain visible.
Deterministic mobility forecasting projects aircraft along a 30-minute great-circle horizon and vessels along a two-hour horizon. It raises confidence-decayed approach incidents when a track is predicted to enter a watch area, while labeling every result as a forecast rather than an observation.
Resolved incidents remain in the lifecycle timeline for seven days, preserving acknowledgements, evidence changes, exposure transitions, resolution time, and automation audit context.
Every mobility forecast is filed in .agent_earth_predictions.json and later resolved against live tracks as a hit or miss. Earth reports pending/resolved counts, reliability bins, and a Brier score (lower is better), and supplies that calibration evidence to the copilot before it explains future risk.
Global, Hazards, Mobility, Space, and Local modes filter the incident queue without hiding source health or uncertainty.
Persistent watch areas define a named coordinate, radius, severity threshold, and optional category filter. Earth correlates every incident against them, renders their geodesic boundaries, and exposes closest-distance and entry/exit changes in the inspector.
Incident details expose evidence IDs, confidence, recommendations, acknowledgements, mute state, and automation history.
Critical authoritative or independently corroborated incidents may create one high-priority local follow-up task and desktop notification. A persisted one-hour cooldown prevents repeated alert storms; Earth never delegates to peers or runs general tools automatically.
Brief asks the configured model to explain only the normalized evidence. If the model is offline or fails, a deterministic brief is returned instead. Identical briefs are cached for five minutes against an incident-evidence fingerprint.
/api/earth/snapshot, /api/earth/incidents, /api/earth/incidents/action, /api/earth/watch-areas, /api/earth/predictions, and /api/earth/brief use the same launch token as the rest of the dashboard. Incident queries support severity, lifecycle, category, watch-area, and antimeridian-safe bounding-box filters. Existing Starlink, track, and space-weather APIs remain available.

Incident state, watch areas, and the automation audit are stored in .agent_earth_incidents.json, .agent_earth_watch_areas.json, and .agent_earth_automation.json. These files can contain approximate event or user-selected coordinates and should be treated as sensitive workspace data.

Deep-think mode

Deep-think mode runs multiple independent attempts at rising temperatures, groups them by agreement, and returns a majority result with confidence metadata. It is slower and best suited to difficult analytical prompts.

GUI configuration

The Model Studio is the primary runtime model control surface. It shows the active provider/model, discovers live model catalogs, switches exact API-provider models, configures OpenAI-compatible/OpenAI/Anthropic endpoints, activates Ollama, starts a local GGUF server, and stops a GGUF server owned by the process. API keys are never returned to the browser; an environment-variable name is preferred, and an inline key is stored only after it is explicitly entered and confirmed. Switching affects new turns without deleting existing chat sessions.

Its Agent Ensemble can route one objective to as many as six explicit specialists simultaneously - for example ChatGPT/OpenAI, Claude/Anthropic, Grok/xAI, Ollama, and a local GGUF model in one run. Each specialist has its own role and instructions. An optional chair model reconciles agreement, contradiction, minority concerns, and a concrete recommendation without changing the default chat model. The interface confirms the exact routes before making calls because configured API models may incur provider usage charges. The terminal equivalent is /ensemble provider:model,provider:model :: objective.

The CEREBRO Social Mesh discovers live local terminal and GUI instances plus authenticated LAN/remote peers. Authenticated presence is deliberately independent of payload consent: a remote instance can expose its callsign, operator name, headline, status message, availability, accent, last-seen state, locality, trust, and route health before accepting any conversation, data packet, task proposal, or compute request. Previously authenticated profiles remain visible as offline contacts. Operators can exchange bounded, redacted human chat immediately; these messages are inert and never enter either agent's prompt, memory, task queue, or compute path. The searchable topology and directory provide browser-local favorites, unread counts, thread history, and one-click chat or payload selection. Conversations, data, and task proposals remain separate typed envelopes that require explicit recipient acceptance. Accepted conversations open as a new agent chat, accepted data becomes locally visible without entering model context, and accepted task proposals enter the recipient's local task queue without executing automatically. Local and LAN compute routes remain low-friction. Remote compute retains an independent recipient-side approval queue: approve once, approve and remember for that exact peer, or deny. Remembered approval is scoped to that peer and expires; it is never a network-wide grant.

The relevant defaults are:

{
  "gui": {
    "enabled": false,
    "host": "127.0.0.1",
    "port": 8766,
    "auto_open_browser": true,
    "tail_external_files": true,
    "event_buffer": 500,
    "parallel_turns": 3
  }
}

parallel_turns allows different chat sessions to run concurrently. Turns inside one session remain strictly ordered.

Models and routing

CEREBRO separates provider configuration from role/model selection.

Each entry in llm_providers may specify:

Setting	Meaning
`type`	`openai`, `openai_compatible`, or `anthropic`
`base_url`	Provider API root
`model`	Provider default model
`api_key_env`	Environment variable containing the API key
`api_key`	Static key, mainly for trusted local endpoints
`auto_discover_model`	Whether to query the provider model list
`known_models`	Static fallback catalog with capability tags
`context_window`	Optional local model context size
`disable_model_thinking`	Disable provider-specific thinking output where supported

The default configuration includes templates for Anthropic, Google, Groq, LM Studio, local GGUF, Meta, Mistral, Ollama, OpenAI, OpenRouter, Together, and xAI.

Model router

The model router estimates input size, chooses a short/medium/long context route, reserves output space, and can compact prompts that exceed a route's budget.

Inspect it with:

python agent.py --model-router
python agent.py --validate-router
python agent.py --route-prompt "Analyze a large Python repository"

Role-specific providers and models are configured through role_providers and role_models.

Local GGUF models

CEREBRO can discover .gguf files, provision a supported llama.cpp server, start it on loopback, benchmark models, and expose the resulting OpenAI-compatible endpoint to the agent. Use the model REPL commands or the registered tools:

find_gguf_models
install_gguf_backend
load_gguf_model
benchmark_local_models
use_best_local_model
stop_gguf_model

Vision GGUF models may require a separate multimodal projector and server support. A text-only GGUF cannot consume GUI images merely because the GUI accepts them.

Agent loop

At a high level, a turn flows through:

user input
  -> deterministic fast paths and intent profile
  -> memory / mission / workspace context
  -> model and prompt-budget routing
  -> planner-executor or direct agent loop
  -> tool arbitration and execution
  -> validation, loop governance, and final answer
  -> conversation, run log, metrics, and memory updates

The model emits a small action protocol:

tool — invoke one registered tool;
batch — invoke a bounded group of actions;
final — return the answer.

Tool specifications are selected dynamically for each prompt instead of placing the entire registry into every model request. All registered tools remain callable by name.

Selection is both static and learned. Intent keywords, delegated-role preferences, and text relevance choose the initial candidates; a persistent tool policy then re-ranks them from recorded outcomes, so tools that have actually succeeded on similar requests are surfaced first and tools that keep failing there sink. See Learned tool routing.

Tool system

AgentTools builds the live tool registry. Use:

python agent.py --tools
python agent.py --tools --tool-schemas

Major capability groups include:

workspace reads, writes, patching, search, manifests, snapshots, and diffs;
Python AST, symbol, call-graph, hotspot, semantic, and dependency analysis;
testing, syntax validation, health reports, risk registers, and diagnostics;
web research, HTTP inspection, feeds, JSON APIs, and bounded crawling;
defensive network inspection, DNS, RDAP, TLS, ports, traffic metadata, and IDS baselines;
defensive threat intelligence, CVE/KEV lookup, hashes, signatures, and static x86 analysis;
structured planning, simulation, decision analysis, forecasts, evidence audits, and red teaming;
persistent memory, RAG, knowledge graphs, typed temporal world models, and conversation branches;
media display/playback, metadata, PDF extraction, Markdown rendering, and Manim generation;
timers, reminders, scheduling, calendar import/export, weather, time, and saved location;
model discovery, benchmarking, routing, comparison, portfolios, and local backend lifecycle;
peer discovery, task delegation, consensus, capability exchange, shared memory, and mission coordination;
checkpointed self-improvement, experiments, regression evaluation, failure memory, and quality-diversity search.

Tools are assigned risk levels. File writes, command execution, network changes, publishing, and other side effects pass through explicit policy and authorization checks.

Learned tool routing

Every executed tool call is recorded as evidence about that tool, bucketed by the classified intent of the request. The resulting policy in .agent_tool_policy.json scores each tool by a smoothed, confidence-weighted success rate and tracks which tools successfully follow which, so the agent learns both what works for a kind of request and what tends to come next.

The policy is advisory and bounded:

a tool with no recorded history scores exactly zero and changes no ordering, so behavior is unchanged until experience accumulates;
text relevance still dominates ranking; experience adjusts it rather than overriding it;
only successful calls create follow-on evidence;
the store is pruned to a fixed size, keeping the most-exercised evidence.

Two read-only tools expose it:

show_tool_policy — win rates and evidence-weighted scores per request type;
suggest_next_tools — what has historically followed a given tool.

Set tool_policy.enabled to false in .agent_config.json to disable learning and fall back to purely static selection. min_uses, max_injected, and relevance_weight tune how much evidence is required and how strongly it counts.

Multi-instance operation

CEREBRO can run multiple windows/processes in one workspace and connect them into a local mesh.

Long-running REPLs started directly in separate CMD prompts automatically publish fresh local-presence records and authenticated loopback endpoints. A running Mission Control instance discovers and synchronizes them without requiring the processes to have been launched from the GUI. Presence records older than 20 seconds are ignored, so terminated processes disappear from the network and Earth views.

Control server

Start the authenticated coordination server:

python agent.py --control-server --host 127.0.0.1 --port 8765

Inspect status:

python agent.py --control-server-status

The default control plane is loopback-only, token-authenticated, size-bounded, and restricted to allow-listed coordination messages. It is not a remote shell.

Allowed message families include status, ping, messages, context sync, memory/mission sharing, capability announcements, gossip state, model endpoint advertisements, and delegated tasks. Dangerous command names such as shell, exec, PowerShell, payload, persistence, keylogging, exfiltration, and upload are explicitly denied.

Peers and map of minds

LAN mesh (auto-discovery)

By default, lan_mesh makes private-LAN cooperation frictionless:

Binds the control server to 0.0.0.0 on port 8765 (with authorization for non-loopback bind).
Advertises presence over UDP beacons on port 8764 (private/link-local only).
Auto-connects when another CEREBRO beacon or light subnet scan finds a peer.
Shares the control token only inside private-LAN advertisements (or via shared CEREBRO_LAN_MESH_TOKEN / CEREBRO_CONTROL_TOKEN).

Allow Windows Firewall for UDP 8764 and TCP 8765 on Private networks. Both machines should run Mission Control or a REPL so presence + mesh start. Optional config:

{
  "lan_mesh": {
    "enabled": true,
    "auto_bind": true,
    "auto_connect": true,
    "control_port": 8765,
    "discovery_port": 8764
  }
}

Tools: start_lan_mesh, show_lan_mesh. The Collaborate tab shows mesh status and a Start / refresh LAN mesh control.

Relevant tools include:

cerebro_scan
cerebro_map
connect_peer
start_lan_mesh
show_lan_mesh
list_peers
cluster_status
request_peer_capabilities
delegate_task_to_peer
broadcast_task_to_peers
collect_peer_results
share_conversation_with_instances
share_response_with_instances

Non-loopback manual discovery, binding, or connection still requires explicit authorization. Delegated task execution is off by default and must be enabled on the receiving instance with allow_peer_task_delegation. Once enabled, loopback and private/link-local LAN peers collaborate directly. Delegation through a public or unresolvable endpoint is fail-closed: the receiving instance gets a visible request and must approve it with decide_remote_delegation before computation starts. A decision may be remembered for that exact peer (with a configurable expiry); list_remote_delegation_requests shows pending requests and remembered approvals, and decisions are written to the control-plane audit log.

Conversation, data, and task proposals are deliberately separate from task execution or compute delegation. In the GUI, Collaborate can share a full session, and each agent response has a Share button for one answer (with its prompt when available). Recipients accept shares from the collaboration inbox into a new chat session. In the terminal, /shares lists destinations and pending requests, /share <target> [title] sends recent dialogue, /share data <target> <text> sends a data packet, /share task <target> <goal> proposes a queued task, and /share accept <message-id> or /share dismiss <message-id> records the receiving operator's decision. Targets use local:<instance-id>, in:<connected-client-id>, or out:<host:port>. Acceptance never grants permission to offload computation; public or unresolved remote compute retains its independent notification and peer-scoped approval gate.

Shared window coordination

Sibling processes also use workspace files for visible messages, receipts, task claims, leases, dependency graphs, and coordination sessions. The channel records advisory work; it does not execute another process's shell commands.

Examples:

python agent.py --coordination-status
python agent.py --create-coordination-task "Review the GUI upload path" --priority high
python agent.py --claim-next-coordination-task
python agent.py --complete-coordination-task TASK_ID --result "reviewed"

Memory and cognition

CEREBRO has several complementary memory layers:

recent per-session conversation history;
durable memories with source, confidence, tags, sensitivity, and lifecycle state;
workspace RAG chunks with bounded indexing and retrieval;
a provenance-aware cognitive workspace for high-salience evidence;
failure memory keyed by normalized failure signatures;
a learned tool policy recording which tools succeed for which kinds of request;
a typed temporal world model for observations, claims, assumptions, predictions, decisions, desired states, contradictions, and retractions;
decision journals, forecasts, beliefs, trust records, and experiment results.

External content is not automatically elevated into trusted workspace evidence. Model-authored concepts are advisory and cannot grant themselves tool authority.

Self-improvement

Run a checkpointed improvement cycle:

python agent.py --self-improve "Improve GUI reliability" --cycles 2 --roles planner,coder,reviewer

The self-improvement system can:

create and restore checkpoints;
use separate planner, coder, reviewer, tester, and critic roles;
require behavioral source changes rather than comment-only churn;
run syntax checks, quick tests, full tests, evaluation harnesses, and quality gates;
compare multiple candidates per cycle;
roll back failed or regressive candidates;
record failure signatures and avoid repeating known mistakes;
maintain a quality-diversity archive of successful changes.

Self-improvement writes to the current codebase. Run it only in a workspace you can restore, review the resulting diff, and keep human approval gates for consequential changes.

Security model

GUI

Loopback binding by default.
DNS-rebinding defense through Host-header validation.
Random per-launch token required for every /api/* route and the SSE stream.
No-store responses, no-referrer policy, content-type sniffing protection, and a restrictive Content Security Policy.
Bounded request bodies and independent upload limits.
Image signature verification and upload-directory path confinement.
Read-only dashboard tool whitelist.
Config secrets are returned as <redacted> and preserved during round trips.

Agent and tools

Prompt-injection detection and untrusted-content boundaries.
Risk-classified tools and explicit write/command/network authorization.
Workspace path confinement for file operations.
Secret redaction in logs, messages, tasks, and diagnostics.
Bounded tool batches, per-turn caps, repeat detection, failure streak breakers, and loop governors.
Dry-run support for many high-impact operations.
Static-only malware and assembly analysis paths; bytes are never executed.

Peer mesh

Authenticated JSON-lines protocol.
Loopback-only default.
Bounded frame sizes and client counts.
Strict allowed command types plus a denied-command vocabulary.
Opt-in task delegation, shared missions, model endpoints, forged tools, and other sensitive federation features.
Peer trust, quarantine, rogue-risk scoring, and assurance records.

No policy layer eliminates risk. Inspect configuration, keep backups, use low-privilege environments, and review side effects before authorizing them.

Persistence

Important runtime files include:

File or directory	Data
`.agent_config.json`	Providers, models, router, GUI, safety, voice, scheduler, and feature settings
`.agent_gui_transcript.json`	GUI sessions and transcript entries
`.agent_gui_uploads/`	Images attached through the GUI
`.agent_user_location.json`	Saved latitude, longitude, label, and timezone
`.agent_runs.jsonl`	Run/event log
`.agent_window_activity.jsonl`	Shared sibling-window activity
`.agent_window_messages.jsonl`	Visible inter-window messages
`.agent_window_message_receipts.jsonl`	Display and acknowledgement receipts
`.agent_coordination_board.json`	Shared tasks, owners, leases, dependencies, and events
`.agent_coordination_sessions.json`	Multi-task coordination sessions
`.agent_control_server.jsonl`	Control-plane audit events
`.agent_control_server_token`	Local control-plane token
`.agent_failure_memory.json`	Normalized tool/model failure history
`.agent_tool_policy.json`	Learned tool-routing outcomes per request type
`.agent_blackboard.json`	Durable agent memory
`.agent_rag_index.json`	Workspace retrieval index
`.agent_cycle_ledger.json`	Self-improvement cycle outcomes
`.agent_improvement_backlog.json`	Candidate improvement work
`.agent_decision_journal.json`	Recorded decisions and supporting context
`.agent_checkpoints/`	Recoverable self-improvement snapshots

These files can contain prompts, paths, model outputs, findings, coordinates, or operational metadata. Treat the workspace as sensitive.

CLI reference

Frequently used commands:

Command	Purpose
`python agent.py`	Start the terminal REPL
`python agent.py --run-prompt "..."`	Run one prompt
`python agent.py --gui`	Start the mission-control GUI
`python agent.py --gui-status`	Show GUI singleton status in the current process context
`python agent.py --tools`	List registered tools
`python agent.py --model-router`	Inspect model routes
`python agent.py --validate-router`	Validate router configuration
`python agent.py --validate agent.py`	Validate Python syntax through CEREBRO
`python agent.py --health-report "goal"`	Generate a repository health report
`python agent.py --planning-brief "goal"`	Generate an implementation brief
`python agent.py --secret-scan .`	Scan workspace files for likely secrets
`python agent.py --workspace-snapshot . --hashes`	Build a bounded workspace manifest
`python agent.py --diagnostic-bundle agent.py`	Create a redacted diagnostics artifact
`python agent.py --quick-self-test`	Run the fast internal test set
`python agent.py --self-test`	Run the comprehensive internal test set
`python agent.py --self-test-profile`	Profile internal test durations

The CLI also exposes coordination, calendar, media, service connector, social draft/publish, model selection, control-server routing, and self-improvement commands. Run python agent.py --tools --tool-schemas for the authoritative live capability surface.

Testing and development

Compile the main modules:

python -m py_compile agent.py cerebro_gui.py cognitive_workspace.py codename_generator.py semantic_snapshot.py

Run the external regression suite:

python -m pip install pytest
python -m pytest -q

Run CEREBRO's internal suites:

python agent.py --quick-self-test
python agent.py --self-test

The GUI is embedded as HTML/CSS/JavaScript inside cerebro_gui.py. It intentionally has no frontend build step. When changing it:

run Python compilation;
validate the embedded JavaScript syntax;
start the GUI on an unused loopback port;
test chat, sessions, SSE reconnects, image selection/paste/drop, Earth rendering, responsive layout, and config redaction;
verify request limits and path-confinement tests.

The agent may be running in a dirty workspace. Preserve unrelated state files and user changes.

Troubleshooting

The GUI port is already in use

Choose another port:

python agent.py --gui --gui-port 8877

The backend indicator is offline

Start the configured local model server.
Confirm its base URL in .agent_config.json.
Check that a model is loaded.
Run python agent.py --model-router and inspect fallback settings.
For hosted models, confirm the expected API-key environment variable exists.

An uploaded image is rejected

Confirm it is PNG, JPEG, GIF, WebP, or BMP.
Keep each file under 8 MB.
Make sure the bytes match the filename extension; renaming a different file type is rejected.
Keep the JSON request under the server's encoded upload limit.

The model rejects an image turn

The active model is probably text-only or its local server lacks multimodal support. Select a vision-capable model and, for local GGUF setups, load the required vision projector when the server/model family needs one.

A peer appears but is not plotted

The peer is connected but has no advertised location. Save a location on that instance and reconnect so the new handshake includes it. Older same-machine peers inherit the local location automatically.

Browser GPS does not work

Geolocation requires browser permission. You can enter latitude and longitude manually. CEREBRO never requires GPS to run.

Read Aloud is silent

Refresh the GUI after upgrading so the latest voice controller is loaded.
Open Voice, leave Best available selected, and press Preview voice. This prefers the highest-ranked Natural/Neural browser voice.
If browser synthesis fails to start, CEREBRO automatically retries through the Windows default output device.
Confirm Windows has at least one speech voice installed under Settings → Time & language → Speech.
Try an explicit Windows local voice to test the host-audio path independently of browser speech.
Confirm the selected Windows default output device is not muted and is routed to the expected speakers or headphones.

Pytest is unavailable

python -m pip install pytest

You can still run python -m py_compile ... and python agent.py --quick-self-test with the standard runtime.

State files become too large

Most loaders and GUI panels are bounded, but durable logs and uploads can accumulate. Stop CEREBRO, archive the files you need, and remove obsolete logs/uploads carefully. Do not delete active coordination lock/state files while sibling instances are writing them.

Operational notes

CEREBRO is an experimental agent runtime, not a security boundary or a substitute for human review.
Network inspection and threat-intelligence tools are for authorized defensive use.
Social publishing, service API calls, external viewers, network binds, and other consequential actions retain explicit authorization gates.
World-model confidence, peer consensus, and validation certificates are decision aids, not guarantees of truth.
Google Earth is a Google product. CEREBRO is not affiliated with or endorsed by Google.

License

No license file is currently included in this repository. Until a license is added, standard copyright restrictions apply; do not assume permission to redistribute or sublicense the code.

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
__pycache__		__pycache__
web_assets		web_assets
README.md		README.md
agent.py		agent.py
cerebro_gui.py		cerebro_gui.py
codename_generator.py		codename_generator.py
cognitive_workspace.py		cognitive_workspace.py
earth_intelligence.py		earth_intelligence.py
flock_cameras.example.geojson		flock_cameras.example.geojson
lan_mesh.py		lan_mesh.py
semantic_snapshot.py		semantic_snapshot.py

Folders and files

Latest commit

History

Repository files navigation