raytrace-cli 0.11.1__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- raytrace/__init__.py +1 -0
- raytrace/__main__.py +33 -0
- raytrace/app/LICENSE +21 -0
- raytrace/app/README.md +599 -0
- raytrace/app/bin/raytrace.mjs +297 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-BwCSEQnW.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-Dr3UlScf.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-CUSSCpQX.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff +0 -0
- raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-BSMlKf0J.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-CEL4l2ZJ.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Ael50iVv.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Bq9vWWag.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-CTOM6hUh.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-fLZuRloM.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-DMdlQ8Kv.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-xuaO2J-f.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BIfNGwUT.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BqneJy0T.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-9HEixskS.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-V-xxqcpd.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-CvHOgSBP.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-DMJ8VG8y.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-CB9ihrfo.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-DSY6xOcd.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-BgSNZQsw.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-DWFSQ4vo.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-BmRBH3aV.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-D3D2R8hC.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CAhNIIs5.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CZ70TYgx.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-D38SheWl.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-DmB0ttJJ.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-BulugwFq.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-DDuiU_S-.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-C8zxqsMH.woff +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-DZ4AoWbu.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-D2EvbN8M.woff2 +0 -0
- raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-iLQfcSjf.woff +0 -0
- raytrace/app/dist/dashboard/assets/index-DepcI8Fi.js +38 -0
- raytrace/app/dist/dashboard/assets/index-H97VLD5l.css +1 -0
- raytrace/app/dist/dashboard/favicon.svg +6 -0
- raytrace/app/dist/dashboard/index.html +15 -0
- raytrace/app/package.json +48 -0
- raytrace/app/proxy/agent-intent-schema.test.mjs +142 -0
- raytrace/app/proxy/call-assessment.mjs +385 -0
- raytrace/app/proxy/call-assessment.test.mjs +167 -0
- raytrace/app/proxy/call-category.mjs +461 -0
- raytrace/app/proxy/capture-health.mjs +30 -0
- raytrace/app/proxy/capture-health.test.mjs +44 -0
- raytrace/app/proxy/capture.mjs +38 -0
- raytrace/app/proxy/capture.test.mjs +49 -0
- raytrace/app/proxy/claude-code-adapter.mjs +301 -0
- raytrace/app/proxy/claude-code-hook.mjs +22 -0
- raytrace/app/proxy/codex-config.mjs +36 -0
- raytrace/app/proxy/codex.mjs +14 -0
- raytrace/app/proxy/evidence-schema.test.mjs +240 -0
- raytrace/app/proxy/evidence-store.mjs +993 -0
- raytrace/app/proxy/evidence-store.test.mjs +301 -0
- raytrace/app/proxy/exec-narrative.mjs +625 -0
- raytrace/app/proxy/exec-narrative.test.mjs +262 -0
- raytrace/app/proxy/execution-correlation.mjs +185 -0
- raytrace/app/proxy/execution-correlation.test.mjs +146 -0
- raytrace/app/proxy/execution-runner.mjs +89 -0
- raytrace/app/proxy/execution-runner.test.mjs +38 -0
- raytrace/app/proxy/experiment-engine.mjs +195 -0
- raytrace/app/proxy/experiment-engine.test.mjs +93 -0
- raytrace/app/proxy/explanations.mjs +36 -0
- raytrace/app/proxy/explanations.test.mjs +20 -0
- raytrace/app/proxy/failure-signature.mjs +56 -0
- raytrace/app/proxy/gvisor-forwarder.mjs +493 -0
- raytrace/app/proxy/gvisor-forwarder.test.mjs +433 -0
- raytrace/app/proxy/init-evidence-db.mjs +227 -0
- raytrace/app/proxy/local-sandboxes.mjs +94 -0
- raytrace/app/proxy/local-token.mjs +30 -0
- raytrace/app/proxy/playground-recovery.test.mjs +130 -0
- raytrace/app/proxy/playground.mjs +439 -0
- raytrace/app/proxy/prompt-context.mjs +278 -0
- raytrace/app/proxy/prompt-traces.mjs +40 -0
- raytrace/app/proxy/prompt-traces.test.mjs +32 -0
- raytrace/app/proxy/providers.mjs +65 -0
- raytrace/app/proxy/providers.test.mjs +76 -0
- raytrace/app/proxy/proxy.integration.test.mjs +135 -0
- raytrace/app/proxy/raytace-proxy.mjs +941 -0
- raytrace/app/proxy/request-metrics.mjs +13 -0
- raytrace/app/proxy/request-metrics.test.mjs +19 -0
- raytrace/app/proxy/request-policy.mjs +45 -0
- raytrace/app/proxy/request-policy.test.mjs +47 -0
- raytrace/app/proxy/run-recap.mjs +139 -0
- raytrace/app/proxy/runtime-attribution.mjs +110 -0
- raytrace/app/proxy/sandbox-bridge.mjs +49 -0
- raytrace/app/proxy/schema/EVIDENCE_DATABASE.md +276 -0
- raytrace/app/proxy/schema/agent_intent.sql +101 -0
- raytrace/app/proxy/schema/auxiliary.sql +90 -0
- raytrace/app/proxy/schema/capture_health.sql +14 -0
- raytrace/app/proxy/schema/classification.sql +89 -0
- raytrace/app/proxy/schema/file_context.sql +53 -0
- raytrace/app/proxy/schema/runtime_evidence.sql +201 -0
- raytrace/app/proxy/schema/search.sql +66 -0
- raytrace/app/proxy/schema/shared_storage.sql +21 -0
- raytrace/app/proxy/search.mjs +418 -0
- raytrace/app/proxy/search.test.mjs +161 -0
- raytrace/app/proxy/smoke.test.mjs +93 -0
- raytrace/app/proxy/step-attribution.mjs +380 -0
- raytrace/app/proxy/step-lab.mjs +78 -0
- raytrace/app/proxy/step-lab.test.mjs +38 -0
- raytrace/app/proxy/summaries.mjs +151 -0
- raytrace/app/proxy/summaries.test.mjs +69 -0
- raytrace/app/proxy/tool-metadata.mjs +111 -0
- raytrace/app/proxy/tool-metadata.test.mjs +38 -0
- raytrace/app/proxy/trace-view.mjs +324 -0
- raytrace/app/proxy/trace-view.test.mjs +92 -0
- raytrace/app/proxy/typesafe.mjs +63 -0
- raytrace/app/proxy/typesafe.test.mjs +39 -0
- raytrace/app/src/agents.mjs +7 -0
- raytrace/app/src/api.mjs +57 -0
- raytrace/app/src/auth.mjs +205 -0
- raytrace/app/src/beta.mjs +96 -0
- raytrace/app/src/claude-code.mjs +93 -0
- raytrace/app/src/commands.mjs +285 -0
- raytrace/app/src/config.mjs +49 -0
- raytrace/app/src/export.mjs +200 -0
- raytrace/app/src/lima.mjs +176 -0
- raytrace/app/src/local-sandbox.mjs +358 -0
- raytrace/app/src/mcp.mjs +688 -0
- raytrace/app/src/paths.mjs +33 -0
- raytrace/app/src/prompt.mjs +42 -0
- raytrace/app/src/proxy-process.mjs +143 -0
- raytrace/app/src/sandbox.mjs +306 -0
- raytrace/app/src/share.mjs +86 -0
- raytrace/app/src/terminal.mjs +68 -0
- raytrace/app/src/upload.mjs +198 -0
- raytrace/app/worker/sandbox/Dockerfile +8 -0
- raytrace/app/worker/sandbox/SYSCALL_CATALOG.md +197 -0
- raytrace/app/worker/sandbox/claude-hook.mjs +364 -0
- raytrace/app/worker/sandbox/collector.py +405 -0
- raytrace/app/worker/sandbox/dns_forwarder.py +255 -0
- raytrace/app/worker/sandbox/engine.py +940 -0
- raytrace/app/worker/sandbox/file_scan.py +491 -0
- raytrace/app/worker/sandbox/lima.yaml +29 -0
- raytrace/app/worker/sandbox/network.py +90 -0
- raytrace/app/worker/sandbox/projects.py +702 -0
- raytrace/app/worker/sandbox/setup.py +159 -0
- raytrace/app/worker/sandbox/syscall_catalog.sql +985 -0
- raytrace/app/worker/sandbox/transcript-delivery.test.mjs +153 -0
- raytrace/app/worker/sandbox/viewer.py +195 -0
- raytrace/node/LICENSE +2946 -0
- raytrace/node/node.exe +4 -0
- raytrace_cli-0.11.1.dist-info/LICENSE +21 -0
- raytrace_cli-0.11.1.dist-info/METADATA +42 -0
- raytrace_cli-0.11.1.dist-info/RECORD +165 -0
- raytrace_cli-0.11.1.dist-info/WHEEL +4 -0
- raytrace_cli-0.11.1.dist-info/entry_points.txt +2 -0
raytrace/__init__.py
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
"""RayTrace CLI, packaged for pip: the npm package @raytrace-cli/cli with its own Node.js."""
|
raytrace/__main__.py
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
# The `raytrace` command from pip. The wheel carries the npm package in app/
|
|
2
|
+
# and an official Node.js build in node/, so this only hands over to them: on
|
|
3
|
+
# macOS and Linux by replacing this process (the Claude Code hook runs
|
|
4
|
+
# `raytrace hook claude-code` on every tool call, and stdin, stdout and
|
|
5
|
+
# signals then reach Node untouched), on Windows as a child whose exit code
|
|
6
|
+
# becomes ours.
|
|
7
|
+
import os
|
|
8
|
+
import stat
|
|
9
|
+
import subprocess
|
|
10
|
+
import sys
|
|
11
|
+
|
|
12
|
+
HERE = os.path.dirname(os.path.abspath(__file__))
|
|
13
|
+
NODE = os.path.join(HERE, 'node', 'node.exe' if os.name == 'nt' else 'node')
|
|
14
|
+
CLI = os.path.join(HERE, 'app', 'bin', 'raytrace.mjs')
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def main():
|
|
18
|
+
if not os.path.isfile(NODE):
|
|
19
|
+
sys.exit(f'raytrace: the bundled Node.js is missing ({NODE}); reinstall with pip install --force-reinstall raytrace-cli')
|
|
20
|
+
if os.name != 'nt' and not os.access(NODE, os.X_OK):
|
|
21
|
+
# Some installers drop the executable bit that the wheel records.
|
|
22
|
+
os.chmod(NODE, os.stat(NODE).st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
|
|
23
|
+
args = [NODE, CLI, *sys.argv[1:]]
|
|
24
|
+
if os.name == 'nt':
|
|
25
|
+
try:
|
|
26
|
+
sys.exit(subprocess.call(args))
|
|
27
|
+
except KeyboardInterrupt:
|
|
28
|
+
sys.exit(130)
|
|
29
|
+
os.execv(NODE, args)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
if __name__ == '__main__':
|
|
33
|
+
main()
|
raytrace/app/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 RayTrace contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
raytrace/app/README.md
ADDED
|
@@ -0,0 +1,599 @@
|
|
|
1
|
+
# RayTrace
|
|
2
|
+
|
|
3
|
+
**See what your coding agent actually did.**
|
|
4
|
+
|
|
5
|
+
[npm package](https://www.npmjs.com/package/@raytrace-cli/cli) ·
|
|
6
|
+
[Set up in your editor (MCP)](#set-up-in-your-editor-mcp) ·
|
|
7
|
+
[Local sandboxes](#local-sandboxes) ·
|
|
8
|
+
[Cloud sandboxes](#cloud-sandboxes) ·
|
|
9
|
+
[What you can do](#what-you-can-do-with-a-recorded-session) ·
|
|
10
|
+
[Commands](#commands) ·
|
|
11
|
+
[Report an issue](https://github.com/Godcreatebugs/raytrace-cli/issues)
|
|
12
|
+
|
|
13
|
+
Your agent finished the task. Which files did it read? What commands did it
|
|
14
|
+
run? Where did the tokens and money go?
|
|
15
|
+
|
|
16
|
+
RayTrace runs Claude Code or Codex in a **sandbox**, an isolated copy of your
|
|
17
|
+
project, and records everything that happens there: your prompts, the agent's
|
|
18
|
+
answers and tool calls, and every command that actually ran, with its exit code
|
|
19
|
+
and network connections. You explore it all in a dashboard.
|
|
20
|
+
|
|
21
|
+

|
|
22
|
+
|
|
23
|
+
*One real coding task: 50 model round trips, 58 tool calls, and a command-by-command record.*
|
|
24
|
+
|
|
25
|
+
## Pick how you want to use it
|
|
26
|
+
|
|
27
|
+
| | Where it runs | Account | Best for |
|
|
28
|
+
|---|---|---|---|
|
|
29
|
+
| **[From your editor (MCP)](#set-up-in-your-editor-mcp)** | local or cloud, you choose per sandbox | only for cloud | asking your agent "put this repo in a sandbox and open it" |
|
|
30
|
+
| **[Local sandbox](#local-sandboxes)** | a Linux VM on your machine | none | keeping your code on your machine; free and open source |
|
|
31
|
+
| **[Cloud sandbox](#cloud-sandboxes)** | RayTrace's servers | yes | sharing sessions with your team at [app.raytracer.si](https://app.raytracer.si) |
|
|
32
|
+
|
|
33
|
+
All three need **Node.js 22.13 or newer** (`node --version`) on macOS or Linux,
|
|
34
|
+
or none at all from pip: `pip install raytrace-cli` (or `uv tool install raytrace-cli`)
|
|
35
|
+
installs the same CLI with its own Node.js. Where this page says
|
|
36
|
+
`npx -y @raytrace-cli/cli@latest`, use `uvx --from raytrace-cli raytrace` instead.
|
|
37
|
+
Windows is experimental.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Set up in your editor (MCP)
|
|
42
|
+
|
|
43
|
+
`raytrace mcp` is an [MCP](https://modelcontextprotocol.io) server. Add it to
|
|
44
|
+
your editor once, and your agent can create, open, stop and destroy sandboxes
|
|
45
|
+
for you. There is nothing to install first: `npx` downloads the CLI on first use.
|
|
46
|
+
|
|
47
|
+
### 1. Add the server
|
|
48
|
+
|
|
49
|
+
**Claude Code.** One command, then restart Claude Code. `--scope user` makes it
|
|
50
|
+
available in every project:
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
claude mcp add --scope user raytrace -- npx -y @raytrace-cli/cli@latest mcp
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Check it with `claude mcp list`, which should show `raytrace` as connected.
|
|
57
|
+
|
|
58
|
+
**Cursor.** Add to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
|
|
59
|
+
|
|
60
|
+
```json
|
|
61
|
+
{
|
|
62
|
+
"mcpServers": {
|
|
63
|
+
"raytrace": { "command": "npx", "args": ["-y", "@raytrace-cli/cli@latest", "mcp"] }
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
**VS Code.** Add to `.vscode/mcp.json` in the project, or run **MCP: Open User
|
|
69
|
+
Configuration** from the command palette for every project:
|
|
70
|
+
|
|
71
|
+
```json
|
|
72
|
+
{
|
|
73
|
+
"servers": {
|
|
74
|
+
"raytrace": { "command": "npx", "args": ["-y", "@raytrace-cli/cli@latest", "mcp"] }
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
**Codex.** `codex mcp add raytrace -- npx -y @raytrace-cli/cli@latest mcp`
|
|
80
|
+
|
|
81
|
+
**Any other MCP client.** Run the command `npx` with the arguments
|
|
82
|
+
`-y @raytrace-cli/cli@latest mcp`, over stdio. Most clients use the same
|
|
83
|
+
`mcpServers` JSON as Cursor.
|
|
84
|
+
|
|
85
|
+
> Already have the CLI installed globally? You can use `raytrace mcp` as the
|
|
86
|
+
> command instead of `npx`.
|
|
87
|
+
|
|
88
|
+
### 2. Ask for a sandbox
|
|
89
|
+
|
|
90
|
+
Open a Git project in your editor and ask your agent in plain words:
|
|
91
|
+
|
|
92
|
+
| You say | What happens |
|
|
93
|
+
|---|---|
|
|
94
|
+
| "Create a local sandbox and connect this repo" | a sandbox on your machine, then a terminal opens with Claude Code running in it |
|
|
95
|
+
| "Put this project in a cloud sandbox" | uploads the repo to RayTrace's cloud, then opens a terminal with Claude Code in it |
|
|
96
|
+
| "Open my sandbox with Codex" | a terminal connected to an existing sandbox, with Codex running in it |
|
|
97
|
+
| "List my sandboxes" / "Stop demo-box" / "Destroy it" | manages them; the agent asks you before it destroys anything |
|
|
98
|
+
| "Run `npm test` in the sandbox" | runs a command in a cloud sandbox and reports the result back in the chat |
|
|
99
|
+
|
|
100
|
+
**The first time:**
|
|
101
|
+
|
|
102
|
+
- **Cloud sandboxes** need a RayTrace sign-in. The agent shows you a short code
|
|
103
|
+
and opens a browser page. Approve it there (or create your account), and the
|
|
104
|
+
agent carries on. Local sandboxes need no account.
|
|
105
|
+
- **The first local sandbox** sets up a Linux VM, which takes a few minutes. If
|
|
106
|
+
[Lima](https://lima-vm.io) is missing, the agent asks before downloading it.
|
|
107
|
+
See [what you need](#what-you-need).
|
|
108
|
+
- **In each new sandbox**, Claude Code or Codex asks you to sign in to your
|
|
109
|
+
Anthropic or OpenAI account, as it would on your machine.
|
|
110
|
+
- **On macOS**, the first time a terminal is opened for you, macOS asks whether
|
|
111
|
+
your editor may control your terminal app. Allow it.
|
|
112
|
+
|
|
113
|
+
### 3. Work in the sandbox
|
|
114
|
+
|
|
115
|
+
The terminal opens where you work: a new tmux window if you're in tmux, a new
|
|
116
|
+
iTerm window or WezTerm tab, otherwise a new Terminal window on macOS (VS Code's
|
|
117
|
+
built-in terminal can't be opened from outside), your desktop's terminal on
|
|
118
|
+
Linux, or Windows Terminal. If none can be opened, the agent gives you the
|
|
119
|
+
command to paste instead, such as `raytrace connect demo-box --claude`.
|
|
120
|
+
|
|
121
|
+
Inside, the agent runs **without approval prompts**. The sandbox is what keeps
|
|
122
|
+
it contained, so there's no need to approve every command, and everything it
|
|
123
|
+
does is recorded. See [Working in a sandbox](#working-in-a-sandbox).
|
|
124
|
+
|
|
125
|
+
### MCP tools reference
|
|
126
|
+
|
|
127
|
+
| Tool | What it does |
|
|
128
|
+
|---|---|
|
|
129
|
+
| `login` | signs in to RayTrace (cloud only): shows a code to approve in the browser |
|
|
130
|
+
| `create_sandbox` | copies the open Git project into a new sandbox. `local: true` for one on your machine, `agent: "codex"` to open it with Codex, `connect: false` to skip opening a terminal |
|
|
131
|
+
| `connect_sandbox` | opens a terminal in an existing sandbox with Claude Code (default), Codex (`agent: "codex"`) or a plain shell (`agent: "none"`); starts it first if it's stopped |
|
|
132
|
+
| `list_sandboxes`, `sandbox_status` | your local and cloud sandboxes, and one sandbox's details or creation progress |
|
|
133
|
+
| `start_sandbox`, `stop_sandbox` | stopping keeps the files |
|
|
134
|
+
| `destroy_sandbox` | deletes a sandbox. Cloud: its traces go too, unless `keep_traces` (paid plans). Local: its logs are archived, unless `delete_logs` |
|
|
135
|
+
| `run_command`, `get_command_result`, `cancel_command` | run shell commands in a cloud sandbox from the chat: up to 4 at once, 120 s by default and at most 30 minutes, with the real exit code and output |
|
|
136
|
+
|
|
137
|
+
Local sandboxes are named by their name and cloud ones by their id (`rtp-…`).
|
|
138
|
+
Whatever a command prints is treated as data from your project, never as
|
|
139
|
+
instructions to the agent.
|
|
140
|
+
|
|
141
|
+
---
|
|
142
|
+
|
|
143
|
+
## Local sandboxes
|
|
144
|
+
|
|
145
|
+
Run the sandbox on your own machine. Your project is copied into it, and nothing
|
|
146
|
+
is uploaded. It is open source and needs no RayTrace account.
|
|
147
|
+
|
|
148
|
+
### What you need
|
|
149
|
+
|
|
150
|
+
| | Requirement |
|
|
151
|
+
|---|---|
|
|
152
|
+
| **macOS 13.5 or later** | Nothing to install. RayTrace uses your [Lima](https://lima-vm.io) 2.0+ if you have it, or offers to download Lima into `~/.raytrace/lima` (no admin rights; checked against a pinned checksum) |
|
|
153
|
+
| **Older macOS** | QEMU too: `brew install qemu` |
|
|
154
|
+
| **Linux** | Lima, QEMU, and access to `/dev/kvm` (`sudo usermod -aG kvm $USER`, then log out and in) |
|
|
155
|
+
| **Windows** | experimental; RayTrace doesn't download Lima there |
|
|
156
|
+
| **Disk and memory** | the first setup downloads about 1 GB; the VM uses 4 GiB of memory while it runs |
|
|
157
|
+
|
|
158
|
+
`raytrace doctor` checks all of this and says how to fix anything missing.
|
|
159
|
+
|
|
160
|
+
### Set it up
|
|
161
|
+
|
|
162
|
+
```sh
|
|
163
|
+
npm install -g @raytrace-cli/cli
|
|
164
|
+
|
|
165
|
+
cd your-project # any Git repository
|
|
166
|
+
raytrace sandbox create --local # first time: sets up the VM, a few minutes
|
|
167
|
+
raytrace connect your-project --claude # a terminal in it, with Claude Code running
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
- The sandbox is named after the folder. Use `--name my-box` to choose the name.
|
|
171
|
+
- Use `--codex` instead of `--claude` to start Codex, or leave both off for a
|
|
172
|
+
plain shell where you run `claude` or `codex` yourself.
|
|
173
|
+
- `connect` prints a link to the dashboard showing only this sandbox's prompts.
|
|
174
|
+
`raytrace open` opens the full dashboard.
|
|
175
|
+
|
|
176
|
+
Or skip the commands and ask your editor's agent:
|
|
177
|
+
[set up MCP](#set-up-in-your-editor-mcp), then say "create a local sandbox and
|
|
178
|
+
connect this repo".
|
|
179
|
+
|
|
180
|
+
### Day to day
|
|
181
|
+
|
|
182
|
+
```sh
|
|
183
|
+
raytrace sandbox list --local # your local sandboxes
|
|
184
|
+
raytrace connect my-box --claude # back in; the sandbox keeps running when you leave
|
|
185
|
+
raytrace sandbox stop my-box # stop it; its files are kept
|
|
186
|
+
raytrace sandbox start my-box
|
|
187
|
+
raytrace sandbox destroy my-box # asks whether to delete its captured logs too
|
|
188
|
+
limactl stop raytrace # stop the whole VM to free its 4 GiB of memory
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
When you destroy a sandbox, you're asked what to do with its logs:
|
|
192
|
+
|
|
193
|
+
- **Yes** deletes them everywhere, the dashboard and Playground forks included.
|
|
194
|
+
- **No** moves them to `~/.raytrace/archive/<name>-<time>/`: the agent
|
|
195
|
+
transcripts, the recorded commands, files and connections as JSON lines, and
|
|
196
|
+
any forks. Its sessions stay in your dashboard.
|
|
197
|
+
|
|
198
|
+
`--delete-logs` or `--keep-logs` answers without asking. To keep the logs in the
|
|
199
|
+
cloud, `raytrace upload logs --sandbox my-box` sends them to
|
|
200
|
+
[app.raytracer.si](https://app.raytracer.si) (needs a sign-in).
|
|
201
|
+
|
|
202
|
+
### How it works
|
|
203
|
+
|
|
204
|
+
- **Isolation:** each sandbox is a Docker container under
|
|
205
|
+
[gVisor](https://gvisor.dev), inside a Linux VM made with
|
|
206
|
+
[Lima](https://lima-vm.io). It can't see your machine's files or private
|
|
207
|
+
networks. A copy of your project goes in (picked the same way as for
|
|
208
|
+
[cloud uploads](#what-is-uploaded)); your own files are never changed.
|
|
209
|
+
- **Resources:** each sandbox gets 2 GB of memory, 2 CPUs, 256 processes and a
|
|
210
|
+
512 MB `/tmp`. All sandboxes share the VM's 30 GiB disk.
|
|
211
|
+
- **Recording:** a collector outside the sandbox, which the agent can't turn
|
|
212
|
+
off, records every command, file change and network connection. Claude Code's
|
|
213
|
+
prompts, answers and tool calls go to your local dashboard as well. Nothing
|
|
214
|
+
leaves your machine.
|
|
215
|
+
- **Changes:** the project is snapshotted after every edit, so **Changes** in
|
|
216
|
+
the dashboard shows what each prompt left different, with a patch to take home.
|
|
217
|
+
- **Playground:** rerun a session from any step with something changed (a tool
|
|
218
|
+
result, a file, the model or the message) and compare the outcomes,
|
|
219
|
+
optionally with a check such as `npm test`. Each rerun is a fork, a sandbox
|
|
220
|
+
of its own started from the snapshot just before that step.
|
|
221
|
+
|
|
222
|
+
---
|
|
223
|
+
|
|
224
|
+
## Cloud sandboxes
|
|
225
|
+
|
|
226
|
+
A cloud sandbox is the same isolated copy of your project, on RayTrace's
|
|
227
|
+
servers, with sessions recorded for your organization at
|
|
228
|
+
**[app.raytracer.si](https://app.raytracer.si)**. This is a preview.
|
|
229
|
+
|
|
230
|
+
```sh
|
|
231
|
+
npm install -g @raytrace-cli/cli
|
|
232
|
+
raytrace auth login # opens your browser: sign in, or create your account
|
|
233
|
+
cd your-project # any Git repository
|
|
234
|
+
raytrace sandbox create # uploads it and prints the sandbox id
|
|
235
|
+
raytrace connect <sandbox-id> --claude # a terminal in it, with Claude Code running
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
`auth login` prints a short code and opens the sign-in page; approve it there.
|
|
239
|
+
If you skip it, `sandbox create` and `connect` ask you to sign in first. With
|
|
240
|
+
one sandbox, `connect` needs no id. You can also create a sandbox in the web
|
|
241
|
+
dashboard by dropping a project folder on the **Sandboxes** page.
|
|
242
|
+
|
|
243
|
+
### What is uploaded
|
|
244
|
+
|
|
245
|
+
The files Git would track (including new files it doesn't ignore), **without**
|
|
246
|
+
`.git`, dependencies such as `node_modules`, build output, `.env*` files, private
|
|
247
|
+
keys (`.pem`, `.key`, `.p12`, `.pfx`) and common credential files (`.npmrc`,
|
|
248
|
+
`.netrc`, `id_rsa`, …). Check for secrets inside other files before you upload.
|
|
249
|
+
|
|
250
|
+
### Limits
|
|
251
|
+
|
|
252
|
+
- **Project size:** up to 200 MiB and 20,000 files, each file up to 25 MiB
|
|
253
|
+
(100 MiB once packed). A project over a limit is refused, with the files
|
|
254
|
+
named, and nothing is uploaded; add those files to `.gitignore`.
|
|
255
|
+
- **Sandboxes at a time:** Beta 1, Individual 5, Team & Enterprise 20.
|
|
256
|
+
Destroyed ones don't count.
|
|
257
|
+
- **Each sandbox:** 2 GB of memory, 2 CPUs, 256 processes, a 512 MB `/tmp`.
|
|
258
|
+
|
|
259
|
+
### When you are done
|
|
260
|
+
|
|
261
|
+
`raytrace sandbox stop` keeps the files. `raytrace sandbox destroy` deletes them
|
|
262
|
+
and any sign-in made inside, along with the recorded traces. To keep the traces,
|
|
263
|
+
use `--keep-traces` (paid plans).
|
|
264
|
+
|
|
265
|
+
---
|
|
266
|
+
|
|
267
|
+
## Working in a sandbox
|
|
268
|
+
|
|
269
|
+
- **Claude Code and Codex are preinstalled** in every sandbox, local and cloud.
|
|
270
|
+
- **No approval prompts.** `--claude` starts Claude Code with
|
|
271
|
+
`--dangerously-skip-permissions`, and `--codex` starts Codex with
|
|
272
|
+
`--dangerously-bypass-approvals-and-sandbox`. The sandbox's own settings, which
|
|
273
|
+
the agent can't change, make this the default too, so typing `claude` or
|
|
274
|
+
`codex` yourself works the same way. The sandbox is what keeps the agent
|
|
275
|
+
contained, and every command is recorded.
|
|
276
|
+
- **Restricted files stay locked.** Files a project's owner restricts in the
|
|
277
|
+
dashboard (**Initial scan**) can't be changed by the agent, whatever it tries.
|
|
278
|
+
- **Signing in:** sign in to Claude Code or Codex inside the sandbox, as you
|
|
279
|
+
would on your machine. The sign-in stays in that sandbox until you destroy it.
|
|
280
|
+
- **Leaving:** exiting the agent drops you into the sandbox's shell, and exiting
|
|
281
|
+
that leaves the sandbox running. `raytrace connect` takes you back.
|
|
282
|
+
|
|
283
|
+
In local sandboxes, Codex's prompts don't reach the dashboard's **Prompts** page
|
|
284
|
+
yet. Its commands, file changes and network connections are recorded.
|
|
285
|
+
|
|
286
|
+
---
|
|
287
|
+
|
|
288
|
+
## What you can do with a recorded session
|
|
289
|
+
|
|
290
|
+
Cloud sessions are at [app.raytracer.si](https://app.raytracer.si), and
|
|
291
|
+
`raytrace open` opens the same pages for your local sandboxes. Every page is
|
|
292
|
+
about one prompt, and they link to each other, so you can go from "what did I
|
|
293
|
+
ask" to "what actually ran" to "what if it had gone differently" in a couple of
|
|
294
|
+
clicks. The screenshots below are from the cloud dashboard, with a session in
|
|
295
|
+
the `raytrace-demo-shop` sandbox.
|
|
296
|
+
|
|
297
|
+
### Prompts: what you asked, and what came back
|
|
298
|
+
|
|
299
|
+

|
|
300
|
+
|
|
301
|
+
Every prompt you gave the agent, newest first, with an activity calendar on
|
|
302
|
+
top. Each row shows where it ran (Mac, local sandbox or cloud sandbox), the
|
|
303
|
+
model, how many tool calls it took and what it cost. Open one to read the
|
|
304
|
+
answer and a short recap of the run.
|
|
305
|
+
|
|
306
|
+

|
|
307
|
+
|
|
308
|
+
- **Find a session again:** click a day in the calendar, or add
|
|
309
|
+
`?box=<sandbox id>` to see a single sandbox's prompts.
|
|
310
|
+
- **Spot the expensive ones:** the cost and tool-call count are on every row.
|
|
311
|
+
|
|
312
|
+
### Tool calls: how the agent got there
|
|
313
|
+
|
|
314
|
+
<!-- screenshot: the one at the top of this README (docs/images/tool-calls.jpg) -->
|
|
315
|
+
|
|
316
|
+
The path from your prompt to the answer: one divider for each round trip to the
|
|
317
|
+
model, one row for each tool call it proposed, with the command and what the
|
|
318
|
+
agent says came back, plus tokens, time and cost at each step.
|
|
319
|
+
|
|
320
|
+
- **Follow its reasoning step by step,** and see where it went in circles.
|
|
321
|
+
- **See where the tokens went:** which steps were the expensive ones.
|
|
322
|
+
|
|
323
|
+
### Sandbox evidence: what actually ran
|
|
324
|
+
|
|
325
|
+

|
|
326
|
+
|
|
327
|
+
What the agent *says* it ran is in Tool calls. This page is what the sandbox
|
|
328
|
+
itself saw, recorded from outside the agent where it can't be turned off or
|
|
329
|
+
edited. You get every process in time order, with its real exit code, the files
|
|
330
|
+
it read or changed, where it connected and what it installed. Each process is
|
|
331
|
+
tied to the tool call that started it, and anything no tool call accounts for
|
|
332
|
+
shows up too.
|
|
333
|
+
|
|
334
|
+
- **Check the agent's claims:** "tests pass" against the real exit code.
|
|
335
|
+
- **Catch side effects:** a script that phoned home, a package you didn't ask
|
|
336
|
+
for, a file outside the task that got changed.
|
|
337
|
+
|
|
338
|
+
### Changes: what the prompt left different
|
|
339
|
+
|
|
340
|
+
<!-- screenshot: docs/images/changes.png -->
|
|
341
|
+
|
|
342
|
+
Every file the prompt changed, with its diff, first for the whole prompt and
|
|
343
|
+
then step by step, so you see which tool call made which change. Download it all
|
|
344
|
+
as one patch and apply it to your own checkout.
|
|
345
|
+
|
|
346
|
+
- **Review the agent's work like a pull request,** before you take it.
|
|
347
|
+
- **Take the result home:** the sandbox works on a copy, and the patch brings
|
|
348
|
+
the changes back to your machine.
|
|
349
|
+
|
|
350
|
+
### Context: what the model could see
|
|
351
|
+
|
|
352
|
+
<!-- screenshot: docs/images/context.png -->
|
|
353
|
+
|
|
354
|
+
What was in the model's context when it answered, in three parts:
|
|
355
|
+
|
|
356
|
+
- what you said earlier in the conversation;
|
|
357
|
+
- what the model brought in itself: its earlier answers, and the files it read,
|
|
358
|
+
with how much of each actually fit;
|
|
359
|
+
- what the agent's harness adds to every request.
|
|
360
|
+
|
|
361
|
+
Use it to:
|
|
362
|
+
|
|
363
|
+
- **Understand a wrong answer:** was the right file never read, or cut off?
|
|
364
|
+
- **Test a hunch:** "Rerun without this" on any file opens the Playground with
|
|
365
|
+
that file removed.
|
|
366
|
+
|
|
367
|
+
### Playground: rerun it differently, and compare
|
|
368
|
+
|
|
369
|
+

|
|
370
|
+
|
|
371
|
+
Pick any step of a session and rerun from there with something changed: an
|
|
372
|
+
earlier tool result removed or edited, a file in the project, the model, or the
|
|
373
|
+
time limit. Each rerun is a fork, a sandbox of its own started from a snapshot
|
|
374
|
+
taken just before that step, running in parallel with the others. Add a check
|
|
375
|
+
such as `npm test` and every fork is graded pass or fail. Run a change several
|
|
376
|
+
times and you get its pass rate, cost and steps, next to the same step rerun
|
|
377
|
+
unchanged.
|
|
378
|
+
|
|
379
|
+
- **Find out what actually mattered:** would it still have broken the build
|
|
380
|
+
without that misleading test output?
|
|
381
|
+
- **Compare models on your own task:** same step, same files, a different model.
|
|
382
|
+
- **Compare outcomes side by side:** each fork's answer, steps and files next to
|
|
383
|
+
the original's.
|
|
384
|
+
|
|
385
|
+
### Story and Chain of thought: why it did what it did
|
|
386
|
+
|
|
387
|
+

|
|
388
|
+
|
|
389
|
+
**Story** is the short version of a long run. It shows a timeline of only the
|
|
390
|
+
steps that mattered, the single most consequential command pulled out at the
|
|
391
|
+
top, and for each step what the agent could see, what it proposed, what really
|
|
392
|
+
happened and what that led to.
|
|
393
|
+
|
|
394
|
+
**Chain of thought** takes each tool call and lists its likely causes among what
|
|
395
|
+
the agent could see: your request, an earlier result, its own plan, or the
|
|
396
|
+
project's instructions.
|
|
397
|
+
|
|
398
|
+
Both are worked out from the recording alone, with nothing rerun. Some parts
|
|
399
|
+
use [your own key](#ai-features-on-your-own-key).
|
|
400
|
+
|
|
401
|
+
- **Explain a run to someone else** without replaying all 60 steps.
|
|
402
|
+
- **Trace a bad decision back** to the result or instruction that caused it.
|
|
403
|
+
|
|
404
|
+
### Search: across everything the agents did
|
|
405
|
+
|
|
406
|
+
<!-- screenshot: docs/images/search.png -->
|
|
407
|
+
|
|
408
|
+
Search every recorded session at once, failures first. Type free text, or use
|
|
409
|
+
filters such as `outcome:failed tool:Bash exit:>=1 file:.env`, and summarise
|
|
410
|
+
with a pipe: `| stats count by tool`. With no query, it shows the most common
|
|
411
|
+
failures lately.
|
|
412
|
+
|
|
413
|
+
- **Find patterns:** which commands fail most, and which sessions touched
|
|
414
|
+
`.env`.
|
|
415
|
+
|
|
416
|
+
### Initial scan: guard the files that matter
|
|
417
|
+
|
|
418
|
+

|
|
419
|
+
|
|
420
|
+
When a project goes into a sandbox, every file is rated from 1 to 5 for how
|
|
421
|
+
risky it is to change, with the reason. Secrets, migrations and deploy
|
|
422
|
+
configuration rate highest. You can move any file up or down, choose which
|
|
423
|
+
files to be alerted about, and **restrict** files so the agent can't change them
|
|
424
|
+
at all, whatever it tries. **Alerts** lists what the agent did to those files:
|
|
425
|
+
changes, refused edits, reads, and commands that named them.
|
|
426
|
+
|
|
427
|
+
- **Let the agent work freely** while keeping your migrations and CI config
|
|
428
|
+
off-limits.
|
|
429
|
+
|
|
430
|
+

|
|
431
|
+
- **Get told** when it touches what you care about.
|
|
432
|
+
|
|
433
|
+
### Sandboxes: where it all ran
|
|
434
|
+
|
|
435
|
+
Every sandbox, grouped by the machine it runs on, with what was asked in each.
|
|
436
|
+
Destroyed sandboxes stay listed, because their evidence outlives them.
|
|
437
|
+
|
|
438
|
+
### AI features, on your own key
|
|
439
|
+
|
|
440
|
+
Everything above works without any key. A few views can also ask a model to
|
|
441
|
+
explain a run, using **your own OpenRouter key**, billed to your OpenRouter
|
|
442
|
+
account:
|
|
443
|
+
|
|
444
|
+
```sh
|
|
445
|
+
raytrace key openrouter # paste your key from https://openrouter.ai/keys (not echoed)
|
|
446
|
+
raytrace key # which keys are set
|
|
447
|
+
```
|
|
448
|
+
|
|
449
|
+
| Feature | Where | Model (default) |
|
|
450
|
+
|---|---|---|
|
|
451
|
+
| Run recap: what the agent did and why, in a few lines | Story, Chain of thought | `anthropic/claude-sonnet-5.5` |
|
|
452
|
+
| Chain of thought: the likely reasons for each tool call | Chain of thought | `qwen/qwen3-coder` |
|
|
453
|
+
| Step summaries, and plain-English lines for commands no rule describes | Tool calls, Sandbox evidence | `openai/gpt-oss-120b` |
|
|
454
|
+
|
|
455
|
+
- **No key?** Those parts say so, and everything else works.
|
|
456
|
+
- **Cost:** each answer is kept, so opening the same prompt again is free.
|
|
457
|
+
Nothing is sent until you open a view that needs it.
|
|
458
|
+
- **What's sent:** only to OpenRouter, the parts of the run the feature reads.
|
|
459
|
+
Nothing goes to RayTrace.
|
|
460
|
+
- **Other models:** set `RAYTACE_OBSERVER_MODEL` (recap),
|
|
461
|
+
`RAYTACE_ATTRIBUTION_MODEL` (Chain of thought) or `RAYTACE_SUMMARY_MODEL`
|
|
462
|
+
(summaries) in `~/.raytrace/config.env`, then `raytrace stop && raytrace start`.
|
|
463
|
+
- **Optional:** `raytrace key typesafe` adds a [TypeSafe](https://typesafe.ai)
|
|
464
|
+
key, which ranks Chain of thought's reasons and rates how severe each command
|
|
465
|
+
was.
|
|
466
|
+
- `raytrace key openrouter --remove` removes a key.
|
|
467
|
+
|
|
468
|
+
---
|
|
469
|
+
|
|
470
|
+
## Commands
|
|
471
|
+
|
|
472
|
+
| Command | What it does |
|
|
473
|
+
|---|---|
|
|
474
|
+
| `raytrace mcp` | the MCP server for your editor; see [Set up in your editor](#set-up-in-your-editor-mcp) |
|
|
475
|
+
| `raytrace sandbox create [--local] [--name <name>]` | copy this Git repository into a new sandbox, in the cloud or (`--local`) on this machine |
|
|
476
|
+
| `raytrace connect [id or name] [--claude \| --codex]` | open a terminal in a sandbox, optionally with an agent running in it |
|
|
477
|
+
| `raytrace sandbox list [--local]` | your sandboxes |
|
|
478
|
+
| `raytrace sandbox start\|stop <id or name>` | start or stop one; stopping keeps its files |
|
|
479
|
+
| `raytrace sandbox destroy <id or name>` | delete one. Cloud: `--keep-traces` (paid plans). Local: `--delete-logs` or `--keep-logs` |
|
|
480
|
+
| `raytrace open` | open the local dashboard |
|
|
481
|
+
| `raytrace auth login\|status\|logout` | your RayTrace sign-in, for cloud sandboxes |
|
|
482
|
+
| `raytrace upload logs [--sandbox <name>]` | send a local sandbox's recorded logs to the cloud dashboard; `raytrace upload status` shows your storage |
|
|
483
|
+
| `raytrace share <trace-id> [--fork]` | a time-limited link to one recorded prompt; `--list`, `--revoke <share-id>` |
|
|
484
|
+
| `raytrace export <trace-id> [--format json\|markdown] [--output <file>]` | export a recorded prompt to the terminal or a file, even with RayTrace stopped |
|
|
485
|
+
| `raytrace --code <code>` | redeem a beta invite code |
|
|
486
|
+
| `raytrace key [openrouter\|typesafe] [--remove]` | your keys for the dashboard's AI features |
|
|
487
|
+
| `raytrace doctor` | what this machine has and lacks |
|
|
488
|
+
|
|
489
|
+
`raytrace help` lists everything.
|
|
490
|
+
|
|
491
|
+
---
|
|
492
|
+
|
|
493
|
+
## Beta invites
|
|
494
|
+
|
|
495
|
+
If RayTrace gave you a beta code, sign in, redeem it, then create your sandbox:
|
|
496
|
+
|
|
497
|
+
```sh
|
|
498
|
+
raytrace auth login
|
|
499
|
+
raytrace --code <code>
|
|
500
|
+
raytrace sandbox create
|
|
501
|
+
```
|
|
502
|
+
|
|
503
|
+
The code gives you one sandbox with $10 of model credit. Codes are single-use
|
|
504
|
+
and expire 3 days after they're issued, and the credit expires 3 days after you
|
|
505
|
+
redeem it. Your account and that sandbox show as **Beta** in the cloud dashboard
|
|
506
|
+
until then.
|
|
507
|
+
|
|
508
|
+
## Privacy
|
|
509
|
+
|
|
510
|
+
- **Local sandboxes** keep everything on your machine, in `~/.raytrace`, readable
|
|
511
|
+
only by you. The local dashboard's API needs the token in
|
|
512
|
+
`~/.raytrace/api-token`, so other accounts on the machine can't read your
|
|
513
|
+
traces. `raytrace open` signs your browser in with a one-time link.
|
|
514
|
+
- **Cloud sandboxes** upload your project ([what is uploaded](#what-is-uploaded))
|
|
515
|
+
and record prompts, model requests and answers, tool calls and commands on
|
|
516
|
+
RayTrace's servers. Members of your organization can see them; other
|
|
517
|
+
organizations can't.
|
|
518
|
+
- **Your sign-in** is kept in the macOS Keychain or the Linux secret service (or a
|
|
519
|
+
file only you can read where neither exists). `raytrace auth logout` removes
|
|
520
|
+
it. Cloud commands ask you to sign in again after 2 days without cloud use.
|
|
521
|
+
|
|
522
|
+
## Troubleshooting
|
|
523
|
+
|
|
524
|
+
- **The MCP server doesn't show up in my editor:** restart the editor after
|
|
525
|
+
adding it. In Claude Code, `claude mcp list` shows whether it's connected.
|
|
526
|
+
Check that `node --version` is 22.13 or newer.
|
|
527
|
+
- **No terminal opened after "connect":** the agent's reply has the command to
|
|
528
|
+
paste, such as `raytrace connect my-box --claude`. On macOS, allow your editor
|
|
529
|
+
to control your terminal app in **System Settings → Privacy & Security →
|
|
530
|
+
Automation**.
|
|
531
|
+
- **The first local sandbox is taking long:** setting up the VM takes a few
|
|
532
|
+
minutes. Ask the agent for the sandbox status, or read
|
|
533
|
+
`~/.raytrace/logs/mcp-create-<name>-*.log`. The whole VM log is in
|
|
534
|
+
`~/.raytrace/logs/sandbox-vm.log`.
|
|
535
|
+
- **`sandbox create --local` says the machine isn't ready:** each line says
|
|
536
|
+
what's missing and how to fix it; `raytrace doctor` shows the same. Port 8798
|
|
537
|
+
in use usually means another Lima VM is running (`limactl list`).
|
|
538
|
+
- **A local sandbox's sessions don't show in the dashboard:** restart RayTrace
|
|
539
|
+
with `raytrace stop && raytrace start`.
|
|
540
|
+
- **The dashboard says this browser isn't signed in:** run `raytrace open`.
|
|
541
|
+
- **`Cannot reach RayTrace at https://api.raytracer.si`:** check your
|
|
542
|
+
connection. Networks that inspect HTTPS, such as some company Wi-Fi, can block
|
|
543
|
+
it.
|
|
544
|
+
- **A sandbox isn't found:** `raytrace auth status` shows which account you're
|
|
545
|
+
signed in as. Sandboxes belong to the account that made them.
|
|
546
|
+
|
|
547
|
+
## Uninstall
|
|
548
|
+
|
|
549
|
+
```sh
|
|
550
|
+
raytrace sandbox destroy <id or name> # any sandboxes you no longer need
|
|
551
|
+
raytrace uninstall --purge # local sandboxes: deletes the VM and ~/.raytrace
|
|
552
|
+
raytrace auth logout
|
|
553
|
+
npm uninstall -g @raytrace-cli/cli # or: pip uninstall raytrace-cli
|
|
554
|
+
claude mcp remove raytrace -s user # if you added the MCP server to Claude Code
|
|
555
|
+
```
|
|
556
|
+
|
|
557
|
+
Without `--purge`, remove the VM yourself with `limactl delete --force raytrace`.
|
|
558
|
+
|
|
559
|
+
## Developing
|
|
560
|
+
|
|
561
|
+
```sh
|
|
562
|
+
npm install
|
|
563
|
+
npm run build # dashboard -> dist/dashboard
|
|
564
|
+
npm run dashboard:dev # dashboard with hot reload, API from a running RayTrace
|
|
565
|
+
npm run typecheck
|
|
566
|
+
npm test
|
|
567
|
+
node bin/raytrace.mjs <command> # run the CLI from this folder
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
To use your checkout as the MCP server in Claude Code:
|
|
571
|
+
|
|
572
|
+
```sh
|
|
573
|
+
claude mcp add --scope user raytrace -- node /path/to/raytrace-cli/bin/raytrace.mjs mcp
|
|
574
|
+
```
|
|
575
|
+
|
|
576
|
+
To try it without touching your real setup, give it its own home and port:
|
|
577
|
+
|
|
578
|
+
```sh
|
|
579
|
+
mkdir -p /tmp/rt && echo RAYTACE_PORT=18797 > /tmp/rt/config.env
|
|
580
|
+
RAYTRACE_HOME=/tmp/rt node bin/raytrace.mjs setup --no-claude-code
|
|
581
|
+
```
|
|
582
|
+
|
|
583
|
+
### Publishing to pip
|
|
584
|
+
|
|
585
|
+
The pip package is the npm package plus an official Node.js build, one wheel per
|
|
586
|
+
platform. After `npm publish`, build the same version's wheels and upload them:
|
|
587
|
+
|
|
588
|
+
```sh
|
|
589
|
+
python3 python/build_wheels.py # all six platforms, into python/dist/
|
|
590
|
+
twine upload python/dist/*.whl
|
|
591
|
+
```
|
|
592
|
+
|
|
593
|
+
The *pip wheels* workflow builds the same wheels on every `v*` tag and installs
|
|
594
|
+
them on Linux, macOS and Windows (x64 and ARM); its `wheels` artifact can be
|
|
595
|
+
uploaded instead. The Node.js version is `NODE_VERSION` in `python/build_wheels.py`.
|
|
596
|
+
|
|
597
|
+
## License
|
|
598
|
+
|
|
599
|
+
MIT
|