RAYTRACE DOCS
Your sandbox.
Your choice.
RUN ON YOUR MACHINE
Local sandboxes.
Install the npm package, create a sandbox from a Git project, and launch Claude Code. Then open your local dashboard to inspect the run.
Install the CLI, check its version, enter your Git project, create a local sandbox, connect, launch Claude Code, and open the local dashboard. All commands are listed below.
One command at a time, from install to local evidence. Output is illustrative; first-time setup is compressed.Watch full screen →
Local commands
Run these groups in order. Replace your-project with your Git project’s path and demo-box with your sandbox name.
Install & check
Requires Node.js 22.13+, npm, and Git. The doctor command checks your machine’s prerequisites.
npm install -g @raytrace-cli/cli@latest
raytrace --version
raytrace doctorCreate & connect
Create an isolated copy of your project, then enter its terminal. First-time VM setup may take a few minutes.
cd your-project
raytrace sandbox create --local --name demo-box
raytrace connect demo-boxRun your agent
Launch Claude Code and sign in when prompted. For Codex, run codex instead.
claudeOpen the dashboard
Leave the agent first. Exit the sandbox terminal, then open the dashboard on your machine; the sandbox keeps running.
exitraytrace openAll local commands & sandbox management
| Command | Run in | What it does |
|---|---|---|
npm install -g @raytrace-cli/cli@latest | Your machine | Install or update the CLI. Requires Node.js 22.13+, npm, and Git. |
raytrace --version | Your machine | Show the installed CLI version. The video uses 0.12.0. |
raytrace doctor | Your machine | Check prerequisites and get instructions for missing requirements. |
cd your-project | Your machine | Enter your Git project. Replace your-project with its path. |
raytrace sandbox create --local --name demo-box | Your machine | Copy this project into a new local sandbox named demo-box. First use prepares the VM and preinstalled agents. |
raytrace connect demo-box | Your machine | Open a terminal inside the running sandbox’s isolated project copy. |
claude | Inside sandbox | Launch Claude Code, then sign in to your Claude account if prompted. |
codex | Inside sandbox | Alternatively, launch Codex and sign in to your Codex account. |
exit | Inside sandbox | Leave the sandbox terminal and return to your machine. The sandbox keeps running. |
raytrace open | Your machine | Open the local dashboard. Select demo-box in Sandboxes to inspect prompts, tool calls, file changes, and network activity. |
raytrace sandbox list --local | Your machine | List your local sandboxes and their names. |
raytrace sandbox stop demo-box | Your machine | Stop the sandbox and keep its project files. |
raytrace sandbox start demo-box | Your machine | Resume the sandbox; connect again to continue working. |
raytrace sandbox destroy demo-box | Your machine | Delete the sandbox workspace. Export your work first; the CLI asks whether to keep or delete captured logs. |
raytrace stop | Your machine | Stop the local recorder services, separately from individual sandboxes. |
raytrace start | Your machine | Start the local recorder services. Restart them if sessions stop appearing after an upgrade. |
raytrace upload logs --sandbox demo-box | Your machine | Optionally upload this sandbox’s evidence after signing in to RayTrace. Review the dates and size before confirming. |
raytrace help | Your machine | Show CLI commands and options. |
First-time setup can take several minutes, about 1 GB of downloads, and 4 GiB of memory while the VM runs. Your original project remains on your machine; the agent works in its sandbox copy. Agent provider calls use your provider account, and captured evidence stays local unless you choose to upload it. Privacy & scope →
GET STARTED WITH RAYTRACE
Cloud sandboxes.
Install RayTrace, sign up from the CLI, create a cloud sandbox from your project, and run your agent there. Then inspect the prompts, tool calls, and executed commands in the hosted dashboard.
You’ll need Node.js 22.13+, npm, and a Git project. RayTrace does not ask you for an API key.
Install the CLI, sign in to RayTrace, enter your Git project, create a cloud sandbox, connect using its ID, launch Claude Code, and review evidence at app.raytracer.si.
From your terminal to a cloud sandbox, one command at a time. Output is illustrative and setup timing is compressed.Watch full screen →
Cloud commands
Run these groups in order. Replace your-project with your Git project’s path and cloud-demo with your sandbox name.
Install & sign in
Approve the browser sign-in before continuing.
npm install -g @raytrace-cli/cli@latest
raytrace --version
raytrace auth loginCreate & connect
Upload your project to a new cloud sandbox, then enter its terminal.
cd your-project
raytrace sandbox create --name cloud-demo
raytrace connect cloud-demoRun your agent
Claude Code and Codex are preinstalled. Launch one and sign in with your provider account.
claudePrefer Codex? Run codex instead.
Review your runOpen app.raytracer.si ↗ and select your sandbox to inspect the evidence.
Sign-in help & browser setup
Login prints a short code and opens a browser approval page. Check your account with raytrace auth status. Your RayTrace account is separate from your agent provider account.
To create a sandbox in your browser, open app.raytracer.si, sign in, and drop a project folder on the Sandboxes page. Review what would be uploaded before sending it.
Everyday commands & uninstall
| Command | What it does |
|---|---|
raytrace auth login|status|logout | Sign in to RayTrace, inspect your sign-in, or remove it from this machine. |
raytrace sandbox create [--name <name>] | Upload the current Git project to a new cloud sandbox. A later create makes another sandbox; it does not sync changes into an existing one. |
raytrace sandbox list | List your cloud sandboxes. |
raytrace connect [id] | Open an interactive terminal in a sandbox (also raytrace sandbox shell [id]). Omit the ID only when you have one live sandbox. |
raytrace sandbox start|stop [id] | Resume or stop a sandbox; stopping keeps its files. |
raytrace sandbox destroy [id] | Delete the sandbox and any agent sign-in inside it. On Beta its traces go too; on paid plans you are asked whether to keep them until your retention date (--keep-traces in scripts). Destruction asks you to type the ID to confirm — export any work you want to keep first. |
raytrace help | Show commands. |
Remove RayTrace
Destroy any sandboxes you no longer need, sign out, then remove the package:
raytrace sandbox destroy <sandbox-id>
raytrace auth logout
npm uninstall -g @raytrace-cli/cliSigning out removes your sign-in from this machine; it does not stop or destroy cloud sandboxes. Recorded sessions are kept for your organization.
Privacy & release scope
Cloud sandboxes run on RayTrace’s servers. Creating one uploads your project; prompts, requests, answers, tool calls, and executed commands are recorded there for your organization. Organization members can review the sessions in the hosted dashboard. Destroying a sandbox deletes its files and agent sign-ins. On Free its recorded evidence goes too; on Pro and Enterprise you choose whether to keep it until your retention date.
What leaves your machine
A local sandbox stays on your machine, and nothing about it is sent unless you run raytrace upload logs. That command shows the sandbox, its dates and size, asks you to confirm, and sends only that sandbox’s evidences: prompts, model responses, tool calls and kernel-level activity, gzipped. Other sandboxes, your project files and your sign-ins are not included. Credential-shaped fields are withheld when recorded, but prompts and tool output can still contain secrets, so check before you upload. Members of your organization can see what you upload, according to their role. Uploaded evidence is what your machine reported, not evidence RayTrace collected independently, and the dashboard marks it Local.
Your CLI sign-in is kept in the macOS Keychain or Linux secret service, with a file readable only by you as a fallback. raytrace auth logout removes the sign-in from your machine; it does not stop or destroy cloud sandboxes.
Evidence boundaries
A transcript’s reported tool result is separate from independently observed execution evidence. A command starting or exiting successfully is not proof of a correct outcome. RayTrace does not reconstruct a model’s private chain of thought.
What gets uploaded
Creating a sandbox uploads the files Git would track, including new files not ignored by Git. It excludes .git, dependency directories such as node_modules, common build output, .env*, private keys (.pem, .key, .p12, .pfx), and common credential files such as .npmrc and .netrc. Symlinks are skipped. A folder dropped in the dashboard follows the same rules. Review your files before uploading: exclusions cannot detect secrets embedded in ordinary source files.
Limits: a project may be up to 200 MiB and 20,000 files before compression, with no single file over 25 MiB, and 100 MiB once packed; a project over a limit is refused with the files named, and nothing is uploaded. How many live sandboxes you may run depends on your plan (3 on Free, 5 on Pro) — see Pricing. Cloud sandboxes are a preview; report a preview issue.
YOUR AI’S EVIDENCE
What RayTrace records.
Follow what your agent saw, what it tried, and what the sandbox observed. RayTrace stores the session alongside execution evidence so you can investigate the steps behind an answer.
The agent’s session
Review prompts, model responses, tool calls, and the results returned to the agent. This is the record of the interaction: the instructions it received, the tools it requested, and what those tools reported.
What ran in the sandbox
Inspect recorded processes, command arguments, start and exit events, exit codes, and timing. A tool call can start several processes; the sandbox evidence lets you follow those processes beyond the agent’s reported result.
Files and changes
Review file operations reported by the agent’s tools and snapshots of changes inside the project folder. Compare added, edited, and deleted files with the agent’s claims. A built-in read tool is part of the agent’s report; a project snapshot confirms changes, but does not prove which files a program read.
Network activity
Inspect recorded sandbox network destinations and connection outcomes to understand which services the run contacted. Read this alongside the agent’s requests and results when investigating unexpected activity.
Where your record lives
Local sandbox evidence stays on your machine unless you choose to upload it. Cloud sandbox evidence is stored on RayTrace for your organization. Read Privacy & scope for upload details and coverage limits.
READING A TRACE
What the labels
on a tool call mean.
Every row in Tool calls carries two labels. The Tool column says what kind of step it was. The Sandbox column says what independent evidence there is that it happened.
They answer different questions and are decided in different ways. A category is a description of the step. A sandbox label is a comparison of recorded facts, and nothing else.
Tool categories
The Tool column shows the category first and the tool’s real name beside it, such as Run · Bash or Edit · apply_patch. A category is named for what the call did, not for the tool or agent that made it, so Claude Code’s Read and a Codex cat are both Read.
| Category | What it means | Examples |
|---|---|---|
| Read | Looked at the contents of a file. | Read, cat, head, sed -n |
| Search | Looked for files or text, or listed what is there. | Grep, Glob, rg, find, ls |
| Write | Created or replaced a whole file or folder. | Write, echo … > file, cp, mkdir |
| Edit | Changed part of an existing file, or its permissions. | Edit, apply_patch, sed -i, chmod |
| Delete / move | Removed, renamed or moved files. | rm, mv, a patch that deletes a file |
| Run | Executed a script or program. | sh check.sh, python tool.py, node server.js |
| Test | Ran tests, a linter or a type check. | pytest, npm test, tsc, eslint |
| Build / install | Built the project or fetched its dependencies. | npm install, pip install, make, cargo build |
| Git | Version control. | git status, git commit, gh pr create |
| Web | Reached the network. | WebFetch, WebSearch, curl, wget |
| Plan | Organised its own work, or asked you something. | TodoWrite, update_plan, AskUserQuestion |
| Delegate | Handed work to another agent or an outside tool. | Task, Skill, any MCP tool |
| Not sure | RayTrace could not tell what kind of step this was. | An unfamiliar program, or a tool RayTrace does not know |
How a category is decided
- A named tool is placed by its name.
- A shell command is placed by the programs it runs. RayTrace reads the command line, skips set-up such as
cdandexport, and looks each program up. - A command with several parts takes its most consequential one, in this order: Delete / move, Edit, Write, Git, Build / install, Test, Web, Run, Search, Read. So
cd app && cat notes.txt && rm old.txtis Delete / move. - A command RayTrace does not recognise is put to a decision model, which chooses among the same categories from the command’s text. When it is not confident, or is not available, the step reads Not sure.
A script is Run, whatever it does inside: sh check.sh is Run even if the script deletes files. The category describes the step the agent took. What the script then started is in Sandbox evidence.
Sandbox labels
The Sandbox column compares what the agent reported with what RayTrace recorded independently. A command is confirmed by the process the sandbox saw. A file write is confirmed by a snapshot of the project folder taken after the call. No model has a say in any of these labels.
| Label | What it means | How it is decided | What to do |
|---|---|---|---|
| ✓ ran | The sandbox saw this command run. | A process the sandbox recorded was matched to the tool call: by the call’s own id where the agent passes one, otherwise by the command’s text inside the call’s time window. | Click the label to open that process in Sandbox evidence. |
| ⚠ ran, differs | The command ran, but the agent was told something different from what the sandbox saw. | The exit code in the agent’s result does not match the one the sandbox recorded, or the run time it reported is far from the observed one. | Click the label and compare. The sandbox’s record is the independent one. |
| ✗ rejected | The agent’s own sandbox policy refused to run the command. | The result the agent got back says the command was refused. | Nothing ran. Look at what the agent did next. |
| — not seen | A command was proposed, and the sandbox has no process for it. | No recorded process matched this tool call. | Missing evidence is not proof that it did not run. Open Sandbox evidence and look at what ran around that time. |
| ✓ file changed | The agent reported a write, and the file is different on disk. | The snapshot of the project folder taken after the call lists the file as added, edited or deleted. | Click the label to see the files that changed. |
| ✗ no change | The agent reported a successful write, but the file on disk did not change. | The file is inside the project folder and no snapshot from that round trip lists it. | Worth a look. It is also what you see when a file is rewritten with exactly the content it already had. |
| in agent | A built-in tool that starts no program and changes no file: a read, a search, a plan. | The tool is one RayTrace knows to run inside the agent itself. | There is nothing for the sandbox to observe. You have the agent’s report only. |
| not covered | RayTrace was not watching there. | A write outside the project folder (/workspace), a file too big to snapshot (over 5 MB), a write no snapshot was taken for, or a run that was not in a sandbox. | Treat it as the agent’s word. This is different from “not seen”, where RayTrace looked and found nothing. |
What counts as proof
- The sandbox’s own observation: ✓ ran, ⚠ ran, differs, ✓ file changed and ✗ no change. These come from a process the sandbox recorded or from the files on disk, not from anything the agent said.
- The agent’s report only: ✗ rejected and in agent. RayTrace shows what the agent was told, and has nothing of its own to set beside it.
- No evidence either way: — not seen and not covered. Neither one says the step did not happen.
The sandbox records programs starting and exiting, and snapshots the project folder after each call that can change files. It does not record which files a program read, so a read made by a built-in tool is always “in agent”..
SECURITY & ISOLATION
Your agent gets a sandbox.
Not your machine.
RayTrace runs coding agents in isolated cloud sandboxes, records what they actually do, and keeps each project separate from every other project. This page explains the boundaries in plain language — what is separated, what is restricted, and where the honest limits are.
THE SHORT VERSION
Built for code you have not reviewed yet.
A coding agent can write files, run commands, install packages and call tools. RayTrace assumes that work should happen somewhere disposable and observable — not directly against your laptop, your credentials, or a production system.
Each sandbox is a separate gVisor-isolated container with its own workspace and home storage. One sandbox cannot browse another sandbox’s project. Sandboxes run as a non-root user with Linux capabilities dropped, resource limits applied, and network access restricted so private addresses are refused.
HOW ISOLATION WORKS
Several boundaries, not one promise.
A separate execution boundary
Every sandbox runs under gVisor, which places a user-space kernel between the agent’s processes and the host. That is a stronger boundary than an ordinary container sharing the host kernel directly.
Private project storage
Each sandbox gets its own workspace and home volumes. Other sandboxes’ volumes are not mounted, so an agent cannot wander into a neighbouring project’s files.
Least privilege by default
Sandbox processes run as a non-root user, with all Linux capabilities dropped and privilege escalation disabled. CPU, memory and process-count limits keep one run from consuming the whole machine.
A narrower network
Sandboxes can reach the public internet for package installs and documentation, but connections to private addresses are refused. That protects internal services and cloud metadata from code running inside a sandbox.
BEFORE ANYTHING IS UPLOADED
You see the boundary before you cross it.
Creating a sandbox uploads a copy of your project. Common secret-bearing files are excluded before upload — including environment files, private keys and common credential files — and the same screening is repeated on RayTrace’s side. The browser flow shows what would be uploaded before anything is sent.
No sandbox writes back to your computer automatically. When you destroy a sandbox, its files and any agent sign-in made inside it are deleted; the recorded session evidence is kept for your organization.
FILES THAT DESERVE A SECOND LOOK
Risky files are flagged before the agent touches them.
Every uploaded project gets an initial scan that classifies files from “Ignore” to “Lock down,” based on how widely a file is used and how sensitive its contents are. Migrations, deployment configuration, credential-handling code and destructive database operations sit at the top.
You can mark any file to be reported when it changes, or restricted so the agent may not change it. Restricted files are enforced in the sandbox, not merely labelled in the dashboard — and a kernel-level record shows attempts as well as completed changes.
EVIDENCE, NOT JUST CLAIMS
What the agent says is kept separate from what was observed.
An agent’s transcript can say a command succeeded. RayTrace also records independently observed execution evidence from the sandbox, so reported results and observed results can be compared instead of blended into one story.
That separation matters when something looks wrong: a successful shell exit does not prove every command inside it succeeded, and a polished summary does not prove the work was done correctly. RayTrace does not reconstruct a model’s private chain of thought; it shows the requests, tool calls and execution evidence that can actually be checked.
MODEL ACCESS
Your provider key does not live in the sandbox.
Claude Code and Codex can run on RayTrace’s central model access through a controlled bridge, using a revocable per-sandbox token rather than your provider API key. Usage is metered against your plan, and access can be revoked without rotating your own credentials.
You can also sign in inside a sandbox with your own agent account. That sign-in stays in the sandbox’s private home storage and is deleted when the sandbox is destroyed.
THE HONEST BOUNDARY
Shared infrastructure, isolated sandboxes.
RayTrace sandboxes are isolated containers on shared infrastructure; they are not a separate physical machine per customer. That is a deliberate trade-off: strong sandbox isolation without making every run wait for a dedicated machine to be provisioned. Platform operators run the service and can administer the infrastructure, so RayTrace is not a zero-access vault for data you would never entrust to a cloud provider.
If your organization needs dedicated infrastructure or a specific compliance review, talk to us through the Team & Enterprise query form. We would rather describe the boundary accurately than oversell it.