# Maple Local

Run Maple as a single binary on your machine — OTLP ingest, an embedded ClickHouse, a query API, and the dashboard, with no cloud and no auth.

import LocalHero from "../../components/local/LocalHero.astro"
import LocalFlow from "../../components/local/LocalFlow.astro"
import LocalCommandGrid from "../../components/local/LocalCommandGrid.astro"
import InstallTabs from "../../components/local/InstallTabs.astro"

<LocalHero />

Local mode is the fastest way to look at OpenTelemetry data — point any OTLP exporter at `localhost`, open the dashboard, and explore traces, logs, and metrics with no account and nothing to deploy. It's the same query engine and UI as hosted Maple, running entirely on your machine. Everything is single-tenant: every row is stored under `org_id = "local"`.

## Install

Pick your package manager. Homebrew is the easiest path on macOS and Linux; the install script works anywhere a shell does.

<InstallTabs />

> Prefer to do it by hand? Download a release bundle (both `maple` + `libchdb`) from [GitHub Releases](https://github.com/Makisuo/maple/releases), or read [`scripts/install.sh`](https://github.com/Makisuo/maple/blob/main/scripts/install.sh) first before piping it to a shell.

## Start the server

```bash
maple start            # OTLP ingest + embedded ClickHouse + query API on :4318
maple start --offline  # …serve the UI bundled in the binary (no internet, no prompts)
maple start -d         # …or detached; logs to ~/.maple/maple.log, stop with `maple stop`
```

`maple start` is the long-lived process: it owns the embedded ClickHouse (chDB) connection and hosts OTLP/HTTP ingest, the `/local/query` API, and (with `--offline`) the dashboard — all on one port that binds loopback by default. Data persists in `~/.maple/data` between runs.

Common flags: `--host` (default `127.0.0.1`), `--advertise-host`, `--port` (default `4318`), `--data-dir` (default `~/.maple/data`), `--offline`, `--background`/`-d`, and `--reset` to wipe an incompatible store before starting. See the [CLI reference](/docs/local-mode/cli-reference#server-commands) for the full list, plus `maple stop` and `maple reset`.

To reach the bundled UI from another machine, opt into the complete unauthenticated listener and print a real client-facing hostname:

```bash
maple start --host 0.0.0.0 --advertise-host maple.home.arpa --offline
```

This exposes the UI, raw SQL query API, health endpoint, and direct OTLP routes—not just ingest. Use it only on a trusted network or behind TLS with browser-compatible authentication. The bundled UI does not add a Bearer API key or propagate an entry-page query parameter to API requests.

## Send telemetry

The server speaks OTLP/HTTP on `POST /v1/{traces,logs,metrics}` (protobuf or JSON, gzip optional) — the same protocol every OpenTelemetry SDK already exports. Point your app at it; no auth header is needed locally:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"
export OTEL_SERVICE_NAME="my-service"
```

That's it — most exporters default to protobuf and work out of the box. For language-specific setup (custom spans, log correlation, framework auto-instrumentation), follow the [instrumentation guides](/docs/getting-started/introduction). Any data you can already send to hosted Maple flows into local mode unchanged.

<LocalFlow />

## Open the dashboard

By default `maple start` points you at the auto-updating dashboard hosted at `local.maple.dev`, which talks back to your binary on loopback (the startup banner prints a link with the bound `?port=`). Because that page is a public origin reaching a local server, Chrome may show a one-time "access devices on your local network" prompt.

Pass `--offline` to serve the dashboard bundled inside the binary from the configured bind address instead: same-origin, no prompt, and it works with no internet. The banner prints a connection-safe address; wildcard LAN binds should set `--advertise-host` to the hostname another browser will use.

## Query from the terminal

The same binary is also a query CLI. Every command runs against the running server and prints JSON by default (add `--format table` for an aligned table, or `--debug` to see the compiled SQL on stderr):

```bash
maple services                         # active services at a glance
maple traces --service api --since 1h  # recent spans for one service
maple errors --since 24h               # error groups by fingerprint
maple query "SELECT count() FROM traces"
```

<LocalCommandGrid />

Most query flags are shared: `--since` (e.g. `30m`, `1h`, `24h`, `7d`) or absolute `--start`/`--end`, `--service`/`-s`, `--env`/`-e`, and `--limit`/`-n`. The full surface — every command, argument, and flag — lives in the [CLI reference](/docs/local-mode/cli-reference).

## Local vs. remote

The same CLI talks to either your local server or a hosted Maple workspace. The mode is resolved per command: an explicit `--local`/`--remote` flag wins, then a pinned default (`maple use local|remote|auto`), then auto-detect — a stored token implies remote, otherwise it probes the local server's `/health`. Run `maple whoami` to see what's resolved. Connect a remote workspace with `maple login`; details are in the [CLI reference](/docs/local-mode/cli-reference#auth-and-configuration).

## How it works

One Bun-compiled binary is both the CLI and the server, talking to ClickHouse in-process via `bun:ffi` → `libchdb` (no subprocess, no second language). For the architecture, the `/local/query` contract, the UI-origin model, and the release bundle, see the [local-mode design doc](https://github.com/Makisuo/maple/blob/main/docs/local-mode.md).