The thinking path
Darwin had a gravel path behind Down House that he called the Sandwalk. When he had a hard problem, he walked loops around it until the pieces fit together.
This project is built for that kind of work: problems that take days or weeks of iteration, not a single clever prompt.
Most AI tools are stateless chat boxes tied to one model vendor. Every new thread starts with amnesia, so you spend the first ten minutes pasting context and re-explaining your repo, your server, or your dataset.
Sandwalk flips the setup. A local server runs on your machine (or on a remote Linux box over SSH) and keeps your sessions, files, wiki pages, knowledge graph, and skills on disk under ~/.sandwalk/. The native macOS/Ubuntu desktop app, the web UI, and the sandwalk terminal CLI are all clients of that same server.
You bring your own keys, your existing ChatGPT Plus/Pro login, or local GGUF weights. Nothing is locked inside a proprietary cloud.
Why people use it
- Run a split grid instead of trusting one model. Ask Capy (the built-in meta-agent) to fan a prompt across a
2×2 or 3×2 grid of different models or Specialists. Compare their reasoning and outputs live in one window.
- Point it at any SSH box and it sets itself up. Enter
user@host in SSH and click Connect. Sandwalk logs in, installs the CLI in ~/.local/bin without sudo, starts a background daemon that stays alive after you disconnect, and opens a window tunneled to that machine.
- Put repetitive checks on a timer. Create an Automation (
every 15m, daily at 9am, cron, or a webhook) that runs a command locally or over SSH and only wakes the model when the output changes.
- Keep your existing terminal agents. Run Claude Code, Codex, OpenCode, fx, or Hermes inside Sandwalk terminals with live status badges. Convert any of their transcripts into a Sandwalk chat, or hand a Sandwalk chat straight into
claude --resume or codex resume.
- Turn finished work into a reusable skill. Distill sessions into your Living Wiki and Omnigraph knowledge graph, then click Create Skill to package the method into
~/.sandwalk/skills/<slug>/SKILL.md for the next run.
- Burst to cloud GPUs when your laptop is not enough. Run code locally by default, or attach a Modal container (
T4, L4, A10, A100, H100) per session. Every plot, 3D structure, or notebook lands back in your local workspace folder.
Tour
Memory without prompt rot
Stuffing old transcripts into a vector database or a giant system prompt degrades reasoning and invalidates your LLM prompt cache on every turn.
Sandwalk freezes a compact prefix at the start of a session (USER.md, MEMORY.md, PRIORS.md, the Wiki table of contents, and the active graph schema) so KV caches stay warm. Deeper context lives on disk under ~/.sandwalk/ and is read on demand when the agent needs it:
flowchart LR
S1["Past Sessions"] --> A1["Chat Memory"]
S2["Docs & Notes"] --> A2["Living Wiki"]
S3["Domain Data"] --> A3["Omnigraph"]
S4["Completed Tasks"] --> A4["Skills"]
A1 & A2 & A3 & A4 --> Hub[("~/.sandwalk/")]
Hub --> Next["Next Agent"]
Full walkthrough: sandwalk.sh/docs/memory.
Install
Desktop app
Download an installer from the latest release:
On Ubuntu 24.04 or 26.04, you can also install and update through APT:
curl -fsSL https://apt.sandwalk.sh/sandwalk.gpg | sudo gpg --dearmor -o /usr/share/keyrings/sandwalk.gpg
echo "deb [arch=amd64,arm64 signed-by=/usr/share/keyrings/sandwalk.gpg] https://apt.sandwalk.sh stable main" | sudo tee /etc/apt/sources.list.d/sandwalk.list
sudo apt update && sudo apt install sandwalk
CLI (macOS & Linux)
curl -fsSL https://sandwalk.sh/install.sh | bash
sandwalk setup # providers, API keys, or ChatGPT Plus/Pro login
sandwalk desktop # optional: installs the desktop app for your OS
From source
git clone https://github.com/fastfold-ai/sandwalk.git
cd sandwalk
pnpm install
cd cli && uv sync --extra all && cd ..
scripts/dev-api.sh # agent API on :8787
scripts/dev-ui.sh # Tauri window + Vite on :1420 (`web` for browser only)
CLI
Run sandwalk in any terminal, or press ⌘⇧T in the desktop app.
sandwalk # interactive TUI session
sandwalk "question" # one-shot prompt
sandwalk setup # configure providers, keys, and default model
sandwalk login chatgpt # use a ChatGPT Plus/Pro plan for OpenAI models
sandwalk serve # run the local agent API on :8787
sandwalk cron list # list and trigger scheduled Automations
sandwalk ssh list # manage SSH hosts, remote commands, and tunnels
sandwalk skills add fastfold-ai/skills
sandwalk mcp list
sandwalk sandbox status # Local or Modal GPU sandbox
sandwalk eval # run benchmark suites (MMLU-Pro, LiveCodeBench, BixBench)
sandwalk doctor # check environment and provider health
sandwalk upgrade
Inside an interactive session, / opens the command menu (/models, /effort, /plan, /specialist, /skills, /mcps, /sandbox, /agents, /compact, /export). Full CLI reference: cli/README.md.
Benchmarks & Roadmap
Sandwalk includes an evaluation runner (Dashboard → Benchmarking and sandwalk eval) that tests the full harness (model, Specialist, skills, tools, and sandbox) end to end:
| Shipped suites | Next up on the roadmap |
|---|
| MMLU, MMLU-Pro, ARC-C, MBPP, LiveCodeBench | Long-horizon memory & Omnigraph recall bench across Cookbook modes 01–06 |
| BixBench (bioinformatics) & Bio-Capybara | Skill crystallization lift evals (before vs. after packaging a /skill) |
| Multi-model and multi-Specialist A/B runs with per-step trajectories | Multi-Specialist grid vs. single-agent ablations |
| Token, latency, and cost breakdowns per question | SWE-bench Verified & Terminal-Bench PTY suites |
Disk layout (~/.sandwalk/)
| Path | Contents |
|---|
config.json | Providers, API keys, active model, sandbox and memory settings |
mcp.json | MCP servers (Cursor-compatible, including the local omnigraph server) |
skills/ | Installed and user-created skills (<slug>/SKILL.md + references/) |
memory/ | USER.md, MEMORY.md, memory.db, wiki/<scope>/*.md, and omni/<scope>/graph.omni |
bin/ | Managed local binaries (omnigraph, omnigraph-server, sandwalk-omnigraph-mcp) |
workspaces/<session>/ | Per-session files: uploads/, outputs/, plans/, project/ |
agent-server.db | Sessions, Automations, and SSH hosts shared by the CLI and desktop app |
Development
| Directory | Contents |
|---|
cli/ | Python agent, 190+ tools, built-in skills, Automations & SSH services, FastAPI server |
apps/local-web/ | React dashboard and Tauri desktop shell |
apps/sandwalk-mac/ | Swift menubar helper that supervises the local server |
apps/packaging/ | Signed macOS DMG, notarization, Ubuntu .deb & APT scripts |
scripts/verify.sh # typecheck, lint, build, unit tests + coverage gates (web + cli)
scripts/verify.sh e2e # Playwright: grid, terminals, PTY round-trip
pnpm e2e:bench # perf report -> apps/local-web/e2e/results/grid-latest.json
See AGENTS.md, .agents/skills/, CONTRIBUTING.md, .github/TESTING.md, and apps/packaging/APPLE-SIGNING.md.
Acknowledgments
Sandwalk builds on and draws inspiration from:
- Omnigraph (
ModernRelay/omnigraph) & omnigraph.dev: Versioned Rust + Lance graph engine, .pg schemas, .gq queries, Git-style branching, and Cookbook ontologies.
- LangChain, LangGraph & Deep Agents (
langchain-ai/deepagents): Core agent execution graph, streaming tool orchestration, and model adapters.
- Hermes Agent (
NousResearch/hermes-agent): Bounded session-start USER.md / MEMORY.md snapshot design and SQLite FTS5 session_search.
- TencentDB Agent Memory (
TencentCloud/TencentDB-Agent-Memory): Four-asset memory hub (Chat Memory, Skill, Wiki, Graph) and the save-file skill model.
- skills.sh (
vercel-labs/skills): Open SKILL.md specification and public skills catalog.
- llama.cpp (
ggml-org/llama.cpp) & Modal: Local GGUF inference and on-demand cloud CPU/GPU sandboxes.
License
Apache License 2.0. Copyright © 2026 Fastfold AI Labs.
