Astromesh Cortex

Astromesh Cortex is a native desktop IDE and control plane for designing, testing, and deploying AI agents. Built on Electron, it gives you a full-screen “Mission Control” surface: a schema-aware YAML editor, a drag-and-drop visual builder, an interactive agent console, and one-click lifecycle management across three runtime targets — a local Python runtime, GCP Cloud Run (via Orbit), and the Nexus Kubernetes cloud.

Cortex is not a web SPA, not a backend service, and not a monitoring-only dashboard. It is a standalone desktop application that owns the full author → test → deploy → operate loop from a single window.

Cortex vs Forge

Both Cortex and Forge let you build agents visually, but they serve different needs and coexist within the Astromesh ecosystem.

	Astromesh Forge	Astromesh Cortex
Form factor	Web SPA embedded in an Astromesh node at `/forge`	Standalone desktop app (Electron)
Backend	None — pure client, runs in the browser	Native main process with system access
Scope	Quick in-node visual building	Full IDE + multi-runtime ops console
Runtime lifecycle	—	Installs & manages a local Python runtime
Cloud provisioning	—	GCP via Orbit, Nexus cloud connection
Use it for	Fast, lightweight edits inside a running node	Designing, testing, and deploying across environments

Architecture

Cortex is a standard Electron application: a React renderer talks to the main process over an IPC bridge, and the main process hosts the services that drive each runtime target.

flowchart TB
  subgraph cortex["Cortex (Electron)"]
    renderer["`**Renderer (React)**
    Editor · Console · Deploy`"]
    main["Main Process (IPC Bridge)"]
    services["`**Services**
    LocalRuntime · Orbit (GCP) · Nexus (Cloud)`"]
    renderer --- main
    main --- services
  end
  services --> local["Local Runtime (:8000)"]
  services --> nexus["Nexus (K8s Cloud) (:8080)"]
  services --> gcp["GCP Cloud Run (Orbit)"]

Component breakdown

Renderer (React) — The UI layer: the Monaco-based agent editor, the visual builder canvas, the agent console and trace timeline, and the deploy controls. Pure presentation and interaction; it never touches the OS directly.
Main Process (IPC Bridge) — The Electron main process. It mediates every privileged operation — file system access, process spawning, network calls — between the renderer and the services over a typed IPC bridge.
Services — The control-plane logic. LocalRuntime installs and supervises a local Python runtime; Orbit provisions and manages GCP Cloud Run deployments; Nexus authenticates with and operates the Kubernetes cloud.

What’s new

v0.17.0 — per-model usage breakdown

Agent run results now show a per-model consumption table (provider / model / role / calls / tokens in-out / cost), collapsed beneath the run’s total token count. It reads usage.by_model from astromesh core v0.36.0+; older runtimes simply omit the field without breaking the contract.

v0.16.0 — operator Admin panel

A read-only view of the hub’s current tariffs and plans, authenticated with an operator token stored per connection through safeStorage. Distinct from the tenant dual-auth, and hidden behind an empty state until a token is set.

v0.15.0 — the “Uso” observability panel

A three-level view over the hub’s observability endpoints: tenant overview (month totals with a month selector, all-time totals, and a per-agent ranking with soft-deleted agents flagged), per-agent drill-down (metrics plus recent invocations), and invocation detail (per-model breakdown plus sub-invocations). It replaces the earlier Metrics / Logs / Cost stubs.

v0.14.0 — live streaming, cancellation, persistent transcripts

The Nexus run panel streams a run over the hub’s WebSocket route, showing tool-call activity live, with a Stop button that cancels the run in flight (the hub records it cancelled and charges nothing). Transcripts persist per tenant and reload on tenant activation. It falls back to the synchronous run when the hub lacks the stream route.

v0.13.0 — Nexus run panel and version comparison

The Nexus shell runs agents against the hub directly, keeping an in-memory transcript per agent and session and rendering each result’s usage breakdown. The versions drawer gained a Compare mode: pick two versions and read a side-by-side Monaco diff of their specs, each side labelled with its number and checksum.

Earlier in the same line: a versions drawer in the agent editor (history with per-version view and revert), agent-version client methods, and support for type: client tools from astromesh core v0.35.0.

Tech Stack

Layer	Technology
Desktop shell	Electron 41
UI	React 19 + Tailwind CSS 4
Editor	Monaco Editor + monaco-yaml
Visual builder	@xyflow/react
State	Zustand
Build	electron-vite + Vite 8
Tests	Vitest

Key Capabilities

Workspace-centric projects — A workspace is just a folder with a .cortex/workspace.json you commit to git; secrets stay in a gitignored .cortex/local.json.
Dual-shell modes — A Runtime mode for local development and a Nexus mode for cloud operations, toggled with Ctrl+M.
Schema-aware YAML editor — Monaco with validation and autocomplete against the Astromesh agent schema.
Visual agent builder — A drag-and-drop @xyflow canvas with bidirectional YAML sync and inspectors for model, tools, memory, guardrails, permissions, and orchestration.
Agent console & traces — An interactive chat playground to test running agents, plus a hierarchical trace timeline with per-span latency, inputs, and outputs.
Three runtime targets — Local Python runtime (:8000), GCP Cloud Run via Orbit, and the Nexus Kubernetes cloud (:8080).
Channels & dev tunnel — A WhatsApp setup wizard, a live Channel Activity stream, and ngrok/cloudflared tunnel management for webhook testing.

What’s Next

Quick Start — Install Cortex and ship your first agent to a local runtime
Runtimes — Local, GCP (Orbit), and Nexus targets in depth
Workspaces — The workspace model, editor, console, channels, and shortcuts
The Astromesh Ecosystem — How Cortex fits alongside Forge, Nexus, and Orbit