Architecture
Corral is a thin layer of Rust between herdr and the engines that do the heavy lifting. This page shows the pieces, what runs where, and how code, tables and plots travel between them.
The layers
- herdr is the terminal workspace. The agent, the script, the console and the variables are herdr panes, so closing the window loses nothing. Corral talks to herdr through its socket: one JSON request, one JSON reply, no CLI process per call.
- corral is one Rust binary that depends only on the C library. The short commands (a layout, sending code,
corral eval) run and exit in milliseconds; the long-lived ones are the viewers (the variables pane, the table viewer) and Mirador's server, a few MB each. - The engines. Ark runs R, and corral talks to it over ZeroMQ with the Jupyter protocol, implemented in corral itself. IPython runs Python in your project's uv environment. DuckDB answers the table viewer's queries. Mirador shows plots, and tables when you ask, in your browser.
Inside the binary
| Modules | What they do |
|---|---|
ark, zmtp, sha256 | The R console in front of Ark: ZeroMQ, Jupyter messages and their signatures, a line editor with history and completion. |
lsp | Connects the editor to Ark's language server, inside your live R session. |
console, workspace, layout | The layouts, which pane gets the space, and finding, starting or bringing in a console. |
send, eval | Code from the editor (Ctrl+R, F5) and from agents into the console. |
vars, table | The variables pane and the table viewer, which asks DuckDB only for what is on screen. |
plots, mirador | View(), plots, and Mirador's server and page. |
atajos, theme | The shortcut palette, and one palette of colors taken from herdr's theme. |
install, setup, zip | The installer, Ark's download, and unzip and inflate for the releases. |
herdr, term, json, toml, env | herdr's socket, the terminal, the config and state files, and the helpers the rest share. |
How things travel
Code
Ctrl+R in the editor runs corral send; an agent runs corral eval. Both bring the console into view, starting it if needed, and type into it through herdr, so the code runs in your live session and you watch it happen. corral eval writes the code to a file and types a short call that runs it, then hands the agent what was printed and any new plots as PNG. After every command the session writes vars.json, and the variables pane redraws from it.
Tables
View(df) writes the table to a temporary Parquet file (with arrow or nanoparquet in R; polars, pyarrow or pandas in Python; CSV when none is installed) and opens the table viewer in a popup next to the console. The viewer never loads the table: each page, count, sort, search, filter and summary is one DuckDB query on the file, so ten million rows open in about 34 ms and the viewer itself stays around 3 MB.
The terminal is the default. When you want the browser, press m in the viewer or in the variables pane, or call View(df, mirador = TRUE): Mirador opens the same file, with the same queries and the same keys.
Why a file in between? The viewers run in their own processes, outside R and Python, so your console stays free while you look and closing a viewer can't touch your session. Parquet is the format DuckDB reads fastest: columnar and compressed, so a query reads only the columns and row groups it needs.
Plots
Corral's R file makes httpgd the graphics device, and Python gets a small server with the same API. Mirador's server reads the plots from it, and the page shows each new one about 80 ms after the command that drew it.
What runs where
| Process | Written in | Lives |
|---|---|---|
| herdr | Rust | While your workspaces exist, with or without a window |
corral commands | Rust | Milliseconds per command |
| Variables pane, table viewer, Mirador's server | Rust | While open |
| Ark and your R session | Rust and R (r/corral.R runs inside R) | Your R console |
| IPython | Python (py/corral_py.py) | Your Python console |
| Fresh and Corral's plugin | Rust and TypeScript | The script pane |
| DuckDB | C++ | One short run per query |
| Your agent | Any | Its own pane |
State on disk
Corral keeps no database and no daemon of its own. What it remembers is in plain files:
~/.local/state/corral/sessions/<id>/: one folder per R or Python session, withmeta.json,vars.json, the plot server's address and whatcorral evalexchanges. It is removed when the session ends.~/.local/state/corral/: Mirador's address and token, the script drafts, the R console's history and the installer's record of what it changed.~/.config/corral/config.json: whatcorral configsets. Keys and the theme live in herdr's ownconfig.toml.