Getting started

Quick start

Get from zero to a real crash-and-resume in a few commands. Every secret comes from environment variables — nothing is hard-coded.

1. Install

Clone the repo and install the package with all optional extras (engine, MCP server, and demo agent).

install

git clone https://github.com/faithabiodun/tuskpoint.git
cd tuskpoint
python -m pip install -e ".[all]"

configure

cp .env.example .env   # then fill in your keys

What needs keys, and what doesn't

Reads from Walrus are public and free. Only writes (checkpoint_save, checkpoint_fork) need a publisher, and semantic search (checkpoint_search) needs MemWal credentials. The server runs without either — those tools return a clear message instead of failing.

2. Prove the Walrus round-trip

This writes a tiny blob to a publisher and reads it back from an aggregator, confirming your endpoints work end-to-end.

round-trip

python scripts/check_walrus.py

3. Run the crash / resume demo

The demo runs a small LangGraph research agent, persists each step to Walrus, then exits the process. A second, fresh process resumes from the last checkpoint — proving the state survived outside any single run.

part 1 — run, persist, EXIT

python demo/run_demo.py --real --part1

part 2 — fresh process resumes from Walrus

python demo/run_demo.py --real --part2

4. Start the MCP server

The same engine is exposed as an MCP server over stdio. Run it directly, or register it with a client (see Connect a client).

mcp server

python mcp_server/server.py

Next steps

Browse the full tool reference, learn how fork & replay works, or wire TuskPoint into Claude, Cursor, or Windsurf.