Quick Start — Docker

Run Tomoshibi locally in 30 seconds. This is the recommended way — the hosted playground is rate-limited and ephemeral.

Hosted playground is a preview

Rate-limited, shared, no persistence. For crawl/batch/monitor and unlimited use, self-host with Docker.

Full stack — Docker Compose (recommended)

Clone

Get the source and compose file.

git clone https://github.com/Michael-Obele/tomoshibi.git && cd tomoshibi

Up

Starts api (7431) + web (7432) + mcp (7433) + redis (7434) + searxng (7435).

docker compose up -d
curl http://localhost:7431/health  # → {"status":"ok"}

Scrape

Smart mode is default — no config needed.

curl -X POST http://localhost:7431/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Single image

Docker Hub / GHCR

docker pull michaelobele/tomoshibi-api:latest
docker run --rm -p 7431:7431 michaelobele/tomoshibi-api
# or GHCR
docker pull ghcr.io/michael-obele/tomoshibi-api:latest

From source (Go 1.25+)

go run ./packages/api/cmd/api
# with async (crawl/batch/monitor)
REDIS_URL=redis://localhost:7434 go run ./packages/api/cmd/api

Next steps

API Reference

All endpoints with curl examples.

Try Playground

Test without Docker (limited).

Documentation