# TrialONE

> TrialONE investigates robot failures from live data, recordings and source code, produces evidence and a proposed action, and checks the repair on a fresh run. Access is by request.

## Get started

- [Introduction](https://trialone.dev/docs): Investigate robot failures from live data, recordings and source code. Check the repair on a new run.
- [Quickstart](https://trialone.dev/docs/quickstart): From an approved account to your first issue.
- [Pilot guide](https://trialone.dev/docs/pilot): Start with a real failure your team already spends time investigating.
- [How it works](https://trialone.dev/docs/how-it-works): Measurements identify departures. The investigation connects the evidence. A new run checks the result.

## Ways in

- [Recordings](https://trialone.dev/docs/recordings): What TrialONE reads, and what it makes of each kind.
- [Live on the robot](https://trialone.dev/docs/live): Watch a running robot and stay silent until something changes.
- [Coding agents](https://trialone.dev/docs/coding-agents): Let Claude Code, Codex or Cursor pick up a fault TrialONE found, and report the repair back.
- [The CLI](https://trialone.dev/docs/cli): The commands you use, what each is for, and the flags it takes.

## Working with issues

- [Issues and recipes](https://trialone.dev/docs/issues): One fault, across every run it appeared in, with what a fix needs.
- [Checking a repair](https://trialone.dev/docs/verify): Repeat the triggering scenario and check a fresh recording against the original finding.
- [Case history](https://trialone.dev/docs/history): Keep the finding, applied change and follow-up together for the next investigation.

## Account

- [Access and team](https://trialone.dev/docs/access): Who can use TrialONE, and how a team works in one workspace.
- [Data](https://trialone.dev/docs/data): Choose workspace uploads separately from the model used for an investigation.
- [Model settings](https://trialone.dev/docs/models): Use managed interpretation, your own provider key or a model endpoint on your network.

## Resources

- [For agents](https://trialone.dev/docs/for-agents): This documentation is written to be read by a model as well as a person.

---

<!-- https://trialone.dev/docs -->
# TrialONE documentation

Investigate robot failures from live data, recordings and source code. Check the repair on a new run.

TrialONE helps robotics engineers investigate failures across software and hardware. It connects measurements and logs with the source and configuration available to it, then produces a finding with evidence, a proposed change or a next measurement. You can investigate a running ROS 2 robot or analyse recordings on a laptop.

> **Start with one real incident.** Request Pilot Access, install the CLI and sign in with `trialone login`. Bring one failing recording, the symptom you observed and, if available, a healthy recording and the relevant source tree. Follow the [Quickstart](https://trialone.dev/docs/quickstart), then the [Pilot guide](https://trialone.dev/docs/pilot).

## The workflow

1. Connect the live robot or provide a recording. Name the robot so its runs stay together.
2. Review the evidence, proposed cause and remaining uncertainty in the report.
3. Apply the change yourself, or give the issue to your coding agent. Physical work needs a person at the robot.
4. Repeat the triggering scenario and compare a fresh recording with the original finding.

## Terms you will see

| Term | What it is |
| --- | --- |
| Machine | One robot. Its runs are filed under its name: `--machine`, the variable `TRIALONE_MACHINE`, or the computer's hostname. |
| Run | One diagnosis or live watcher session, with the measurements and available code, configuration and device metadata. |
| Finding | One thing that left its normal range, with the second it happened, the channels involved and the measured numbers. |
| Issue | Related findings grouped across runs. It is open, in repair, resolved or ignored. |
| Recipe | What a fix needs, in nine fixed fields, from the symptom to an acceptance criterion that a partial fix fails. |

## What do you want to do?

- [Quickstart](https://trialone.dev/docs/quickstart): Install, sign in and analyse your first recording.
- [Pilot guide](https://trialone.dev/docs/pilot): Choose an incident and agree what a useful result looks like.
- [How it works](https://trialone.dev/docs/how-it-works): What is measured, what is explained, and where the limits are.
- [Watch a robot live](https://trialone.dev/docs/live): Attach to the running ROS 2 graph and stay silent until something changes.
- [Hand a fault to a coding agent](https://trialone.dev/docs/coding-agents): Claude Code, Codex or Cursor reads the issue and reports the repair back.

---

<!-- https://trialone.dev/docs/quickstart -->
# Quickstart

From an approved account to your first issue.

You need an approved TrialONE account, Python 3.10 or newer and a recording to analyse. File analysis runs on Linux, Windows or macOS without a ROS installation. Watching a live ROS 2 graph also needs a working ROS 2 environment, `rclpy` and the message packages used by your robot.

## 1. Request Pilot Access

TrialONE is available to approved pilot teams. [Request Pilot Access](https://trialone.dev/request-access) with the email you will sign in with. You can sign in with Google or GitHub before the approval arrives; the app opens as soon as it does.

## 2. Install the command line tool

TrialONE is not on public PyPI. It comes from our own package index, and your CLI key is the password. Create one under [Settings, CLI keys](https://trialone.dev/app/settings/keys) and put it into the command; the same key signs this machine in afterwards.

```bash
pip install --index-url https://trialone:<your-cli-key>@trialone.dev/api/pypi/simple --extra-index-url https://pypi.org/simple trialone
```

For a microcontroller on a serial port (Arduino, ESP32), add the serial extra: `"trialone[serial]"` instead of `trialone`. If pip asks for a username and password, any username works and the CLI key is the password.

## 3. Sign in on this machine

```bash
trialone login
```

It shows a one-time code and opens [trialone.dev/cli-login](https://trialone.dev/cli-login) when you press Enter. Enter the code there while you are signed in to the app and approve it. On a robot over SSH, open that page on your laptop instead.

The terminal receives its own key, checked before it is saved, and `trialone whoami` shows which account it is connected to. Each machine gets its own key: revoking one under [Settings, CLI keys](https://trialone.dev/app/settings/keys) leaves the others working. Scripts can pass a key from there directly: `trialone login <key>`.

## 4. Diagnose a recording

```bash
trialone diagnose ./recording.mcap --machine amr-01 --symptom "The robot stops when it enters the loading area"
```

The terminal shows a summary and writes the full report and diagnosis JSON to `output/`. When signed in, it also sends the run to your workspace and prints its link. The report shows the finding, supporting measurements, proposed action and what still needs checking. Exit code 0 means analysis completed; it does not mean the robot is healthy.

Give the investigation useful context:

- `--symptom <text>`: describe what you saw, rather than a guess about the cause. This helps the investigation focus on your incident instead of an unrelated warning.
- `--machine <name>`: use the same name for every recording from this robot, especially when analysing several robots on one laptop.
- `--healthy <recording>`: another recording of the same robot that you know ran well. Without one, TrialONE can only compare a recording with itself, and a fault that lasts the whole recording then looks normal.
- `--project <folder>`: the relevant source checkout, including parameter, launch and URDF files. It gives the investigation code and configuration context; a precise file or line is included when the available evidence supports one.

```bash
trialone diagnose ./today.mcap --machine amr-01 --symptom "Stops in the loading area" --healthy ./last-good.mcap --project ./robot_ws/src --json ./diagnosis.json
```

## 5. Check the repair

After applying the change, repeat the scenario and make a fresh recording. Use the same healthy reference so both recordings are measured on the same basis:

```bash
trialone verify ./diagnosis.json ./after-repair.mcap --healthy ./last-good.mcap --json ./verification.json
```

The result is pass, fail or inconclusive, with the findings that disappeared, remained or appeared. It checks the supplied scenario; it is not a general guarantee that the robot cannot fail.

## Choose where data is processed

Detection runs on the machine where you start the CLI. Model interpretation is enabled when a model is configured, subject to your plan or provider. `--no-explain` skips model interpretation. `--no-push` skips the workspace upload, but does not disable model calls. See [Data and model processing](https://trialone.dev/docs/data) before using sensitive recordings.

## Next steps

- [How it works](https://trialone.dev/docs/how-it-works): what is measured, what is explained, and the limits.
- [Live on the robot](https://trialone.dev/docs/live): topics, growing files, CAN and serial ports.
- [Checking a repair](https://trialone.dev/docs/verify): compare the original finding with a new run.
- [Coding agents](https://trialone.dev/docs/coding-agents): let an agent pick up the fault and report back.

---

<!-- https://trialone.dev/docs/pilot -->
# Your first pilot

Start with a real failure your team already spends time investigating.

## Choose a useful incident

A good first case is a repeatable ROS 2 failure with logs or a recording: an intermittent stop, a node crash, delayed sensor data or a controller that stops responding. Choose a problem where your team can recognise a useful diagnosis and repeat the scenario after a change.

## What to bring

| Input | Why it helps |
| --- | --- |
| The failing recording or logs | Shows what actually happened. Include the lead-up to the failure, not only the final error. |
| A short symptom description | Keeps the investigation focused on the problem your operator observed. |
| A healthy run, if available | Separates a persistent fault from the robot's normal behaviour. Keep the task and channels comparable. |
| The matching source and configuration | Helps locate the mechanism and propose a specific change. Tell us if the checkout differs from what ran on the robot. |
| Robot, ROS and deployment details | Makes the result understandable in the context of your hardware and software versions. |

We can start with files on your laptop. A continuous live connection is useful later, when your team wants to capture intermittent incidents and check subsequent runs. Agree the data settings with your team before connecting; [Data and model processing](https://trialone.dev/docs/data) explains the choices.

## What you get back

- A finding with the relevant channels, log lines and timing.
- A proposed explanation tied to the evidence, with uncertainty or missing inputs stated.
- A repair proposal when the cause is supported, or a concrete next check when it is not.
- A follow-up comparison after your team applies the change and repeats the scenario.

## Agree what success means

Before starting, agree the symptom to resolve, the conditions needed to reproduce it and who reviews the result. Useful pilot outcomes are a supported cause, a check that narrows the investigation, or a repair that holds on the repeated scenario. Track investigation time and remaining failures alongside the verdict.

TrialONE proposes and measures; your team applies code, configuration and hardware changes. It does not automatically move the robot or begin a recording. A difficult case may end with a missing measurement rather than a confident repair.

## Arrange the pilot

[Request Pilot Access](https://trialone.dev/request-access) or [contact us](https://trialone.dev/contact) with your robot type, observed symptom and the data you can use. We will agree the incident, processing setup and follow-up with your team. Public validation examples are on [Proofs](https://trialone.dev/proof).

---

<!-- https://trialone.dev/docs/how-it-works -->
# How it works

Measurements identify departures. The investigation connects the evidence. A new run checks the result.

## Detection against the machine's own normal

TrialONE combines documented protocol and log checks with numerical comparisons. Depending on the input, it checks signals against the rest of the recording, earlier behaviour of the same machine or a healthy recording supplied with `--healthy`. A detected departure is evidence to investigate; it does not by itself establish the physical cause.

Repeated operations make numerical comparisons more useful. For example, one robot arm cycle can be compared with other cycles under similar conditions. Detection does not require a model, and its result can be reproduced with the same inputs, configuration and software version.

## Explanation: what the signal is, and why it moved

The model investigation uses tools to read available measurements, logs, source files and configuration. On a live ROS 2 robot, it can also inspect the graph, QoS, parameters and process state. It looks for a causal connection rather than returning a list of every possible cause.

For recording explanations, proposed mechanisms can include predictions that are checked against the measured data. Failed predictions are reported with the evidence that refuted them. A live proposal still needs follow-up evidence; a plausible explanation alone is not a verified repair.

The explanation never changes what was detected. With `--no-explain` you get the deterministic half on its own.

## Three zones per finding

| Zone | When | What you get |
| --- | --- | --- |
| FAULT | The finding has supporting evidence such as a decoded failure, missing data, a calibrated reference or a checked mechanism. | An actionable finding with the proposed repair or next check. |
| LOOK | There is a departure, but the evidence is not strong enough to establish a fault. | An observation to review, with the measurement needed next. |
| clear | The available checks found nothing to report. | No finding. This does not certify every part of the robot as healthy. |

An explanation can raise a zone, never lower it. Every report says how many findings stayed undecided, out of how many.

## Routing: software or hardware

The report proposes who should act: a software engineer or coding agent for code and configuration, a technician for a physical intervention, or a policy engineer when recorded commands explain the behaviour. Files and lines are included where they can be supported. Missing inputs remain visible in the report.

## Proof: the next recording decides

A person or coding agent reports a change. `trialone verify` compares a new recording with the earlier diagnosis and reports what disappeared, remained or appeared. A lower peak is not enough to pass when the same finding remains. See [Checking a repair](https://trialone.dev/docs/verify).

## What it does not do yet

- The live value-change trigger needs several channels moving together. An isolated value change can be missed; separate checks cover missing topics, timing and documented protocol failures.
- Explanations on the live path are leads, not verified answers. Predictions are checked against recordings, not against a running stream.
- A fault present in every operation of a recording is invisible without a healthy reference. Pass `--healthy`.
- Live camera frames can provide visual context to an investigation. They are not a general image fault detector. Point cloud geometry is not analysed.
- File and line evidence depends on the supplied source version. A checkout on your laptop does not independently prove what ran on the robot.
- A passing follow-up covers the recorded scenario and checks used. It does not certify safety or prove that an intermittent fault can never recur.

---

<!-- https://trialone.dev/docs/recordings -->
# Recordings and formats

What TrialONE reads, and what it makes of each kind.

Point `trialone diagnose` at a file or a folder; the format is recognised from the content, not from the file name.

| Kind | Files | Read as |
| --- | --- | --- |
| ROS 2 | rosbag2 folders, `.mcap`, `.db3` | Decodable numeric topic fields become channels. Logs, status messages and supported diagnostic records provide context. |
| ROS 1 | `.bag` | The same. |
| Tables | `.csv`, HDF5 | One column per channel. Semicolons and decimal commas are read as written. |
| Robot learning datasets | LeRobot v2 and v3, with `pip install "trialone[lerobot]"` | The numeric features per episode, with each joint's action paired with its observation. |
| PX4 | `.ulg` | Topics and messages. |
| ArduPilot | `.BIN`, MAVLink `.tlog` | Messages, parameters and decoded device IDs. |
| CAN | candump logs, Vector `.asc` | Frames per ID, with error frames decoded. |
| Network captures | `.pcap`, `.pcapng` | Transport timing, retransmits and connection events. |
| Crash reports | ARM Cortex-M hard faults, ESP32 panics, gdb backtraces, Linux kernel oops, ROS console logs | The failing frame, the fault register bits and the call chain. |
| A folder of runs | several recordings side by side | Each one on its own, unless the files are parts of one rosbag2 recording. |

## Tables

A table with a column called `time`, `timestamp`, `t`, `time_s` or `secs` needs no flags. Otherwise:

- `--time-col`: the timestamp column.
- `--group-col`: the column that groups rows into operations, for example a cycle or run number.
- `--label-col` with `--healthy-label`: a label column and the value that means normal, which then defines the healthy reference.

## A healthy reference

A reference has to be the same kind of recording with the same channels. If it is not, the report says so at the top instead of assuming anything.

```bash
trialone diagnose ./today.mcap --healthy ./last-good.mcap
```

For the live watcher, `trialone learn` reads previous recordings as earlier behaviour. This builds a local reference; it does not train model weights. Earlier does not mean healthy: a fault inside those recordings can become part of the reference. This command makes no model call or recording upload.

```bash
trialone learn ./logs
```

## What cannot be read

An encrypted or unknown file ends with a plain stop that names the one thing needed to go on, never with an invented diagnosis.

---

<!-- https://trialone.dev/docs/live -->
# Live on the robot

Watch a running robot and stay silent until something changes.

Start `trialone watch` in the robot's ROS 2 environment. It discovers readable topics, listens to numeric data and reports supported changes during the session. Missing message types and unreadable topics are named at startup. Check that it can see your graph before leaving it running.

Use the same ROS domain and source your ROS installation and workspace as you would for the robot's own nodes. With a model configured, an investigation can read live graph, log, parameter and process evidence. When signed in, the watcher also posts findings and checks in with your workspace.

```bash
trialone watch
trialone watch --topics /joint_states,/odom
```

## Other sources

| Source | Flag |
| --- | --- |
| A file that is still growing: a CSV with a header row, or lines of `key=value` | `--follow <file>` |
| An existing recording, played as if it were live | `--replay <recording>` |
| A microcontroller on a serial port: Arduino Serial Plotter lines, ESP32 crash reports | `--serial <port>`, with `--baud` |
| Several devices of one machine on one clock: CAN, host board, ROS graph | `--robot <robot.yaml>` |

The serial port needs the extra: `pip install "trialone[serial]"`.

## As a service

```bash
trialone install-service
trialone install-service --install
```

On Linux with systemd, the first command prints the user service. The second installs it, starts it and checks its status. It uses the saved login and model settings, the ROS distribution and domain selected during installation. The installer reports if permission is needed to keep it running after logout. If your robot needs a custom workspace or environment, review the generated service before relying on it.

A connected watcher posts findings, checks in every minute and receives workspace jobs such as building a reference or checking a repair. Configure its recordings folder under Settings, Robots for those recording jobs.

## Silence and incidents

When a watcher stops checking in, the website marks the machine as silent and alerts you. A watcher stopped by hand says so first, so a planned stop is not an alarm.

When you observe a problem, mark it with a short description. The active watcher uses the recent evidence around that moment to investigate what happened:

```bash
trialone mark "The robot stopped beside the loading station"
```

## Camera context

The current pilot watcher can keep a small recent buffer from supported ROS camera topics and send selected frames to the configured model during an investigation. This is visual context, not a continuous video upload or an image fault detector. Turn it off for a machine under Settings, Robots, or start with `--no-camera`. See [Data and model processing](https://trialone.dev/docs/data).

## Limits

- The numerical value-change trigger can miss an isolated change on one channel. This is separate from missing-data, timing and protocol checks.
- Explanations on the live path are leads. Verify them on a recording.

---

<!-- https://trialone.dev/docs/coding-agents -->
# Coding agents

Let Claude Code, Codex or Cursor pick up a fault TrialONE found, and report the repair back.

TrialONE serves an MCP endpoint on the website. A coding agent connected to it can list your issues, read one with its full recipe, claim the repair, and ask the robot to verify it. You can simply say:

> **Say to your agent.** Fix the newest open TrialONE issue and tell TrialONE when you are done.

## Connect

Create an agent key in the app under [Settings, Coding agents](https://trialone.dev/app/settings/agents). The page shows the block for each agent with the key filled in. Agent keys are separate from robot keys: they read issues and report repairs, and cannot post runs.

### Claude Code

```bash
claude mcp add --transport http trialone https://trialone.dev/api/mcp --scope user --header "Authorization: Bearer <key>"
```

### Codex

```
[mcp_servers.trialone]
url = "https://trialone.dev/api/mcp"
http_headers = { Authorization = "Bearer <key>" }
```

### Cursor

```
{
  "mcpServers": {
    "trialone": {
      "url": "https://trialone.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer <key>"
      }
    }
  }
}
```

For clients that need a local MCP process, the settings page includes an `mcp-remote` bridge configuration. Use the connection form supported by your client.

## Tools

| Tool | What it gives the agent |
| --- | --- |
| `list_issues` | What TrialONE found, newest first. |
| `get_issue` | The recipe: symptom, cause, numbers, files and lines, acceptance criterion. |
| `claim_repair` | Records the change and automatically queues the robot's recording check. |
| `request_verification` | Retries a check after a blocker is resolved. |
| `check_repair` | Progress per robot and measured results for the agent to continue with. |

## What an agent cannot do

No tool marks an issue resolved. The agent claims the repair; the robot's next recording decides. A passing verification closes the issue, and the fault coming back reopens it.

An issue routed as physical needs a person at the machine: a part, a connector, the mechanics. An agent should not change code to make such a symptom quieter.

## Without MCP

`trialone fix` hands a finished diagnosis to a coding agent on the same machine. It shows the exact command, the files the recipe names and the verdict, and asks before anything runs.

```bash
trialone fix <diagnosis.json>
```

---

<!-- https://trialone.dev/docs/cli -->
# The CLI

The commands you use, what each is for, and the flags it takes.

Use `--help` on a command to check the options in your installed version. The reference below follows the current CLI. Some newer features are available in pilot builds; [contact us](https://trialone.dev/contact) if your installation does not include one.

## Account

| Command | What it is for | Flags |
| --- | --- | --- |
| `trialone login` | Connect this terminal to your account. The key is checked before it is saved. | `--no-browser` `--paste` |
| `trialone whoami` | Which account this terminal is connected to, and whether it is approved. | none |
| `trialone update` | Install the newest version in one step. | none |

What changed in each version, and what reads differently after an upgrade, is in the [changelog](https://trialone.dev/changelog).

## Diagnose and check

| Command | What it is for | Flags |
| --- | --- | --- |
| `trialone diagnose <recording>` | Investigate a recording and produce findings, evidence and a proposed action. | `--description` `--explain` `--fail-on` `--full` `--group-col` `--healthy` `--healthy-label` `--history` `--json` `--label-col` `--machine` `--max-false-alarm` `--max-faults` `--no-explain` `--no-push` `--no-upload-raw` `--out` `--project` `--push` `--robot-hint` `--state` `--summary-md` `--symptom` `--time-col` `--upload-raw` |
| `trialone verify <diagnosis.json> <new recording>` | Measure a new recording against an earlier diagnosis and rule per finding. | `--attempt` `--group-col` `--healthy` `--json` `--max-false-alarm` `--no-push` `--push` |
| `trialone push <diagnosis.json>` | Send a diagnosis that is already on disk to your account, without analysing again. | `--machine` |
| `trialone fix <diagnosis.json>` | Hand a finished diagnosis to a coding agent on this machine, after asking. | `--agent` `--yes` |
| `trialone mark` | Say that something just went wrong, now or about a recording, and get one page back. | `--json` `--robot` |

## On the robot

| Command | What it is for | Flags |
| --- | --- | --- |
| `trialone watch` | Watch a running robot and stay silent until something changes. | `--baud` `--camera` `--expect-silent-after` `--explain-budget` `--follow` `--healthy` `--history` `--incident-at` `--json` `--max-false-alarm` `--no-camera` `--no-push` `--no-upload-raw` `--project` `--push` `--replay` `--robot` `--robot-hint` `--seconds` `--serial` `--speed` `--state` `--time-col` `--topics` `--upload-raw` `--window` |
| `trialone learn <folder>` | Read recordings the robot already made as earlier behaviour for the watcher. | `--label` `--max` |
| `trialone install-service` | Run the watcher as a service that survives a closed terminal and a reboot. | `--github` `--install` `--project` |
| `trialone watch-folder <folder>` | Diagnose every new recording that lands in a folder. | `--every` `--github` `--once` `--project` |
| `trialone attach` | Record what this robot is: board, OS, ROS distribution and packages, devices. Run it again after changes. | `--json` `--machine` |

## In a CI step

A completed diagnosis returns 0 whether or not it found a problem. Use `--fail-on` to fail a CI step on findings: `fault` follows the workspace alert rule, `finding` includes supported findings, and `any` also includes candidates. A matching finding returns 4. `--summary-md` appends a Markdown summary to a file, such as `$GITHUB_STEP_SUMMARY`. CI can use `TRIALONE_CLI_TOKEN` instead of an interactive login.

```bash
trialone diagnose recording.mcap --project . --fail-on fault --summary-md "$GITHUB_STEP_SUMMARY"
```

## Exit codes

| Command | Code | Means |
| --- | --- | --- |
| `diagnose` | 0 | The recording was read. The report is the answer, with or without findings. |
| `diagnose` | 2 | The recording could not be read. Nothing in the output is about the machine. |
| `diagnose --fail-on` | 4 | The recording carries a finding at the level you asked for. |
| `diagnose`, `verify`, `push` | 3 | The analysis or verdict completed, but the workspace upload failed. |
| `verify` | 0, 1, 2 | Pass, fail, inconclusive. |
| any | 77 | This terminal is not signed in with an approved account. |

## Environment

| Variable | What it does |
| --- | --- |
| `TRIALONE_MACHINE` | The machine name runs are filed under, instead of the hostname. |
| `TRIALONE_HOME` | Where TrialONE keeps its local state. Default `~/.trialone`. |
| `TRIALONE_CLI_TOKEN` | A CLI key without `trialone login`, for CI and containers. |

## Access

Every command that starts the engine first checks that the terminal is signed in and the account is approved. It asks the website at most once a day. Without a network, the last confirmation counts for 30 days, so a robot in a hall without Wi-Fi keeps running. `login`, `whoami`, `update` and `--help` work without it.

## Update or remove

`trialone update` installs the newest version. To remove the tool, uninstall it with pip. If the watcher runs as a service on this machine, stop it first with `systemctl --user disable --now trialone-watch.service`.

```bash
pip uninstall trialone
```

Uninstalling leaves the sign-in and local state in `~/.trialone` (on Windows `%USERPROFILE%\.trialone`); delete that folder too for a clean start. Revoke the key of a machine you no longer use under Settings, CLI keys.

---

<!-- https://trialone.dev/docs/issues -->
# Issues and recipes

One fault, across every run it appeared in, with what a fix needs.

## From finding to issue

A finding gets a fingerprint based on its kind, location and channels. Matching findings can be grouped in one issue across runs, so you can see recurrence and the affected machines. A matching fingerprint links similar evidence; it does not independently prove the same underlying cause.

## States

| State | Means |
| --- | --- |
| Open | Found and not yet worked on. |
| In repair | Someone claimed a repair: a person in the app, or a coding agent over MCP, with what changed. |
| Resolved | The linked verification passed its checks. If a matching finding returns, the issue opens again as regressed. |
| Ignored | Seen and set aside. It stays ignored when it comes back. |

## The recipe

Every finding carries the same nine fields. A field that could not be filled says what is missing instead of disappearing.

| Field | What it holds |
| --- | --- |
| Symptom | what the machine did |
| Causal chain | how that follows from the cause |
| Condition | the measured numbers this rests on |
| Change class | what kind of change is needed |
| Files and lines | where to make it |
| Reference pattern | what the corrected form looks like |
| Acceptance criterion | the test that rejects a partial fix |
| Blast radius | what else the change touches |
| Effort | what it costs to do |

`trialone diagnose --json` writes the recipes as JSON with exactly these fields, which is what the website shows and what a coding agent reads.

## The incident page

The incident page brings together the observed problem, available code and configuration metadata, the explanation, proposed action and next check. When history uploads are enabled, you can inspect the channels around the finding and compare them with other runs. Metadata from a local checkout describes the analysed source; it is not proof that this version was deployed when the recording was made.

## Sharing

From an issue you can open a GitHub issue, share it to Slack or Discord, and open the recording in Foxglove when the machine uploads its recordings. Connect these under Settings, Integrations.

---

<!-- https://trialone.dev/docs/verify -->
# Checking a repair

Repeat the triggering scenario and check a fresh recording against the original finding.

`trialone verify` compares a new recording with an earlier diagnosis, without a model call. It reports the outcome per finding. A quieter symptom does not count as repaired while the same finding remains.

```bash
trialone diagnose ./before.mcap --json
trialone verify <diagnosis.json> ./after-repair.mcap
```

| Per finding | Means |
| --- | --- |
| GONE | The finding is absent from the new recording. |
| STILL | The same finding is present again. A lower peak is still the same finding. |
| NEW | A finding the earlier diagnosis did not have. |

The verdict is pass (exit code 0), fail (1) or inconclusive (2). A new candidate that is not certain makes the verdict inconclusive, never a pass.

A pass means the supplied follow-up meets these checks. Use a fresh recording of the triggering task under comparable conditions. A short quiet interval or a different task is not evidence that an intermittent failure has been removed everywhere.

## Measure both the same way

Use the same `--healthy` reference and the same `--max-false-alarm` rate you diagnosed with. Otherwise a finding can appear or vanish because the bar moved, not because the machine changed.

## Crashes

A crash does not repeat inside one log. Pass a folder with the logs of several runs of the scenario that triggered it, one log per run; each counts as one repetition.

## From the website

On an issue, **Check repair on** lets you describe the applied change and request a follow-up on a robot. Its watcher must be connected and its recordings folder configured. Run the triggering task with your recorder active. The check waits up to 24 hours for evidence and reports missing setup or inconclusive results; you can cancel a waiting request.

Automatic deployment confirmation currently covers supported native Linux executables with a supplied build identity and observable scenario activity. Other deployment types may need manual evidence and remain unverified by this mechanism. The job does not deploy code, start a recorder or move the robot. See [Coding agents](https://trialone.dev/docs/coding-agents) for the connected workflow.

---

<!-- https://trialone.dev/docs/history -->
# Remembering earlier incidents

Keep the finding, applied change and follow-up together for the next investigation.

TrialONE 0.4.21 and later keep a local case history for named robots. It can show whether similar evidence appeared before, what your team reported changing and how the follow-up turned out. This helps avoid repeating a repair that already failed.

## Use a stable robot name

Pass the same `--machine` name for every diagnosis of this robot, or set `TRIALONE_MACHINE`. Different robots analysed on the same laptop should have different names.

```bash
trialone diagnose ./before.mcap --machine amr-01 --json ./before.json
```

## Record the change you actually made

After applying a change, record it against the finding. `repair` stores your description; it does not modify code or hardware. When a diagnosis has several findings, select the finding ID from its JSON.

```bash
trialone repair ./before.json --finding <finding-id> --change "Changed the subscriber QoS configuration" --project ./robot_ws
```

## Attach the follow-up

Use the repair ID printed by the previous command to link a fresh recording to this attempt. Keep the same healthy reference and false-alarm settings if you used them for the original diagnosis.

```bash
trialone verify ./before.json ./after.mcap --attempt <repair-id> --json ./verification.json
trialone cases --machine amr-01
```

## What the history establishes

The history preserves reported changes and passing, failing or inconclusive follow-ups. A repeated symptom is a lead for the next investigation, not proof of an identical cause. An applied change is your team's report; a checkout or commit alone is not independent deployment evidence.

This history is stored locally in `TRIALONE_HOME`, normally `~/.trialone`, and has no separate cloud sync. Related metadata can be included when a diagnosis is uploaded to your workspace. It is separate from model training and from the workspace issue list. See [Data and model processing](https://trialone.dev/docs/data).

---

<!-- https://trialone.dev/docs/access -->
# Access and team

Who can use TrialONE, and how a team works in one workspace.

## Pilot access

We onboard a few robotics teams at a time, and a founder approves each one by hand. [Request Pilot Access](https://trialone.dev/request-access) with your work email. You can sign in with Google, GitHub or email before the approval; until it arrives the app shows where your request stands.

## Keys

| Key | Starts with | For |
| --- | --- | --- |
| CLI key | `t1cli_` | A robot or laptop that runs TrialONE and posts runs. One per machine, under Settings, CLI keys. |
| Agent key | `t1mcp_` | A coding agent over MCP. It reads issues and reports repairs, and cannot post runs. |

The database keeps only a hash of each key, so a key is shown exactly once. A revoked key can no longer post runs, and the machine that used it stops running TrialONE at its next daily check.

## A team

A workspace is one account that several people work in. Invite people by email under Settings, Team. An invitation arrives by email, and when the address already has an account it also waits inside the app.

| Role | Can |
| --- | --- |
| Owner | Everything, including the workspace itself. |
| Admin | Invite and remove people, and see and revoke the keys of everyone in the workspace. |
| Member | Work on issues, assign them, and create their own keys. |

Issues can be assigned to a person, and every action (a claimed repair, a state change, an assignment) is kept with who did it.

---

<!-- https://trialone.dev/docs/data -->
# Data and model processing

Choose workspace uploads separately from the model used for an investigation.

## Two separate choices

Detection runs where you start TrialONE. Model interpretation sends the context needed for an investigation to the configured model endpoint. Workspace upload sends the report and selected history to your TrialONE account. Turning off one does not turn off the other.

| Choice | What it controls |
| --- | --- |
| `--no-explain` on diagnose | Skips model interpretation for that diagnosis. |
| `--no-push` | Skips posting the run to the TrialONE workspace. Model calls can still occur. |
| A model endpoint on your network | Keeps model requests at the address your team configured. Workspace uploads remain a separate choice. |
| `--no-camera` on watch | Stops camera frames being used for live investigations on that run. |

## What reaches your workspace

By default a signed-in run sends the finding and recipe, cited log and source excerpts, channel statistics and selected histories. With `--project`, it can also send commit metadata and the contents of supported parameter, launch and URDF files. The original recording is uploaded only when enabled for the machine or explicitly requested.

## History

| Level | What leaves the machine |
| --- | --- |
| off | The recipe and statistics per channel. |
| incident | Also the minute around each finding: 30 seconds before to 30 seconds after, at 10 points per second. |
| full (default) | Also a trend of every channel and a 10 Hz history of every channel that moved. |

## Machine state

| Level | What leaves the machine |
| --- | --- |
| off | No machine-state attachment. A recipe can still contain cited source or log excerpts. |
| code | Commit, branch, recent commit metadata and hashes of supported configuration files. No file contents in the state attachment. |
| full (default) | Also the parameter, launch and URDF files next to it, each content sent once per hash. |

## The recording itself

Off until you switch it on for a machine, or pass `--upload-raw`. A recording can hold more than numbers (camera frames, point clouds, anything the robot published), and it can be large, so the switch names both.

## Where to change it

Set history, machine state and raw recording upload per machine under Settings, Robots, or per run with the corresponding CLI flags. A flag takes precedence over the stored setting. These settings control workspace uploads; they do not restrict which context the configured model can read.

## Model context

An investigation can send measured values, logs, relevant source and configuration excerpts, and tool results to its model endpoint. The managed interpretation service currently uses external model providers. A model key of your own sends requests to that provider. To use an endpoint on your own network, see [Model settings](https://trialone.dev/docs/models).

## Live camera frames

Camera context is enabled by default in the current pilot watcher for supported topics. It keeps a limited recent buffer on the robot and can send selected frames to the configured model during an investigation. Frames are not separately stored or uploaded with the run by this camera feature. They may show people or your workspace. Disable them under Settings, Robots or with `--no-camera` when that context is not appropriate for your pilot. A separately enabled raw recording upload can still contain its own images.

## How long it is kept

Uploaded histories are deleted after your workspace retention period, 90 days by default. Runs remain until deleted. Under Settings, Profile, **Your data** lets you export workspace records or request account deletion. Owners and admins can delete a run from its page together with its stored files. Contact hello@trialone.info if you need help.

See the [Privacy notice](https://trialone.dev/datenschutz) for service providers and contact details. For a pilot with specific data requirements, agree the processing setup with us before connecting the robot.

---

<!-- https://trialone.dev/docs/models -->
# Model settings

Use managed interpretation, your own provider key or a model endpoint on your network.

## Managed interpretation

After signing in, the CLI can use your TrialONE plan for model interpretation. Availability depends on your account and incident allowance. The terminal names the processing mode and reports when interpretation cannot run. Detection still runs without a model.

## Bring a provider key

Run `trialone` to open the interactive CLI, then use `/key` to configure a supported provider and `/model` to choose its model. The key is saved on this machine. Requests use that provider and its billing, with the context described in [Data and model processing](https://trialone.dev/docs/data).

## Use your own endpoint

TrialONE can send model requests to an endpoint compatible with the chat-completions protocol. Your team runs the server and chooses a model that supports the tools needed for investigation. Set these values in the CLI environment or `~/.trialone/env`:

```
TRIALONE_LLM_PROVIDER=lokal
TRIALONE_LLM_BASE_URL=http://localhost:8000/v1
TRIALONE_LLM_MODEL=<model-served-by-your-endpoint>
```

If your server requires authentication, also set `TRIALONE_LLM_API_KEY`. Replace the example address and model with your actual server. Explicitly choosing `lokal` keeps model requests on that route; a slash in your model's name does not select an external provider.

The endpoint controls where model inference happens. Use `--no-push` separately when you want to skip the workspace upload. The CLI still needs approved access and periodically checks it; this setup is not a complete offline deployment.

## Skip interpretation for one diagnosis

```bash
trialone diagnose ./recording.mcap --no-explain --no-push
```

This runs detection and writes the report locally, without model interpretation or posting the run to the workspace. It does not disable account access checks.

---

<!-- https://trialone.dev/docs/for-agents -->
# For agents

This documentation is written to be read by a model as well as a person.

## Markdown copies

Every page has **Copy page**, which copies it as Markdown, ready to paste into an agent's context.

## llms.txt

[llms.txt](https://trialone.dev/llms.txt) is the plain-text index of this documentation for language models, followed by the full text of every page. It is served at `https://trialone.dev/llms.txt`.

## A working pattern

1. `list_issues`, then `get_issue` for the one to fix. Without a fingerprint, `get_issue` returns the newest open issue.
2. Change the files the recipe names. If the issue is routed as physical, stop and tell the user who has to go to the robot.
3. `claim_repair` with the fingerprint, what changed, and the commit or pull request link. This automatically queues a check on each affected robot; supply `machines` for a staged rollout. Read any setup blockers in the response.
4. For a native Linux executable repair, supply `verification_target`: the built executable SHA-256 and measurable scenario activity. It can be included in `claim_repair` or added to the pending check with `request_verification`. A Git commit alone is not deployment evidence. Python, plugin/library and hardware changes need additional deployment adapters and remain unverified by this mechanism.
5. Deploy the change and record the triggering scenario in a ROS2 bag or MCAP with wall-clock timestamps. With TrialONE connected and the recording folder configured, it observes the running executable and checks completed recordings for up to 24 hours. Missing runtime or scenario evidence cannot confirm the repair. No manual closure is needed.
6. `check_repair` returns progress per robot and the measured result, including remaining failures. Continue the investigation in the agent. Use `request_verification` to retry after resolving a blocker. MCP does not automatically start an idle coding agent.

## From the command line

`trialone diagnose <recording> --json` writes one recipe per finding with fixed fields, for an agent that works without MCP.