Skip to main content
This quickstart takes you from an API key to a working Mirror CLI session, and ends with a small task that confirms Mirror can read files, edit code, and run tests with Reflection models. Mirror’s built-in Reflection provider selects its endpoint automatically, so it needs only your API key. If you’d rather use a coding agent you already have, Pi, OpenCode, Hermes Agent, and GitHub Copilot in VS Code also work with Reflection models. Choose its tab under Set up your agent, and configure an OpenAI-compatible Chat Completions provider with these values:
Claude Code, Codex, and Cursor can use Beam through Vercel AI Gateway, with an AI Gateway API key instead of a Reflection API key. Run npx vercel ai-gateway setup, then select reflection/beam as the agent’s model. Mirror can use the gateway too, with --api vercel.

Before you start

1

Create an API key

Sign in to the Reflection platform, open API Keys, and create a key. The full key is shown only once, so copy it now. Export it in the shell you start your agent from, or add the line to your shell profile:
2

Check the key

List the models your key can use:
The response lists Beam-1.0-501B-A23B. If you get a 401 instead, see 401 Unauthorized.
3

Create a sample project

Each guide uses the same first task: fixing a failing test in a small Python project. Create the project now; you need Python 3 and Git with your commit identity configured.
Create the sample project
python3 -m unittest fails with AssertionError: 3.0 != 4.

Set up your agent

Mirror CLI is Reflection’s coding agent for the terminal. It uses Reflection and Beam-1.0-501B-A23B by default, so connecting it takes only an API key.

Install Mirror CLI

Mirror CLI runs on macOS 14 or later on Apple Silicon, and on Linux with glibc 2.28 or later on x86-64 or ARM64. Git or Jujutsu is needed for worktree management; you can start a session in a plain directory without either. Native Windows isn’t supported.Install uv if you don’t already have it, then install Mirror CLI:
If your shell can’t find mirror after installing, run uv tool update-shell and open a new terminal.To check for an update, run mirror update in a terminal and accept the installation prompt. You can also upgrade the installed tool with uv tool upgrade reflection-mirror.

Connect Mirror CLI to Reflection

1

Start Mirror CLI

Run mirror in the sample project directory, stats-demo. The first time, Mirror CLI shows a Using Mirror notice. In each new directory, it then asks Continue and trust this folder? [y/N]; type y and press Enter to continue.If you’ve used Mirror CLI with another provider, run /model reflection once it starts. Mirror CLI remembers that choice. mirror --api reflection --model Beam-1.0-501B-A23B selects Reflection for that launch only.If REFLECTION_API_KEY is set or a saved Reflection key is available, Mirror CLI opens the prompt and you can skip the next step. An environment key takes precedence over the saved key.
2

Paste your API key

Without an environment key or a saved key, Mirror CLI opens a Connect to Reflection screen with a link to create one:
Mirror CLI's Connect to Reflection screen, showing the model Beam-1.0-501B-A23B, a link to create an API key, and an API key prompt

The Connect to Reflection screen, with a link to create an API key.

Paste your key at the API key › prompt and press Enter. The input is masked, with one * for each character. Mirror CLI saves the key to ~/.mirror/reflection_api_key, readable only by your user, and uses it in later sessions. It doesn’t check the key when it saves it; if the key is wrong, requests fail with 401, and /logout removes the saved key so you can paste another. Press Ctrl+C to cancel without saving.Like other local credentials, the saved key can be read by any command that runs as your user.
3

Check the model

The welcome screen shows Beam-1.0-501B-A23B next to model.
Mirror CLI's welcome screen after connecting, showing the model Beam-1.0-501B-A23B above the prompt

The welcome screen after connecting, with the model above the prompt.

Run a first task in Mirror CLI

With Mirror open in the sample project directory, enter:
Mirror CLI asks before it runs shell commands, including ones that only read files, and before it edits files. Press 1 or Enter to approve each one. It shows tool activity as it works. When it’s done, use /quit to return to your shell.Review what Mirror CLI reports. The intended fix replaces len(nums) + 1 with len(nums) in stats.py. Confirm the result yourself:
The expected result is passing tests and this one-line change to stats.py:
stats.py
The model can take a different path to the same fix, for example by editing the file with a shell command instead of an edit tool.

Enable web search in Mirror CLI (optional)

Mirror uses You.com for web search and page reading by default. You can choose Tavily or Firecrawl instead with /web-provider. This choice is separate from your model provider.
1

Get a web provider API key

Create an account with your chosen provider and copy its API key. You only need a key for the provider you use.
2

Export the key and start Mirror

For You.com, replace the placeholder with your API key and run these commands in the same terminal:
For Tavily or Firecrawl, export TAVILY_API_KEY or FIRECRAWL_API_KEY instead. If Mirror is already running, exit and restart it from this terminal so it picks up the key.
3

Choose your provider

Run /web-provider to open the picker, which shows whether each provider’s key is set. Choose the provider whose key you exported. Exporting a key alone doesn’t select that provider.Mirror saves the choice as web_provider in ~/.mirror/config.json and applies it to subsequent tool calls. Calls already running finish with their original provider. Without a saved choice, Mirror uses You.com.
4

Ask Mirror to search

Enter a prompt that asks for a web search, for example:
  • Keep the key for future sessions: Add the export line to your shell profile, such as ~/.zshrc for zsh. Open a new terminal before starting Mirror. Keep keys out of project files and config.json.
  • Use the right key: Web provider keys are separate from your REFLECTION_API_KEY.
  • Skip search setup: You can use Mirror for coding tasks without a web provider key. Web search and page reading are available when the selected provider’s key is set. Mirror doesn’t fall back to another provider if a call fails.

Sessions and permissions in Mirror CLI

  • Steer the agent. Type while it works to add instructions, and press Escape to stop the current turn. Type / to browse commands.
  • Pick up earlier work. /resume reopens a saved conversation and /clear starts a fresh one. mirror --continue resumes where you left off.
  • Change the model. /model switches models and providers, and Mirror CLI remembers the choice. /effort sets the reasoning effort; the default is max unless the workspace has a saved effort.
  • Work in parallel. /worktree <name> creates a workspace with its own agent from the remote’s default branch, preferring origin or the sole remote. If fetching fails, it uses the cached default or local committed revision. Your current edits aren’t copied. Switch workspaces with Tab and Shift+Tab.
  • Approve tool calls. By default, Mirror CLI asks before shell commands, including ones that only read files such as ls, and before file writes and edits. Built-in file reading and searching don’t need approval. Press 1 or Enter to approve, or 2 to reject. To approve routine tool calls automatically, press F2, use /approvals, or start Mirror CLI with --approval-mode auto. Tools that require explicit confirmation still ask. Each workspace keeps its approval mode. Tools run locally with your account’s permissions; approval isn’t a sandbox.
The Mirror CLI overview explains how Mirror works, and the reference lists every command and shortcut.

Limits

  • For Pi, OpenCode, Hermes, and GitHub Copilot, configure an OpenAI-compatible Chat Completions provider. The public API supports Chat Completions and Models, not the OpenAI Responses API. Mirror uses its built-in Reflection provider. See OpenAI compatibility.
  • Coding agents can send many model requests while completing a task. These count toward your organization’s rate limits like any other request.

Troubleshooting

The API key is missing, malformed, or not valid. Check that REFLECTION_API_KEY is exported in the shell you started the agent from: run the key check in that shell. If you added the export to your shell profile, open a new terminal or source the profile. See Authentication.If Mirror uses a saved key that’s wrong, run /logout and paste a new key. If Pi prints No models available or No API key found, or OpenCode prints Provide an API key or Playground credential in the Authorization header, REFLECTION_API_KEY isn’t set in that shell. For OpenCode, it can instead be missing from the background service: run opencode service restart from a shell where the key is set. OpenCode reports a wrong key as Incorrect API key provided, without the status code. Hermes shows the same message when the key is unset, and suggests hermes setup; ignore that, because the Hermes guide reads the key through key_env instead. ~/.hermes/logs/errors.log says when REFLECTION_API_KEY is empty or unset. In GitHub Copilot, re-enter the key with Update API Key in Chat: Manage Language Models; Copilot doesn’t read REFLECTION_API_KEY.
  • Check that the model ID is exactly Beam-1.0-501B-A23B, including capitalization. OpenCode reports a wrong ID as The model [<ID>] you requested is unavailable.
  • In Pi, OpenCode, Hermes, or GitHub Copilot, check that the base URL is https://api.reflection.ai/openai/v1, ending in /openai/v1 with no trailing path such as /chat/completions. The agent adds that path itself. With a trailing path, OpenCode prints Provider request failed with HTTP 404: 404 page not found.
  • In Mirror, run /model and select Reflection API, its built-in Reflection provider, or run /model reflection. You do not set a base URL for that provider.
A rate limit was exceeded. Wait and retry the task, or run fewer agent sessions at once. See Rate limits.
Reasoning on a large task can take a while before the first output appears. If requests fail with 502 or 503, or time out repeatedly, retry the task. See Errors.
Every request in a session fails with 400 missing_required_parameter:
The model sometimes returns a tool-call step without reasoning. An agent that sends that step back without reasoning_content gets this error on every later request in the session. If the agent can send custom request headers, set Reflection-Missing-Reasoning-Strategy: auto to have the API accept such steps. Otherwise, start a new session: /clear in Mirror, /new in Pi, or opencode run without -c in OpenCode. In Hermes, check that hermes config get model.reasoning_echo prints true. In GitHub Copilot, check that thinking is true for the model in chatLanguageModels.json, then start a new chat.
  • Check the model name the agent prints when it starts.
  • In Mirror, use /model reflection to change the saved model selection. Launching with mirror --api reflection --model Beam-1.0-501B-A23B uses it for that launch only.
  • In Pi, OpenCode, or Hermes, check the default provider and model in the configuration shown in its guide.
  • In GitHub Copilot, check the model picker in the Chat view.

Share feedback

For Mirror CLI, open the GitHub feedback form. Review your report before submitting and remove private information from any attached logs. See reporting a bug. If a guide on this page doesn’t work for you, keep a note of the agent and its version, your operating system, the command you ran, and the error message. Leave out your API key.
Last modified on November 19, 2026