Skip to content

docs: simplify /leash copy and quick start #61

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
logohere merged 1 commit into from
Sep 1, 2026
Merged

docs: simplify /leash copy and quick start #61

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 53 additions & 60 deletions leash.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,16 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>leash — safety-gated robotics runtime | specdog</title>
<meta name="description" content="Open-source Rust robotics runtime with CLI, HTTP, MCP, simulation, replay, bounded navigation, advisory CUDA compute, and explicit physical safety gates.">
<title>leash — safe robot control from CLI, HTTP, and MCP | specdog</title>
<meta name="description" content="Leash is an open-source Rust runtime for robot control. Start in simulation, use CLI, HTTP, or MCP, and connect real hardware behind explicit safety checks.">
<link rel="icon" type="image/svg+xml" href="/dotdog/assets/dog.svg">
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; background: #fff; color: #1a1a2e; max-width: 760px; margin: 0 auto; padding: 24px 24px 40px; line-height: 1.7; }
nav { display: flex; justify-content: center; align-items: center; gap: 18px; flex-wrap: wrap; width: min(calc(100vw - 48px), 960px); margin: 0 auto 32px; padding: 8px 0 0; position: relative; left: 50%; transform: translateX(-50%); }
nav a { color: #6b7280; text-decoration: none; font-size: .9em; font-weight: 500; line-height: 1.4; }
nav a:hover, nav a.active { color: #d97706; }
h1 { font-size: 2.35em; margin-bottom: 8px; }
h1 { font-size: 2.4em; margin-bottom: 8px; }
h2 { font-size: 1.35em; margin: 38px 0 12px; border-bottom: 1px solid #e5e7eb; padding-bottom: 6px; }
h3 { font-size: 1.05em; margin: 24px 0 8px; }
p { margin: 10px 0; }
Expand All @@ -27,9 +27,12 @@
th { font-size: .85em; color: #6b7280; font-weight: 600; }
td { font-size: .92em; }
.hero-art { display: block; width: 108px; height: 108px; margin: 0 auto 20px; }
.lead { font-size: 1.08em; color: #374151; }
.rule { margin: 16px 0; padding: 12px 14px; border-left: 4px solid #d97706; background: #fffbeb; }
.lead { font-size: 1.12em; color: #374151; }
.sublead { color: #4b5563; }
.badge-row { display: flex; gap: 10px; align-items: center; margin: 18px 0; flex-wrap: wrap; }
.actions { display: flex; gap: 10px; margin: 18px 0 28px; flex-wrap: wrap; }
.button { display: inline-block; padding: 8px 13px; border: 1px solid #d97706; border-radius: 7px; text-decoration: none; font-weight: 600; }
.button.primary { background: #d97706; color: white; }
.grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(210px, 1fr)); gap: 12px; margin: 16px 0; }
.card { border: 1px solid #e5e7eb; border-radius: 8px; padding: 14px; }
.card strong { display: block; margin-bottom: 5px; }
Expand All @@ -54,104 +57,94 @@
<img class="hero-art" src="/assets/leash-robot.svg" alt="Robot being walked on a leash by the specdog mascot">

<h1>leash</h1>
<p class="lead">Open-source, safety-gated Rust runtime for robots, operators, and AI agents.</p>
<p class="lead"><strong>Safe robot control from the CLI, HTTP, and MCP.</strong></p>
<p class="sublead">Leash is an open-source Rust runtime for controlling robots. Start in simulation. Connect real hardware when you're ready.</p>

<div class="actions">
<a class="button primary" href="#quick-start">Get started</a>
<a class="button" href="https://github.com/specdog/leash">GitHub</a>
</div>

<div class="badge-row">
<img src="https://img.shields.io/badge/Rust-workspace-orange" alt="Rust workspace">
<img src="https://img.shields.io/badge/MCP-stdio%20%2B%20HTTP-blue" alt="MCP stdio and HTTP">
<img src="https://img.shields.io/badge/default-simulation--safe-green" alt="Simulation safe by default">
<img src="https://img.shields.io/badge/simulation-default-green" alt="Simulation by default">
<a href="https://github.com/specdog/leash"><img src="https://img.shields.io/github/stars/specdog/leash" alt="GitHub stars"></a>
</div>

<div class="rule"><strong>Core rule:</strong> an agent or operator can request motion; Leash decides whether motion is allowed.</div>
<h2 id="quick-start">Quick start</h2>

<h2>Current main</h2>
<pre><code>cargo install leash-harness
leash run sim-http</code></pre>

<p>Leash is now a multi-crate robotics workspace with one shared capability and safety boundary across CLI, HTTP, WebSocket/SSE telemetry, MCP stdio, and MCP Streamable HTTP.</p>
<p>Then, in another terminal:</p>

<div class="grid">
<div class="card"><strong>Safe local development</strong><span class="muted">Simulation, deterministic replay, record/replay JSONL, schemas, and no-hardware smoke tests.</span></div>
<div class="card"><strong>Bounded navigation</strong><span class="muted">Idempotent goal submission, status, cancellation, deadlines, pilot-lease requirements, and verified stop.</span></div>
<div class="card"><strong>Advisory compute</strong><span class="muted">Authenticated async temporal-spatial jobs with CPU authority, qualified CUDA acceleration, parity checks, and fallback.</span></div>
<div class="card"><strong>Physical boundary</strong><span class="muted">Feature-gated Waveshare UGV implementation; Leash remains the sole final device writer.</span></div>
</div>
<pre><code>leash health --url http://127.0.0.1:8000
curl -s http://127.0.0.1:8000/telemetry | jq</code></pre>

<table>
<tr><th>Layer</th><th>State on main</th></tr>
<tr><td>Interfaces</td><td>CLI, HTTP, MCP, SSE/WebSocket telemetry</td></tr>
<tr><td>Runtime</td><td>Typed capabilities, modules, replay, navigation, localization, safety policy</td></tr>
<tr><td>Compute</td><td>CPU + guarded CUDA advisory spatial processing</td></tr>
<tr><td>Hardware</td><td>Waveshare UGV implementation plus deployment/calibration evidence</td></tr>
<tr><td>ROS 2</td><td>Provider/proposal boundary; never a second motor owner</td></tr>
</table>
<p>This runs entirely in simulation. It cannot move physical hardware.</p>

<h2>Try it safely</h2>
<p>For MCP:</p>

<pre><code>cargo install leash-harness
leash run sim-http</code></pre>
<pre><code>leash run sim-mcp</code></pre>

<p>In another terminal:</p>
<h2>What it does</h2>

<pre><code>leash health --url http://127.0.0.1:8000
curl -s http://127.0.0.1:8000/telemetry | jq
leash agent-send "inspect the battery"</code></pre>
<div class="grid">
<div class="card"><strong>Control</strong><span class="muted">CLI, HTTP, WebSocket/SSE, and MCP.</span></div>
<div class="card"><strong>Simulate</strong><span class="muted">Run and test without a robot connected.</span></div>
<div class="card"><strong>Replay</strong><span class="muted">Record runs and replay them through the same telemetry path.</span></div>
<div class="card"><strong>Navigate</strong><span class="muted">Submit bounded goals, patrols, cancellations, and verified stops.</span></div>
<div class="card"><strong>Connect hardware</strong><span class="muted">Use feature-gated robot adapters when you're ready to leave simulation.</span></div>
<div class="card"><strong>Process sensor data</strong><span class="muted">Run bounded CPU jobs and optional CUDA acceleration.</span></div>
</div>

<p>Or expose the simulation runtime through MCP:</p>
<h2>Safety</h2>

<pre><code>leash run sim-mcp
<p>Leash owns the final command sent to the robot.</p>

# or localhost MCP HTTP
leash serve mcp-http --listen 127.0.0.1:9990
leash mcp list-tools
leash mcp call observe</code></pre>
<p>A planner, ROS 2 node, model, app, or agent can ask Leash to do something. It cannot write to the motors directly.</p>

<p>These default paths do not touch physical hardware.</p>
<p>Physical motion is off by default. Hardware commands pass authorization, approval, sensor freshness, deadman, collision, distance-limit, Stop, and E-Stop checks before reaching the robot.</p>

<h2>Safety boundary</h2>
<p><strong>Agents can request motion. Leash decides whether motion is allowed.</strong></p>

<p>Physical motion is fail-closed. Mapping, localization, planning, ROS 2, CUDA, model providers, and external agents can supply requests or evidence, but they do not bypass Leash's final command policy.</p>
<h2>Real hardware</h2>

<p>Physical paths remain subordinate to explicit compile/runtime gates plus authorization, approval, sensor/provider freshness, deadman, collision checks, soft odometry limits, Stop, and E-Stop.</p>
<p>The current hardware implementation is the <a href="https://github.com/specdog/leash/tree/main/implementations/waveshare-ugv">Waveshare UGV stack</a>.</p>

<p>Robot-specific device paths, calibration, deployment, rollback, and field evidence stay outside the reusable core. ROS 2 can provide mapping, localization, and navigation data; Leash remains the motor owner.</p>

<h2>Open source</h2>

<h3>Humans</h3>
<p>Clone the repository, work from current <code>main</code> on a branch, and use simulation first:</p>
<h3>Contributors</h3>

<pre><code>git clone https://github.com/specdog/leash.git
cd leash
npm ci
cargo build
cargo run -- run sim-http</code></pre>

<p>Before merge, contributors run formatting, workspace Clippy/tests, Node tests, schema checks, packaging, and the aggregate smoke suite. Hardware changes must stay feature-gated and require real evidence for physical claims.</p>
<p>Work from current <code>main</code> on a branch. Keep hardware changes feature-gated and test the simulation path without hardware.</p>

<p><a href="https://github.com/specdog/leash/blob/main/CONTRIBUTING.md">Contributing guide</a></p>

<p><a href="https://github.com/specdog/leash/blob/main/CONTRIBUTING.md">Human contribution guide</a></p>
<h3>Coding agents</h3>

<h3>Agents</h3>
<p>Coding agents start at the repository-root <code>AGENTS.md</code>. For project/spec structure, agents query the compiled DotDog graph rather than reading human <code>.dog</code> source:</p>
<p>Start with the repository's <a href="https://github.com/specdog/leash/blob/main/AGENTS.md">AGENTS.md</a>. Project structure is available through the compiled DotDog graph:</p>

<pre><code>npm ci
npx dotdog serve</code></pre>

<p><code>specs/leash/leash.dag</code> is the agent graph. Current code, tests, schemas, and merged docs on <code>main</code> define implementation behavior. If graph and code disagree, agents report the drift instead of inventing structure.</p>

<p><a href="https://github.com/specdog/leash/blob/main/AGENTS.md">Agent instructions</a> · <a href="https://github.com/specdog/leash/tree/main/.agents/skills">Agent skills</a></p>

<h2>In development</h2>

<p>Draft pull requests are not presented as shipped behavior. Current draft work includes durable agent workflows (#187), compact Qualia telemetry and gimbal/MCP integration (#188), and lossless applied-action evidence (#191). Older calibration/map/physical-navigation stacks (#179–#181) remain draft while physical acceptance evidence is incomplete.</p>

<p>Those branches must be reconciled with current <code>main</code> and re-verified before merge.</p>
<p>Agents query <code>specs/leash/leash.dag</code>. Humans own the <code>.dog</code> source.</p>

<h2>Links</h2>
<h2>Learn more</h2>

<p>
<a href="https://github.com/specdog/leash">GitHub</a> ·
<a href="https://github.com/specdog/leash/blob/main/README.md">README</a> ·
<a href="https://github.com/specdog/leash/blob/main/CONTRIBUTING.md">Contributing</a> ·
<a href="https://github.com/specdog/leash/issues">Issues</a> ·
Built with <a href="https://github.com/specdog/dotdog">dotdog</a>
<a href="https://github.com/specdog/leash/tree/main/docs">Docs</a> ·
<a href="https://github.com/specdog/leash/issues">Issues</a>
</p>

<footer>
Expand Down
Loading