raytrace-cli 0.11.1__py3-none-macosx_13_0_arm64.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.
Files changed (165) hide show
  1. raytrace/__init__.py +1 -0
  2. raytrace/__main__.py +33 -0
  3. raytrace/app/LICENSE +21 -0
  4. raytrace/app/README.md +599 -0
  5. raytrace/app/bin/raytrace.mjs +297 -0
  6. raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-BwCSEQnW.woff +0 -0
  7. raytrace/app/dist/dashboard/assets/dm-sans-latin-400-normal-CW0RaeGs.woff2 +0 -0
  8. raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-B9HHJjqV.woff2 +0 -0
  9. raytrace/app/dist/dashboard/assets/dm-sans-latin-500-normal-Dr3UlScf.woff +0 -0
  10. raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-Aqo67rzb.woff2 +0 -0
  11. raytrace/app/dist/dashboard/assets/dm-sans-latin-600-normal-BmdmIIQ2.woff +0 -0
  12. raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-CUSSCpQX.woff +0 -0
  13. raytrace/app/dist/dashboard/assets/dm-sans-latin-700-normal-DvUfVpUG.woff2 +0 -0
  14. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BjWJ59Pq.woff +0 -0
  15. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-400-normal-BtiwyxMk.woff2 +0 -0
  16. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-BJfUCQsA.woff2 +0 -0
  17. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-500-normal-DR84L5F-.woff +0 -0
  18. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-4vooXBpG.woff2 +0 -0
  19. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-600-normal-DRtaDpgU.woff +0 -0
  20. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-BLI3TTWz.woff +0 -0
  21. raytrace/app/dist/dashboard/assets/dm-sans-latin-ext-700-normal-CJIcxD6K.woff2 +0 -0
  22. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-BSMlKf0J.woff2 +0 -0
  23. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-400-normal-CEL4l2ZJ.woff +0 -0
  24. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Ael50iVv.woff +0 -0
  25. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-500-normal-Bq9vWWag.woff2 +0 -0
  26. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-CTOM6hUh.woff2 +0 -0
  27. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-600-normal-fLZuRloM.woff +0 -0
  28. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-DMdlQ8Kv.woff +0 -0
  29. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-400-normal-xuaO2J-f.woff2 +0 -0
  30. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BIfNGwUT.woff +0 -0
  31. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-500-normal-BqneJy0T.woff2 +0 -0
  32. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-9HEixskS.woff +0 -0
  33. raytrace/app/dist/dashboard/assets/ibm-plex-mono-cyrillic-ext-600-normal-V-xxqcpd.woff2 +0 -0
  34. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-CvHOgSBP.woff +0 -0
  35. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-400-normal-DMJ8VG8y.woff2 +0 -0
  36. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-CB9ihrfo.woff +0 -0
  37. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-500-normal-DSY6xOcd.woff2 +0 -0
  38. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-BgSNZQsw.woff2 +0 -0
  39. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-600-normal-DWFSQ4vo.woff +0 -0
  40. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-BmRBH3aV.woff2 +0 -0
  41. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-400-normal-D3D2R8hC.woff +0 -0
  42. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CAhNIIs5.woff2 +0 -0
  43. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-500-normal-CZ70TYgx.woff +0 -0
  44. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-D38SheWl.woff2 +0 -0
  45. raytrace/app/dist/dashboard/assets/ibm-plex-mono-latin-ext-600-normal-DmB0ttJJ.woff +0 -0
  46. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-BulugwFq.woff2 +0 -0
  47. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-400-normal-DDuiU_S-.woff +0 -0
  48. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-C8zxqsMH.woff +0 -0
  49. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-500-normal-DZ4AoWbu.woff2 +0 -0
  50. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-D2EvbN8M.woff2 +0 -0
  51. raytrace/app/dist/dashboard/assets/ibm-plex-mono-vietnamese-600-normal-iLQfcSjf.woff +0 -0
  52. raytrace/app/dist/dashboard/assets/index-DepcI8Fi.js +38 -0
  53. raytrace/app/dist/dashboard/assets/index-H97VLD5l.css +1 -0
  54. raytrace/app/dist/dashboard/favicon.svg +6 -0
  55. raytrace/app/dist/dashboard/index.html +15 -0
  56. raytrace/app/package.json +48 -0
  57. raytrace/app/proxy/agent-intent-schema.test.mjs +142 -0
  58. raytrace/app/proxy/call-assessment.mjs +385 -0
  59. raytrace/app/proxy/call-assessment.test.mjs +167 -0
  60. raytrace/app/proxy/call-category.mjs +461 -0
  61. raytrace/app/proxy/capture-health.mjs +30 -0
  62. raytrace/app/proxy/capture-health.test.mjs +44 -0
  63. raytrace/app/proxy/capture.mjs +38 -0
  64. raytrace/app/proxy/capture.test.mjs +49 -0
  65. raytrace/app/proxy/claude-code-adapter.mjs +301 -0
  66. raytrace/app/proxy/claude-code-hook.mjs +22 -0
  67. raytrace/app/proxy/codex-config.mjs +36 -0
  68. raytrace/app/proxy/codex.mjs +14 -0
  69. raytrace/app/proxy/evidence-schema.test.mjs +240 -0
  70. raytrace/app/proxy/evidence-store.mjs +993 -0
  71. raytrace/app/proxy/evidence-store.test.mjs +301 -0
  72. raytrace/app/proxy/exec-narrative.mjs +625 -0
  73. raytrace/app/proxy/exec-narrative.test.mjs +262 -0
  74. raytrace/app/proxy/execution-correlation.mjs +185 -0
  75. raytrace/app/proxy/execution-correlation.test.mjs +146 -0
  76. raytrace/app/proxy/execution-runner.mjs +89 -0
  77. raytrace/app/proxy/execution-runner.test.mjs +38 -0
  78. raytrace/app/proxy/experiment-engine.mjs +195 -0
  79. raytrace/app/proxy/experiment-engine.test.mjs +93 -0
  80. raytrace/app/proxy/explanations.mjs +36 -0
  81. raytrace/app/proxy/explanations.test.mjs +20 -0
  82. raytrace/app/proxy/failure-signature.mjs +56 -0
  83. raytrace/app/proxy/gvisor-forwarder.mjs +493 -0
  84. raytrace/app/proxy/gvisor-forwarder.test.mjs +433 -0
  85. raytrace/app/proxy/init-evidence-db.mjs +227 -0
  86. raytrace/app/proxy/local-sandboxes.mjs +94 -0
  87. raytrace/app/proxy/local-token.mjs +30 -0
  88. raytrace/app/proxy/playground-recovery.test.mjs +130 -0
  89. raytrace/app/proxy/playground.mjs +439 -0
  90. raytrace/app/proxy/prompt-context.mjs +278 -0
  91. raytrace/app/proxy/prompt-traces.mjs +40 -0
  92. raytrace/app/proxy/prompt-traces.test.mjs +32 -0
  93. raytrace/app/proxy/providers.mjs +65 -0
  94. raytrace/app/proxy/providers.test.mjs +76 -0
  95. raytrace/app/proxy/proxy.integration.test.mjs +135 -0
  96. raytrace/app/proxy/raytace-proxy.mjs +941 -0
  97. raytrace/app/proxy/request-metrics.mjs +13 -0
  98. raytrace/app/proxy/request-metrics.test.mjs +19 -0
  99. raytrace/app/proxy/request-policy.mjs +45 -0
  100. raytrace/app/proxy/request-policy.test.mjs +47 -0
  101. raytrace/app/proxy/run-recap.mjs +139 -0
  102. raytrace/app/proxy/runtime-attribution.mjs +110 -0
  103. raytrace/app/proxy/sandbox-bridge.mjs +49 -0
  104. raytrace/app/proxy/schema/EVIDENCE_DATABASE.md +276 -0
  105. raytrace/app/proxy/schema/agent_intent.sql +101 -0
  106. raytrace/app/proxy/schema/auxiliary.sql +90 -0
  107. raytrace/app/proxy/schema/capture_health.sql +14 -0
  108. raytrace/app/proxy/schema/classification.sql +89 -0
  109. raytrace/app/proxy/schema/file_context.sql +53 -0
  110. raytrace/app/proxy/schema/runtime_evidence.sql +201 -0
  111. raytrace/app/proxy/schema/search.sql +66 -0
  112. raytrace/app/proxy/schema/shared_storage.sql +21 -0
  113. raytrace/app/proxy/search.mjs +418 -0
  114. raytrace/app/proxy/search.test.mjs +161 -0
  115. raytrace/app/proxy/smoke.test.mjs +93 -0
  116. raytrace/app/proxy/step-attribution.mjs +380 -0
  117. raytrace/app/proxy/step-lab.mjs +78 -0
  118. raytrace/app/proxy/step-lab.test.mjs +38 -0
  119. raytrace/app/proxy/summaries.mjs +151 -0
  120. raytrace/app/proxy/summaries.test.mjs +69 -0
  121. raytrace/app/proxy/tool-metadata.mjs +111 -0
  122. raytrace/app/proxy/tool-metadata.test.mjs +38 -0
  123. raytrace/app/proxy/trace-view.mjs +324 -0
  124. raytrace/app/proxy/trace-view.test.mjs +92 -0
  125. raytrace/app/proxy/typesafe.mjs +63 -0
  126. raytrace/app/proxy/typesafe.test.mjs +39 -0
  127. raytrace/app/src/agents.mjs +7 -0
  128. raytrace/app/src/api.mjs +57 -0
  129. raytrace/app/src/auth.mjs +205 -0
  130. raytrace/app/src/beta.mjs +96 -0
  131. raytrace/app/src/claude-code.mjs +93 -0
  132. raytrace/app/src/commands.mjs +285 -0
  133. raytrace/app/src/config.mjs +49 -0
  134. raytrace/app/src/export.mjs +200 -0
  135. raytrace/app/src/lima.mjs +176 -0
  136. raytrace/app/src/local-sandbox.mjs +358 -0
  137. raytrace/app/src/mcp.mjs +688 -0
  138. raytrace/app/src/paths.mjs +33 -0
  139. raytrace/app/src/prompt.mjs +42 -0
  140. raytrace/app/src/proxy-process.mjs +143 -0
  141. raytrace/app/src/sandbox.mjs +306 -0
  142. raytrace/app/src/share.mjs +86 -0
  143. raytrace/app/src/terminal.mjs +68 -0
  144. raytrace/app/src/upload.mjs +198 -0
  145. raytrace/app/worker/sandbox/Dockerfile +8 -0
  146. raytrace/app/worker/sandbox/SYSCALL_CATALOG.md +197 -0
  147. raytrace/app/worker/sandbox/claude-hook.mjs +364 -0
  148. raytrace/app/worker/sandbox/collector.py +405 -0
  149. raytrace/app/worker/sandbox/dns_forwarder.py +255 -0
  150. raytrace/app/worker/sandbox/engine.py +940 -0
  151. raytrace/app/worker/sandbox/file_scan.py +491 -0
  152. raytrace/app/worker/sandbox/lima.yaml +29 -0
  153. raytrace/app/worker/sandbox/network.py +90 -0
  154. raytrace/app/worker/sandbox/projects.py +702 -0
  155. raytrace/app/worker/sandbox/setup.py +159 -0
  156. raytrace/app/worker/sandbox/syscall_catalog.sql +985 -0
  157. raytrace/app/worker/sandbox/transcript-delivery.test.mjs +153 -0
  158. raytrace/app/worker/sandbox/viewer.py +195 -0
  159. raytrace/node/LICENSE +2946 -0
  160. raytrace/node/node +4 -0
  161. raytrace_cli-0.11.1.dist-info/LICENSE +21 -0
  162. raytrace_cli-0.11.1.dist-info/METADATA +42 -0
  163. raytrace_cli-0.11.1.dist-info/RECORD +165 -0
  164. raytrace_cli-0.11.1.dist-info/WHEEL +4 -0
  165. 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
+ ![RayTrace tool-call timeline showing commands, reported results, cost, time, and token usage](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/tool-calls.jpg)
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
+ ![The Prompts page: an activity calendar and the list of prompts, each tagged with where it ran, the model, tool calls and cost](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/prompts.jpg)
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
+ ![An opened prompt with its recap: what happened, probably why, and what is worth checking, with links to Tool calls, Sandbox evidence and Context](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/prompt-recap.jpg)
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
+ ![Sandbox evidence: each process the sandbox saw run, with its exit code, duration and severity, and a plain-English description](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/sandbox-evidence.jpg)
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
+ ![The Playground: pick a step, change the message, files, check command or model, and run forks](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/playground.jpg)
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
+ ![Chain of thought: a recap of the run, the likely reason for each step with its share, and what is worth checking](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/chain-of-thought.jpg)
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
+ ![Initial scan: every file of the project grouped by risk level, with counts of watched and restricted files](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/initial-scan.jpg)
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
+ ![Initial scan alerts: watched files such as config/payment-keys.js being read, each seen by the kernel, with the tool that did it](https://raw.githubusercontent.com/Godcreatebugs/raytrace-cli/main/docs/images/initial-scan-alerts.jpg)
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