Workspaces & Layout

The workspace

A workspace is a folder with a .cortex/ directory. Cortex can live inside any git repository, next to your agents and your code.

my-project/
├── .cortex/
│   ├── workspace.json   # commit it
│   └── local.json       # gitignored on creation
└── orbit.yaml           # written by the GCP wizard, if you use it

workspace.json holds:

Field	Content
connections.runtime[]	Runtime connections: name, local or remote, URL
connections.nexus[]	Nexus connections: name, hub URL, auth mode, optional tenant id
activeRuntimeId, activeNexusId	Which connection each mode uses
environments, activeEnvironment	Named sets of variables (see below)
gcp	Project, region and auth method for the GCP panel
whatsapp	The WhatsApp wizard’s settings
ui.lastMode	The mode the workspace reopens in

Cortex saves the file half a second after any change, and reloads it when it changes on disk (after a git pull, say) unless you have unsaved changes. The Welcome page keeps the last 20 workspaces.

Caution

workspace.json is meant to be committed, and it stores environment variables and the WhatsApp wizard’s tokens in plain text. Do not put real secrets in environments of a workspace you push, or keep workspace.json out of the repository. Nexus credentials are different: they are kept by the operating system’s encryption, outside the workspace.

Runtime-mode layout

Area	Contents
Activity bar	Explorer · Agents · RAG Pipelines · Workflows · Runtime · GCP Deployments · Channels · Channel Activity · Settings
Sidebar	The selected panel. Click the active icon to hide it; drag the edge to resize
Editor area	Tabs: agent YAML, visual builder, RAG pipeline, workflow, workflow run, GCP wizard, infrastructure map
Right panel	The console
Bottom panel	Terminal · Activity (every API request Cortex made, filterable) · Output
Status bar	Mode switch, active connection with its health, runtime version and agent count, active environment

Panel	What it does
Explorer	Runtime status (version, uptime, agents) and a tree of agents, templates and built-in tools
Agents	Agents with their status (deployed, draft, paused) and load errors; new agent, visual editor, deploy, pause, delete
RAG Pipelines	Pipelines on the runtime; open as YAML or in the visual builder
Workflows	Run workflows, follow runs, approve or reject pending steps
Runtime	Install and control the local runtime
GCP Deployments	Provision and operate a Cloud Run runtime
Channels · Channel Activity	WhatsApp setup and live channel traffic
Settings	Runtime connections, environments, dev tunnel

Nexus mode has its own activity bar.

Runtime connections

Settings → Runtime Connections lists the runtimes this workspace knows. Each has a name, a type and a URL; click one to make it active. Every Runtime-mode panel talks to the active connection.

• local is the runtime Cortex installs. It counts as up when Cortex’s own process manager reports it running.
• remote is any other runtime, a Cloud Run service included. Its health is checked against /health every 15 seconds.

Environments

An environment is a named set of variables. Every workspace starts with default.

• Add, remove, clone and rename environments in Settings → Environments. Click a value to edit it in place.
• Choose the active one from the status bar (env: …) or with Activate.
• The active environment’s variables are passed to the local runtime when it starts or restarts. Changing environments does not restart a running runtime.
• The GCP wizard can inject an environment’s variables into the Cloud Run service.

The terminal

The bottom panel’s terminal is an astromeshctl-style command line over the active runtime’s API. It is not a system shell.

Command	Does
status, doctor, version, services	Runtime status, health checks, version, enabled services
agents	Agents and their status
tools	Built-in tools
traces list <agent>, trace <id>	Recent traces and one trace’s summary
metrics	Counters and histograms
mesh status	Mesh summary
run <agent> <query>	Runs an agent and prints the answer
workflows list, workflows run <name> [query]	Lists and runs workflows
approvals, approve <run_id> [comment], reject <run_id> [comment]	The human-in-the-loop queue
help, clear

Tab completes, ↑/↓ walk the history, and the ? button shows a clickable reference.

Keyboard shortcuts

Keys	Action
Ctrl+Shift+P	Command palette
Ctrl/Cmd+M	Switch between Runtime and Nexus mode
Ctrl/Cmd+S	Save the active tab
Ctrl/Cmd+B	Show or hide the sidebar
Ctrl/Cmd+J	Show or hide the bottom panel
Ctrl/Cmd+F4	Close the active tab (asks if it has unsaved changes)
Enter / Shift+Enter	Send / new line, in the console
Ctrl/Cmd+Enter	Send, in the Nexus run panel