---
title: "Ataris documentation"
description: "What Ataris records, how a traced run works, and where to start."
canonical: "https://ataris.dev/docs"
last-updated: 2026-10-12
---
# Ataris documentation

What Ataris records, how a traced run works, and where to start.

Ataris is the tracing layer for autonomous agents. It records what an agent does on one timeline, wherever the agent runs: the tool calls it makes, the processes it starts, the files it opens, the network connections it makes, the credentials it touches, the skills it loads, and the MCP tools it calls.

When a run goes wrong, you open that timeline and see what happened, why, what the agent touched, and whether anything left your environment.

## How a run is traced

1. **You put `ataris` in front of the agent.** `ataris claude -p "…"` or `ataris codex exec "…"`, on a laptop, in CI, on a VM, or inside a sandbox or container you already use. It needs no root. See [Trace an agent CLI](/docs/guides/cli).
2. **The CLI starts a session** in your workspace and runs the agent as it normally would.
3. **Everything the agent does is recorded.** Every process it starts, every file it opens, every network connection it makes, and every credential it touches, including inside the scripts it runs, plus each tool call and its result, the skills it loads, the MCP servers and tools it calls, and the prompt behind the run. It runs on macOS and Linux.
4. **Events stream to the session's timeline** in the dashboard as they happen, and to your code through the SDK.
5. **Causes are linked.** A tool call is tied to the processes it started; a file read is tied to the context that led to it.

There is no agent registration and no tracing code to add. Sessions are tagged with the agent, the repo, and the branch automatically, plus any tags you pass.

## What you can do with it

- **Debug a run.** Replay the context, decision, and command that broke the build.
- **Investigate an incident.** Follow an action back to the instruction that caused it, including one hidden in a README or a fetched web page.
- **Prove what was exposed.** Separate what the agent read from what actually left your environment.
- **See what it reached for.** List the skills the agent loaded and the MCP servers and tools it called in each run.
- **Enforce limits.** On Pro and above, block tool calls with a [policy](/docs/concepts/policies) and see every blocked attempt on the timeline.

## Next steps

- [Trace an agent CLI](https://ataris.dev/docs/guides/cli.md): Put ataris in front of Claude Code, Codex, or Grok to trace it on a laptop, in CI, or in your own sandbox.
- [Quickstart](https://ataris.dev/docs/quickstart.md): Install the ataris CLI, trace an agent run where it already runs, and open its timeline. Every plan.
- [Sessions](https://ataris.dev/docs/concepts/sessions.md): What a session is, how the CLI starts and ends one, its states, and its tags.
- [Trace events](https://ataris.dev/docs/concepts/trace-events.md): Lanes, event kinds, verdicts, flags, resources, and causal links.
- [Policies](https://ataris.dev/docs/concepts/policies.md): Allow, alert, and block rules for files, processes, egress, commands, MCP tools, and skills, and how the CLI enforces them.
- [Trace Claude Code](https://ataris.dev/docs/guides/claude-code.md): Run Claude Code through the ataris CLI on a laptop, in CI, or in your own sandbox.
- [REST API](https://ataris.dev/docs/reference/api.md): Authentication, rate limits, errors, and every /v1 endpoint.