Run locally

Open the archive.

This site replays recorded runs and links their supporting project evidence. To seed your own ghost, delete its source and watch it come back, run the local lab on your machine: with Python and no extra packages in fixture mode, or with live Gemma through Ollama.

01 · Requirements

What you need.

The core is standard-library Python with SQLite and a plain HTML, CSS and JavaScript front end. There is no build step. Fixture mode needs Python, but no extra Python packages, model or network.

PythonRequired
Python 3.12 or newer (requires-python = ">=3.12"). Verified with 3.12.6; newer versions are untested.
Python packagesNone
The core uses only the standard library. The optional sentry-sdk==2.72.0 extra is needed only for metadata-only tracing.
Ollama + GemmaLive mode only
Ollama running locally with gemma4:e2b-it-qat pulled (about 4.3 GB). GhostCache calls it at the fixed local address shown below and nowhere else.
Node.jsOptional for tests
Needed by 23 of the 24 lab UI tests and four public-site tests: 27 tests skip without Node. The remaining lab UI test is pure Python. Running the lab itself needs no Node or npm packages.
BrowserAny recent
The lab is a single page served by the same local process. It works offline and loads no external assets.

02 · Fixture mode

Start with no model at all.

Fixture mode is the default. It is a deterministic simulation: explicit string rules stand in for the model, so the storage, provenance, retrieval and cleanup logic can run anywhere. It never claims to be AI output.

  1. Get the code

    Clone the repository and work from its root, the folder that holds pyproject.toml.

    Terminal
    git clone https://github.com/bipul724/GhostCache.git
cd GhostCache

  2. Start the local lab

    This serves the lab on the loopback address only, in fixture mode.

    Terminal
    python3.12 -m ghostcache serve --port 8765

    It resets a disposable database. Starting the server, and every successful Seed or Reset, replaces the contents of the demo database (by default .local/assistant.sqlite) with a freshly seeded experiment. Never point --database at a file you want to keep.

  3. Open the working bench

    Visit the address the server prints, http://127.0.0.1:8765, in your browser. The banner should read Fixture — deterministic simulation. Then follow the five guided steps and verify the cleanup.

03 · Live Gemma mode

Run the experiment with real local inference.

Live mode sends the same experiment to Gemma through your local Ollama at 127.0.0.1:11434. Nothing is sent to a hosted model. If anything goes wrong it reports the error instead of quietly using fixture output.

  1. Check that the model is installed

    Pull it once if it is missing. Start ollama serve in another terminal only if Ollama isn't already running.

    Terminal
    ollama list                    # should list gemma4:e2b-it-qat
ollama pull gemma4:e2b-it-qat  # only if it is missing

  2. Start the lab in live mode

    Or start in fixture mode and switch with the lab's Mode menu once Live Gemma shows as available. Changing mode starts a fresh experiment.

    Terminal
    python3.12 -m ghostcache serve --port 8765 --mode live --model gemma4:e2b-it-qat

  3. The first call can be slow

    Seeding makes four model calls: three summaries and a saved answer. In the recorded runs, the first call took 40.41 s in the run made just after Ollama was started, 2.28 s in the run straight after it, and 81.25 s in the separate October 27 run; later calls took a few seconds each. That is consistent with Ollama loading the model on its first request, but the reports record call durations, not Ollama's load time, so the cause is inferred, not measured. The lab shows elapsed time while it waits; it can't predict how long a local model will take.

04 · Evaluation and tests

Record a run of your own.

The command-line evaluation runs the whole experiment on a fresh in-memory database, applies all ten checks and writes a JSON report. It exits 0 only if every check passes. Write each report to a new file name.

Terminal
python3.12 -m ghostcache evaluate --mode fixture --output results/my-fixture-run.json
python3.12 -m ghostcache evaluate --mode live --model gemma4:e2b-it-qat --output results/my-live-run.json

The test suite runs offline, with no network or model:

Terminal
python3.12 -m unittest discover -s tests -v

Latest local verification, October 30, 2026: 126 tests passed with Node and the optional Sentry SDK installed. Without the SDK, the suite still runs 126 tests with six telemetry tests skipped. These are regression tests, separate from a recorded evaluation's ten checks. Current project evidence

05 · Optional Sentry tracing

Trace the work without exporting the content.

Tracing is off by default. The core needs no Sentry account or SDK. To send traces to your own project, install the optional SDK in a virtual environment and set your project's DSN explicitly; GhostCache does not load .env automatically.

Terminal · replace the DSN placeholder
python3.12 -m venv .venv
.venv/bin/python -m pip install "sentry-sdk==2.72.0"
export GHOSTCACHE_SENTRY_DSN="https://<public-key>@<org>.ingest.sentry.io/<project-id>"
.venv/bin/python -m ghostcache evaluate --mode fixture --output results/my-traced-fixture-run.json

Choose a report filename that does not already exist. With the SDK installed, run the full local suite with .venv/bin/python -m unittest discover -s tests -v. Node is still needed for the Node-based tests.

Allowed metadata includes model names, timings, token counts, synthetic artifact IDs and marker-present booleans. Document titles and bodies, prompts, questions, answers and the marker are excluded, and error events are dropped. The hosted walkthrough sends no Sentry traces. Tracing setup and privacy boundary ↗

Real traces from October 28 are already archived with two explained findings. Those historical traces are evidence, not a claim that tracing is enabled in your local run. View the project evidence

06 · The two modes

Always labelled, never mixed.

Fixture

Fixture — deterministic simulation

  • String rules write the summaries and answers; no model is called.
  • Works offline with Python and no extra packages; CI uses it.
  • A pass supports the storage, provenance, retrieval and preservation logic, not model behaviour.
  • Token counts are empty, because nothing is generated.
Live Gemma

Live Gemma — local model inference

  • Gemma writes the summaries and answers through your local Ollama.
  • Answers show the model name, duration and token counts.
  • A pass supports the same logic plus that model's behaviour in that run.
  • Errors stay errors: there is no fallback to fixture output.

07 · Troubleshooting

When the archive won't open.

Live Gemma shows as unavailableOllama is unavailable (connection failed). Fixture mode still works.

GhostCache checks Ollama's model list before offering live mode. Start Ollama, confirm that ollama list shows the model, then reload the lab. If the message reads Install gemma4:e2b-it-qat in Ollama to enable live mode, Ollama is running but the model isn't pulled. To use a different installed model, pass --model or set GHOSTCACHE_MODEL.

A live action fails with a model errorLocal model call failed (timed out). No fixture fallback was used.

A failed or malformed model response is reported, never replaced with fixture text. If seeding fails, the previous experiment stays current and nothing partial is published, and the run-mode menu returns to that experiment's mode, so the next reset does not repeat the failed one; if only the summary rebuild after cleanup fails, the cleanup itself stays complete and the lab says so. Errors name only a fixed category, such as connection failed or timed out, never the underlying text. Check that Ollama is still running and try again.

Cleanup finished, but the rebuilt summary failedThe rebuild warning stays until the outcome is resolved.

The purge and summary rebuild have separate outcomes. A failed rebuild does not restore the purged content. The lab reads the controller's current rebuild outcome, so the warning survives a page reload, repeated cleanup and later events leaving the 50-event ledger window. Repeating cleanup does not retry the rebuild, because nothing is left to purge; reset starts a fresh experiment, which clears the outcome. It is in-memory controller state and does not survive a server restart; starting the server seeds a new experiment.

A failed cleanup request may still have changed the experimentThe lab reads the server state back without repeating the deletion.

The purge can commit before storing a rebuilt summary fails. After any failed cleanup request, the lab fetches the current state once, keeps the original error and drops the old answer and checks if the experiment changed. If that read also fails, it says the state could not be confirmed and withdraws the old answer and checks. Read the resulting status before deciding what to do next; the lab does not automatically repeat the mutation.

The page says the local lab is not connectedStart the GhostCache server, then reload this page.

The lab's page needs the Python process that serves it. Start python3.12 -m ghostcache serve from the repository root and open the address it prints.

The port is already in useAddress already in use

If a GhostCache server is already running on that port, use its page. Otherwise choose another port with --port. Don't start a second server on the same port.

The lab refuses the request from another hostnameThis prototype serves localhost only.

The server binds to the loopback address and accepts only localhost or 127.0.0.1 as the host, which protects against DNS rebinding. It is single-user and must not be exposed as a shared service.

A reset reports a storage problemExperiment storage could not be restored; reset to recover.

If a failed reset leaves a database that can't be verified as unchanged and writable, the lab clears the experiment instead of serving a mismatched one. Reset again to recover.

python3 runs a different versionpython3 --version

Run every command with python3.12, the verified interpreter. Other versions of Python 3 are untested.