Mira for Developers

Step 1 — Install a coding agent

Install any one of the following. Each uses a subscription or API key you already have, and any of them works with Mira.

• Claude Code — follow its installer, then run claude once and sign in when the browser opens.
• Codex CLI — install, run codex once, and sign in.
• Qwen Code — install, run qwen once and sign in (Qwen OAuth free tier), or set an OpenAI-compatible API key.
• OpenCode — install, then configure a provider with opencode auth login.

Most require Node.js first; each tool's page says so and will tell you if it is missing.

Step 2 — Produce your token

Open a terminal. On Mac, press ⌘+Space, type Terminal, and press Enter. On Windows, click Start, type PowerShell, and press Enter. Then run the command for your coding agent.

• Claude Code: claude setup-token — a browser page opens; click Authorize, then copy the token it prints (it starts with sk-ant-oat…).
• Codex: codex login signs you in and stores your key; an existing Codex or OpenAI API key also works.
• Qwen Code or OpenCode: use the OpenAI-compatible API key for the account the CLI is configured with.

The token comes from your own account and runs on your subscription. A Claude token is valid for a year and can be revoked by generating a new one.

Step 3 — Enter it in Mira (recommended)

Mira holds the token and runs the worker for you, so your computer can be closed afterward and your runs still complete.

1. Open Settings (the gear) → Account & Credits → Developer mode.
2. Choose your coding agent (Claude Code, Codex, Qwen Code, or OpenCode) and paste the token into the box.
3. Click Save token & turn on developer mode.
4. Within a minute the panel shows connected. Atelier runs and new-file processing now run on your subscription, at no Mira credit cost.

The token is stored encrypted on Mira's server and is not shown again. Remove it from the same panel to turn developer mode off.

Alternative — run the worker on your own machine

If you would rather the token never leave your computer, run the worker locally instead. Your machine must stay on for your runs to work, but the token stays with you.

1. In Mira: Settings → Account & Credits → Developer mode → connect my own machine.
2. Copy the command it shows and run it in your terminal. It installs a small helper that starts with your computer and connects through your local coding agent.

If developer mode isn't working

• "command not found" (claude, codex, qwen, or opencode): the tool isn't installed yet (Step 1), or you need to open a new terminal window after installing.
• The browser said "this site can't be reached" after Authorize: the terminal command was closed too early. Run it again and leave the terminal open until the token prints.
• The panel still shows offline after a minute: reopen the Developer mode panel; if it stays offline, the token may have been pasted incompletely. Generate a fresh one and paste the whole line.
• If you are stuck, a small amount of Mira credit works with no setup and includes technical support.

Step 0 — Check your machine

Two numbers decide everything: memory (RAM) and free disk space. Check both before downloading anything.

• RAM, Windows: Ctrl+Shift+Esc → Performance → Memory. Mac: Apple menu → About This Mac → the Memory line.
• Free disk, Windows: File Explorer → This PC → the bar under Local Disk (C:), e.g. "41.2 GB free of 237 GB". Mac: Apple menu → About This Mac → Storage.

The minimum is 16 GB of RAM and 30 GB of free disk. Docker Desktop needs several GB, Mira's application images roughly 10–15 GB, the model another ~3 GB, and your library needs room to live. Below either number, use the other options.

Step 1 — Get the Mira code

GitHub is a website where open-source code lives; you do not need an account to download. Mira ships as two repositories that must sit side by side in the same parent folder, with these exact names.

1. Make a folder for everything, e.g. Documents\mira-deploy.
2. Open github.com/MarxReader → the Mira repository → the green Code button → Download ZIP. Unzip it into your folder and rename the unzipped folder to exactly Mira (the ZIP names it something like Mira-main).
3. Do the same for the Mira-intake repository, renaming it to exactly Mira-intake.
4. You should now have mira-deploy/Mira and mira-deploy/Mira-intake side by side. The build file expects the intake folder at ../Mira-intake, so the names and layout matter.

Step 2 — Install Docker and start the app

Docker is a free program that runs applications in self-contained boxes, so you do not have to install databases or programming languages yourself. One installer, and every part of Mira, including its own bundled model server, runs inside it.

1. Download Docker Desktop (Windows or Mac), run the installer, and start it. First start takes a minute.
2. Open a terminal inside the Mira folder. Windows: right-click inside the folder → Open in Terminal. Mac: open Terminal, type cd  (with a trailing space), drag the Mira folder into the window, and press Enter.
3. Create the settings file the app expects (a copy of the provided example; you do not need to edit it to start):

4. Start everything:

5. The first start builds the application and downloads its parts, so expect 20–40 minutes and a lot of scrolling text. Every later start takes seconds. When it settles, open http://localhost:3001, which is your Mira.
6. Create your account there. The first account on a fresh deployment is the administrator, which is you.

Step 3 — Download a model

The stack you just started includes its own model server (a service called mira-local-llm, running Ollama inside Docker), so you do not install anything else; you tell it to download a model. In the same terminal:

That downloads the small model (~2.6 GB) into the stack, where Mira can reach it. Installing Ollama separately on your computer does not work, because the app runs inside Docker and cannot see programs installed outside it.

With an NVIDIA GPU, also try docker compose exec mira-local-llm ollama pull mistral:7b (~4.4 GB) for better quality. Do not bother on a CPU-only laptop.

Step 4 — Point Mira at your models

1. In your Mira (the localhost tab), open Settings (the gear) → Server.
2. Click the Mira Server card → Use Mira Server. Out of the box this points at the bundled model server you just pulled a model into, so there is nothing to configure. The setting saves to your profile, and every run now executes on your machine at $0 per token.
3. Verify: the mode×model matrix at the bottom of that page shows which model each stage will use, and the status strip in the Mira Server section shows the server answering.

Pointing at a different model server

Mira can point at any model server you choose: a PC with a big GPU on your home network, a GPU machine rented through the Small Grants & Assistance programs, or a model server your university already runs.

1. Settings → Server → the Mira Server section → open Advanced → Server address.
2. Paste the server's address. Ollama servers end in :11434 (e.g. http://192.168.1.20:11434); OpenAI-compatible servers such as vLLM usually end in :8000. Pick the matching type.
3. Click Save & test. Mira confirms the server answers and uses it for every local-model call from then on; Reset to default returns to the bundled server.

If self-hosting isn't working

• "docker: command not found": Docker Desktop isn't running yet. Start it (the whale icon), wait for "Docker Desktop is running", and try again.
• Build fails mentioning ../Mira-intake: the second download from Step 1 is missing or misnamed. Both folders must sit side by side and be named exactly Mira and Mira-intake.
• "no space left on device" or the build dies partway: you are below the 30 GB bar from Step 0. Free disk space or use another option.
• "Mira Server unreachable" when switching modes: the model server hasn't finished starting, or no model is pulled yet (Step 3). Check with docker compose ps (it should list mira-local-llm as running), then Settings → Server → Advanced → Server address → Save & test.
• The page at localhost:3001 doesn't load: look at the terminal. If text is still scrolling, it is still starting. If it stopped with an error mentioning "port", another program is using the port; close it or restart your machine and retry.
• Model answers are very slow: expected on any machine without a discrete GPU. Close heavy programs; if it is unusable, your machine is below the realistic bar above.
• If you are stuck, developer mode above and the credits options work with no installation, and Mira credits include technical support.
• For setup help, write to [email protected].