Skip to main content
This quickstart uses Node.js 22 or later and the published mirrors-sdk@0.7.0. The package supports ES modules and CommonJS, with no runtime or peer dependencies. Use it in your server-side harness. For other languages, use the Python or Ruby quickstart. You will add background capture and optional context retrieval. Then follow the agent harness guide to connect your model/tool loop, streaming, and completion hooks.

1. Copy your agent’s connection settings

No account yet? Sign up free; the Hobby plan needs no card. Working with a coding agent? Point it at mirrors.dev/agents.md. Open your agent in the Mirrors dashboard, then open Agent setup → SDK connection settings. Copy the API URL and generated agent ID together. The agent ID is not the agent’s display name. Create an SDK key for that same agent with runtime:read and runtime:write permissions. Store the three values in your server configuration:
Use the API origin, without /v1 or a runtime route. Keep the key out of browser bundles, source control, and logs. Use connection troubleshooting if the selected environment, agent ID, or key scope is uncertain.

2. Install and create a shared client

Create one client per agent configuration and reuse it across turns. For example, put this in your server’s mirrors.ts module:

3. Prepare the turn’s prompt

Locate the point where your harness has accepted a user message and is about to assemble the model request. Map its full original history to a CanonicalTrace. Give this execution a fresh ID and keep that ID through its model calls, tools, and final capture. This helper prepares a prompt; your existing harness still makes the model call:
Use the returned system prompt immediately for the next model call. Keep baseSystem and stored history unchanged so future captures contain only original evidence. The harness guide shows where to apply the prompt and finalize the turn. captureTrace returns immediately with a delivery ticket. getContext sends its own current snapshot; it does not need you to await capture first. Its total wait budget is up to 1,000 ms, which you can shorten with timeoutMs. Call once before the user turn’s loop; waiting again at each tool step adds delay. A blocked JavaScript event loop can delay timers. Empty context is normal when nothing matches, in shadow/off mode, before the first mode refresh, or on a delivery fallback. Your harness then uses baseSystem.

4. Connect the rest of your harness

Before running real traffic, wire the remaining lifecycle hooks in the agent harness guide:
  • Original-history updates: preserve actual responses, tool calls, and tool results in order; capture full snapshots without injected context.
  • Execution completion: send final: true after the model/tool loop and stream finish, including failure and cancellation endings.
  • Process shutdown: stop admitting turns, await a bounded flush, inspect delivery counts, then dispose the shared client.
For a chat spanning several user turns, each execution gets a new trace ID. Use the conversation identity rules to group those executions under a durable chat ID.

5. Verify in shadow mode

Start in shadow mode. Run a representative test conversation, inspect its final capture receipt, and confirm the conversation appears in Mirrors. accepted with ingestion queued means analysis was queued, not completed. Then review a correction, preview its scope, and enable active delivery deliberately. Verify that the actual model request contains the guidance while stored history stays original. The harness guide includes checks for tool loops, cancellation, and fallback.