# Apache Maka Examples: How to Use the Agent Workspace (Desktop, TUI, and CLI)

> Explore Apache Maka examples for Desktop, TUI, and CLI agent workspaces. Learn how Maka's Runtime Host executes tasks and records immutable RuntimeEvents for robust auditing.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: examples
- Published: 2026-09-11

---

**Apache Maka provides three primary interfaces—Desktop (Electron), TUI, and CLI—that share a common Runtime Host to execute agent tasks while recording every action as an immutable RuntimeEvent.**

Apache Maka (Incubating) is a high-performance agent workspace designed to orchestrate sessions, agents, models, and tool calls. Whether you prefer a graphical interface, a terminal-based experience, or fully automated scripting, the project offers concrete entry points for every workflow. Below are practical Apache Maka examples derived directly from the source code to get you started with development, execution, and debugging.

## Getting Started

To begin using Apache Maka, clone the repository and install dependencies:

```bash
git clone https://github.com/apache/maka.git
cd maka
npm ci

```

This prepares the monorepo environment, including TypeScript workspaces and Rust native addons.

## Desktop (Electron) Examples

The **Desktop UI** provides an interactive graphical client for visual task management and real-time agent monitoring.

### Hot-Reloaded Development Build

Start the Electron interface with immediate code updates:

```bash
npm run dev

```

This command launches the desktop application with hot-module reloading enabled, allowing you to modify source files and see changes instantly.

### Full Production Build

Compile every workspace before launching the desktop:

```bash
npm run dev:full

```

Use this when you need to verify that production assets build correctly before running the UI.

### Peer-Enabled Native Addon

For builds incorporating the Rust peer-mesh networking addon:

```bash
npm run dev:peer

# Or for a full build with peer support:

npm run dev:full:peer

```

These commands compile the native Rust components prior to starting the Electron shell.

### First-Run Configuration Workflow

When launching the Desktop for the first time, configure your model connection through the interface:

1. Open **Settings → Models**.
2. Add an **API key**, local model, or supported account connection.
3. Test the connection and set it as the default.
4. Return to the workspace and start a task.

Configuration persists in the Electron `userData` directory (e.g., `runtime.sqlite`, [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json), [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json), [`settings.json`](https://github.com/apache/maka/blob/main/settings.json)).

## CLI Examples (Non-Interactive)

The **CLI** enables scripting and automation without UI interaction, executing single agent turns via command-line flags.

### Execute a Single Turn

Run a one-off task that completes and exits:

```bash
npm run cli:dev -- run "Summarize this repository and identify its most important risk"

```

This invokes the runtime directly through `packages/cli`, processes the natural language prompt, and returns the result to stdout.

### Graph-Enabled Execution

Visualize the execution graph during a multi-step task:

```bash
npm run cli:dev -- --graph "Implement two independent slices, integrate them, then review the result"

```

The `--graph` flag renders the task topology, showing how `AgentRun` instances in [`packages/runtime/src/AgentRun.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentRun.ts) relate to each other within the session managed by the Runtime Host.

## TUI (Terminal UI) Examples

The **TUI** offers a curses-style interface for keyboard-driven interaction.

### Launch the Interactive Terminal

```bash
npm run cli:dev

```

Without additional arguments, this opens the text-based UI where you can type commands interactively.

### Visualize with the Graph Command

Inside the TUI, use the slash command to view execution flows:

```

/graph

```

This triggers the same graph visualization engine available in CLI mode but presents it within the terminal canvas.

## Building and Testing

### Compile All Workspaces

Build TypeScript, Rust, and other assets across the entire project:

```bash
npm run build

```

This generates the distribution files required for production deployment of any interface.

### Run Package-Specific Tests

Execute compiled test suites for individual components:

```bash
npm --workspace @maka/runtime run test:dist

```

This targets the specific workspace in `packages/runtime`, validating that the runtime logic functions correctly after compilation.

## Core Architecture and Key Files

Understanding these source locations helps when extending the Apache Maka examples above:

- **[`packages/runtime-host/src/RuntimeHost.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/RuntimeHost.ts)** – The core host implementation that boots the runtime and orchestrates model/tool interactions.
- **[`packages/runtime/src/AgentRun.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/AgentRun.ts)** – Implements a single agent execution turn, handling message loops and tool invocations.
- **[`packages/cli/README.md`](https://github.com/apache/maka/blob/main/packages/cli/README.md)** – Detailed documentation for CLI flags and scripting patterns.
- **[`packages/desktop/README.md`](https://github.com/apache/maka/blob/main/packages/desktop/README.md)** – Desktop-specific build instructions and Electron configuration details.
- **[`ARCHITECTURE.md`](https://github.com/apache/maka/blob/main/ARCHITECTURE.md)** – System map describing how Runtime Host → SessionManager → AgentRun components interact.
- **[`README.md`](https://github.com/apache/maka/blob/main/README.md)** – Overview and quick-start commands for the entire project.

All three interfaces log every model message, tool invocation, and permission decision as **RuntimeEvent** instances, creating an immutable audit trail of agent activity.

## Summary

- Apache Maka offers three entry points: **Desktop** (Electron GUI), **CLI** (scriptable), and **TUI** (interactive terminal).
- Use `npm run dev` for desktop development with hot-reloading, or `npm run cli:dev` for terminal-based interaction.
- Execute automated tasks via `npm run cli:dev -- run "your prompt"` for non-interactive agent turns.
- First-time Desktop users must configure model connections in Settings before executing tasks.
- All actions are recorded as RuntimeEvents by the shared Runtime Host, with source code centralized in `packages/runtime-host/` and `packages/runtime/`.

## Frequently Asked Questions

### How do I run Apache Maka without installing it globally?

Clone the repository, run `npm ci` to install dependencies, then use `npm run dev` for the Desktop or `npm run cli:dev` for the terminal interface. All commands execute from the project root using the local source code.

### Where does Apache Maka store configuration and logs?

The Desktop application stores configuration files—including `runtime.sqlite`, [`connection-catalog.json`](https://github.com/apache/maka/blob/main/connection-catalog.json), and [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json)—in the Electron `userData` directory specific to your operating system. The Runtime Host maintains an immutable event log within the SQLite database.

### Can I use Apache Maka entirely from the command line without a GUI?

Yes. The CLI interface supports fully non-interactive execution via `npm run cli:dev -- run "your task"`. This mode utilizes the same `RuntimeHost` and `AgentRun` classes as the Desktop but outputs results directly to the terminal without spawning Electron windows.

### What is the difference between `dev` and `dev:full` commands?

`npm run dev` starts the Desktop quickly with hot-module reloading, suitable for active development. `npm run dev:full` compiles all workspaces—including Rust native addons—before launching, ensuring production-equivalent assets are used during the session.