FAQ

Questions, answered from what is released

Each answer says what today's releases do, and links to the page that shows it. Where something is planned rather than released, this page leaves it out.

01

What it is

What each package does, and how it differs from tracing tools.

4 questions
What does onetrace do?

It records each stage of an AI pipeline (the code, the settings, every input and output by fingerprint) as a chain of linked records anyone can check. When an answer changes, it shows the first step that changed and what changed there.

How it works →

How is it different from tracing tools such as LangSmith, Langfuse or Datadog?

Tracing tools show you what happened, inside their service. onetrace gives you a record you can check yourself, with no network calls and no account: if a byte changes after the run, the check fails. It works beside them: the console can show your app's own OpenTelemetry spans at the step where two runs differ.

Where it fits →

What do onetrace, the console, onetrace-explain and onedoor each do? Do I need all of them?

onetrace records and verifies runs. The console shows runs in your browser, compares them and finds the first one that changed. onetrace-explain says what changed, with the evidence, and can add a model's reading. onedoor decides, per action, what an AI agent may do. Each works on its own; start with onetrace.

Developer guide →

Is it open source?

Yes, under the Apache-2.0 licence, on GitHub and PyPI.

Source on GitHub →

02

Trust and verification

What a verified run proves, and how you check one yourself.

5 questions
What does "verified" prove, and what doesn't it?

It proves the record is intact (no file changed after the run), complete as the run declared it, and in order. It doesn't prove the answer was right or the model behaved well. The non-claims page lists what a record does not prove.

Non-claims →

Can I verify a run without an account, a server or the internet?

Yes. onetrace-verify is a separate package that needs no network, no key and no account. Anyone you give a run folder to can check it the same way.

Stage records →

What happens if someone edits a record after the run?

The check fails. Each record holds the digest of the one before it, so a changed file breaks the chain from that point on.

The record format →

Are records signed and timestamped?

Records are always linked by their digests. You can also sign with your own Ed25519 key and anchor a run's time with an RFC 3161 time-stamp authority. An anchor is only as good as that authority's certificate, which the docs say plainly.

Manual →

Who holds the signing key?

You do. onetrace keygen writes the private key to a file you choose, readable by you alone, and onetrace never writes it into a run folder, logs it or prints it. A signature carries its public key, so a signed run still verifies if the private key is lost; you just can't sign new runs with it, so make a new key and add it to your trust list.

Manual →

03

Security

Reporting issues, release checks, and running the console safely.

7 questions
How do I report a security issue?

Email onetrace@oneproof.dev, and please don't open a public issue for a vulnerability. onetrace's SECURITY.md, in its source distribution, says what is in and out of scope; there is no fixed response time yet. Anything else goes to the issue tracker.

Report an issue →

Is there a threat model or security brief?

Not as a separate document yet. onetrace's SECURITY.md says what counts as a vulnerability and what is out of scope, and the non-claims page lists what a verified record does not prove.

Non-claims →

How do I know the package I install is the one released?

PyPI lists each release file's SHA-256, and pip install --require-hashes installs only files that match. From console 0.7.0, its release files built on Windows are the same bytes as those built on Linux.

onetrace-console on PyPI →

What checks does a release pass before it ships?

Before a onetrace release ships, its full test suite runs on the source and again on the public code, installed from the built packages in a fresh environment, and the packages are built twice and must come out byte-identical. The built files are also scanned for anything that should not ship. A failing test is fixed before release or waived with its reason recorded: console 0.7.0 shipped with nine such waivers, in tests that fail only on the exported code.

Changelog →

Is the console safe to expose on a network?

It is built to sit behind your own TLS proxy. Sign-in uses local accounts with scrypt-hashed passwords, sessions that time out, CSRF tokens on every action, and a rolling limit on sign-in attempts. Today every signed-in person is a viewer, and there is no identity provider: read the release's known gaps first.

Operator guide →

Where is the Explain key kept?

In your operating system's keychain, under your login, when you install onetrace-explain[keyring]. The console stores no key. Anyone who can run code as your user can read it, as with an environment variable.

Set up a model for Explain →

Can onetrace-explain make things up?

Its first answer, what changed and the evidence, uses no model at all. A model's reading is optional, labelled AI-generated, and each of its claims must cite a probe or an item of the record, or it is dropped and counted. What remains is still a reading, not proof.

Explain a difference →

04

Data and privacy

What a record holds, and what leaves your machine.

5 questions
Does onetrace send my data anywhere?

No. A run is files in a folder you choose, or in a bucket you configure. onetrace reports to no one, and the verifier makes no network calls.

Storage →

Does a record hold my prompts and outputs, or only fingerprints?

By default a run keeps each step's outputs and only fingerprints of its inputs. keep_inputs=["name"] also keeps that input's text, and keep_outputs=False keeps fingerprints of outputs and removes the files when the run closes. No onetrace command erases a kept input, but you can delete its file, or the run's inputs/ folder, and the run still verifies.

Manual →

Can I use it with personal or regulated data?

A run folder holds each step's outputs, which can include documents, prompts and answers; inputs are kept as fingerprints unless you ask to keep one. Treat run folders like logs that may hold sensitive data, and keep them where your data policy says. onetrace itself sends nothing anywhere.

Manual →

Does the console or Explain send records to a model?

Only when you ask. Explain sends to the model you configured, your provider's or one on your own machine, and shows what will be sent before anything goes. Without a model, it still gives what changed and the evidence.

Explain a difference →

Does the hosted demo collect anything?

The demo shows sample runs made when it was built, asks for no account and sets no cookie. When you use Compare, it keeps the comparison it computed so the next visitor gets the same page, and logs the pair, the result and the time, never your address. Its pages load nothing from other sites. This site, oneproof.dev, counts page views with GoatCounter, which sets no cookies, and serves its fonts itself.

Live demo →

05

Performance

The cost of recording, verifying and gating, as measured.

3 questions
Does it slow down model calls?

The call itself runs as before; onetrace records its request and response around it, so the cost is the recording's, not the model's. The console and Explain work only when you use them, never in your pipeline's path.

How it works →

How fast is the verifier?

On one machine, onetrace-verify checked a 1,000-step run in 0.45 s (0.42 to 0.46 s over 5 runs) and a 100-step run in 0.09 s, with 1 KB of output per step and Python's start-up included. Its time grows with the data recorded, not with model time. Measured with onetrace-verify 0.7.1 on an 8-CPU container.

Stage records →

How much latency does onedoor add to an agent's action?

On one machine, onedoor 0.10.2's library call decided a permitted action in 0.29 ms at the median and refused an undeclared one in 0.21 ms, over 1,000 decisions each; the 99th percentile was about 2.1 ms for both. Each decision is written to a local SQLite database before it returns, and no model is called.

onedoor for developers →

06

Engineering

Records on disk, OpenTelemetry, the specification and CI.

6 questions
What does a record look like on disk?

A run is a folder: one JSON receipt per stage, and a manifest whose chain head names the last one. It is plain files you can archive, copy or compare like anything else.

The record format →

How much disk does a run take?

With outputs kept (the default), a step costs its output plus about 1.5 KB of record: about 2.5 KB of files for a 1 KB output and 1.05 MB for a 1 MB output. With keep_outputs=False, a step costs about 1.5 KB whatever its output's size. Each file takes at least one filesystem block, so small steps use more on disk. Measured with onetrace 0.7.1.

The record format →

Does it work with OpenTelemetry?

Yes, beside it. Where a run keeps your app's traces, the console shows the spans at the step where two runs differ, attribute by attribute.

Developer guide →

Will records I make today still verify with later versions?

A record keeps the format it was written in, and later verifiers read earlier formats. A released verifier also reads a newer minor format, checking what it knows. The format page says how each verifier reads each format.

The record format →

Is there a specification I can implement against?

The format is documented, and an IETF Internet-Draft, draft-saha-stage-receipts, describes it. It is a draft, not a standard.

Stage records →

Can I run it in CI?

Yes. A check that fails exits non-zero (PASS 0, FAIL 1), so it can fail a build. Steps can declare expectations (expect=), which the check reads after the run. From onetrace 0.8.0, expect_mode="record" also checks each one as its step returns, and expect_mode="stop" stops the run at one that fails, before the next declared step; a call recorded through onetrace-auto still goes ahead.

Manual →

07

Getting started

What you need, and how little your code changes.

4 questions
What do I need?

Python and pip. onetrace needs Python 3.10 or later, onetrace-explain 3.11 or later, and the console 3.12 or later. There are install lines for macOS, Linux and Windows.

Install →

Do I have to change my code?

No. Either add a decorator per stage, or start your app with onetrace-run from onetrace-auto: calls through supported libraries become steps, and the run says what it could not see.

Zero-config →

Which model providers and frameworks are supported?

Any Python code can be recorded with decorators. Without code changes, onetrace-auto 0.8.0 records calls made through openai (1.40 up to 4), anthropic (2 up to 3), requests (2.28 up to 3), httpx (0.24 up to 1) and httpx2 (2 up to 3), the HTTP layer under openai 3.x, and, through langchain-core (1 up to 2), the chat models, LLMs, tools and retrievers a LangChain or LangGraph app runs. Inside a step, it also records reads and writes through psycopg, chromadb, pinecone, S3, Google Cloud Storage, Azure Blob Storage, Iceberg, Delta and a LangGraph checkpointer. From onetrace-auto 0.9.0 (released 2026-11-18), it also records calls made through litellm (1.80 up to 2) and google-genai (1.50 up to 4), and, inside a step, reads and writes through LangGraph's store, mem0, Letta and Zep. onetrace-auto's README on PyPI lists each library's versions and what a step records.

Zero-config →

Is there a way to learn it hands-on?

Yes: Learn's track 1, nine levels in about two hours.

Learn →

08

Agents and onedoor

Deciding what an agent may do, before it does it.

4 questions
How does onedoor stop an agent doing something it shouldn't?

Every action the agent proposes is checked against your policy before it runs: refused by default, permitted within caps you set, held for a person, or stopped by a kill switch. Each decision goes into an append-only ledger with a digest of the policy that made it.

onedoor →

Do I have to rewrite my agent?

No. onedoor sits in front of your tools as an MCP proxy, LangChain or LangGraph middleware, or an HTTP service.

onedoor for developers →

Can the system receiving the action check it was really allowed?

Yes, with a signed permit for the exact request, short-lived and usable once, which the receiving system checks without calling onedoor. In 0.10.2, the library call is the surface that issues permits.

onedoor for developers →

How do onedoor and onetrace fit together?

onedoor decides what an agent may do; onetrace records what it did. A onetrace record can hold onedoor's decisions, so a reviewer can check each gated step against its decision.

onedoor decisions in a record →

09

The project

Readiness, who builds it, and where to get help.

3 questions
Is it ready for production?

The recorder, verifier and console are released and versioned, and each release lists its known gaps. Read those before relying on it; for example, the console has no identity provider yet.

Changelog →

Who is behind it?

onetrace, onetrace-verify, onetrace-auto, onetrace-console and onedoor are written by Shamik Saha and published under oneproof, as open source under Apache-2.0.

onetrace on PyPI →

How do I get help or give feedback?

Open an issue, or write to onetrace@oneproof.dev.

Report an issue →