RayTrace

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.

01

Install & check

Requires Node.js 22.13+, npm, and Git. The doctor command checks your machine’s prerequisites.

YOUR MACHINE
npm install -g @raytrace-cli/cli@latest
raytrace --version
raytrace doctor
02

Create & connect

Create an isolated copy of your project, then enter its terminal. First-time VM setup may take a few minutes.

YOUR MACHINE
cd your-project
raytrace sandbox create --local --name demo-box
raytrace connect demo-box
03

Run your agent

Launch Claude Code and sign in when prompted. For Codex, run codex instead.

INSIDE SANDBOX
claude
04

Open the dashboard

Leave the agent first. Exit the sandbox terminal, then open the dashboard on your machine; the sandbox keeps running.

INSIDE SANDBOX
exit
YOUR MACHINE
raytrace open
All local commands & sandbox management
CommandRun inWhat it does
npm install -g @raytrace-cli/cli@latestYour machineInstall or update the CLI. Requires Node.js 22.13+, npm, and Git.
raytrace --versionYour machineShow the installed CLI version. The video uses 0.12.0.
raytrace doctorYour machineCheck prerequisites and get instructions for missing requirements.
cd your-projectYour machineEnter your Git project. Replace your-project with its path.
raytrace sandbox create --local --name demo-boxYour machineCopy this project into a new local sandbox named demo-box. First use prepares the VM and preinstalled agents.
raytrace connect demo-boxYour machineOpen a terminal inside the running sandbox’s isolated project copy.
claudeInside sandboxLaunch Claude Code, then sign in to your Claude account if prompted.
codexInside sandboxAlternatively, launch Codex and sign in to your Codex account.
exitInside sandboxLeave the sandbox terminal and return to your machine. The sandbox keeps running.
raytrace openYour machineOpen the local dashboard. Select demo-box in Sandboxes to inspect prompts, tool calls, file changes, and network activity.
raytrace sandbox list --localYour machineList your local sandboxes and their names.
raytrace sandbox stop demo-boxYour machineStop the sandbox and keep its project files.
raytrace sandbox start demo-boxYour machineResume the sandbox; connect again to continue working.
raytrace sandbox destroy demo-boxYour machineDelete the sandbox workspace. Export your work first; the CLI asks whether to keep or delete captured logs.
raytrace stopYour machineStop the local recorder services, separately from individual sandboxes.
raytrace startYour machineStart the local recorder services. Restart them if sessions stop appearing after an upgrade.
raytrace upload logs --sandbox demo-boxYour machineOptionally upload this sandbox’s evidence after signing in to RayTrace. Review the dates and size before confirming.
raytrace helpYour machineShow 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.

01

Install & sign in

Approve the browser sign-in before continuing.

YOUR MACHINE
npm install -g @raytrace-cli/cli@latest
raytrace --version
raytrace auth login
02

Create & connect

Upload your project to a new cloud sandbox, then enter its terminal.

YOUR MACHINE
cd your-project
raytrace sandbox create --name cloud-demo
raytrace connect cloud-demo
03

Run your agent

Claude Code and Codex are preinstalled. Launch one and sign in with your provider account.

INSIDE SANDBOX
claude

Prefer Codex? Run codex instead.

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
CommandWhat it does
raytrace auth login|status|logoutSign 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 listList 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 helpShow 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/cli

Signing 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.

A recorded action is not proof of a correct outcome. A successful exit code confirms how a process ended. Missing evidence means unknown. RayTrace does not recover a model’s private chain of thought.

Learn how to read tool categories and sandbox labels →

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.

CategoryWhat it meansExamples
ReadLooked at the contents of a file.Read, cat, head, sed -n
SearchLooked for files or text, or listed what is there.Grep, Glob, rg, find, ls
WriteCreated or replaced a whole file or folder.Write, echo … > file, cp, mkdir
EditChanged part of an existing file, or its permissions.Edit, apply_patch, sed -i, chmod
Delete / moveRemoved, renamed or moved files.rm, mv, a patch that deletes a file
RunExecuted a script or program.sh check.sh, python tool.py, node server.js
TestRan tests, a linter or a type check.pytest, npm test, tsc, eslint
Build / installBuilt the project or fetched its dependencies.npm install, pip install, make, cargo build
GitVersion control.git status, git commit, gh pr create
WebReached the network.WebFetch, WebSearch, curl, wget
PlanOrganised its own work, or asked you something.TodoWrite, update_plan, AskUserQuestion
DelegateHanded work to another agent or an outside tool.Task, Skill, any MCP tool
Not sureRayTrace 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 cd and export, 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.txt is 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.

LabelWhat it meansHow it is decidedWhat to do
✓ ranThe 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, differsThe 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.
✗ rejectedThe 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 seenA 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 changedThe 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 changeThe 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 agentA 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 coveredRayTrace 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.

Separate sandboxEvery project runs in its own isolated workspace
No provider key insideModel calls use RayTrace’s controlled bridge
Observed evidenceKept separate from what the agent reports

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.

Review your project before uploading. Automated exclusions cannot detect a secret pasted directly into an ordinary source file.

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.

Read the detailed privacy and release scope →