Keystone OS — Quick Start

Just want to use it? (easiest)

Open lantern-os.net in any browser and start typing. That's genuinely it — there's nothing to download and you don't need to sign up to try the chat.

This is the right choice for most people. The rest of this guide is only if you want to run your own private copy on your own machine.

Run your own copy

Running your own copy means you fully own your data and it works offline-first. You'll copy and paste a few commands into a terminal — you don't need to understand them, just run them in order.

A terminal is the text window where you type commands: PowerShell on Windows, Terminal on Mac/Linux. Open it, then cd into the folder where you want Keystone to live.

What you need first

To check what you already have, paste these into your terminal:

node --version

python --version

If a version number prints, you have it. If you see "not recognized" or "command not found", install it from the links above.

Step— Get the code

git clone https://github.com/alex-place/lantern-os

cd lantern-os

(No git? Install it from git-scm.com, or download the project as a ZIP from the GitHub page and unzip it.)

Step— Install

# Required — installs the app

npm install --prefix apps/lantern-garage



# Optional — only if you want the Python-based extras later

python -m pip install -r requirements.txt

Step— Add one AI key

Keystone talks to an AI provider on your behalf. You need one key. It tries them in order and automatically switches to a backup if one is down, so a single key is plenty to start.

First, make your own settings file from the example:

copy .env.example .env      # Windows (PowerShell)

cp .env.example .env        # Mac / Linux

Then open .env in any text editor and paste in one key:

ANTHROPIC_API_KEY=sk-ant-...    # Claude — best quality

GEMINI_API_KEY=AIza...          # Google Gemini — has a free tier, easiest to start

OPENAI_API_KEY=sk-...           # ChatGPT / GPT-4o

Keep your key private. It's like a password for your AI account. Don't share your .env file or post the key anywhere. .env is already ignored by git so it won't get committed.

Step— Start it

npm run dev --prefix apps/lantern-garage

Now open http://127.0.0.1:4177 in your browser.

You'll land on the Keystone home page. Click Chat and type anything to start a conversation. 🎉

To stop the server, go back to the terminal and press Ctrl + C.

What's where

Once it's running on http://127.0.0.1:4177:

Optional extras

You can skip all of this — the chat works without any of it. Come back when you're curious.

Run two copies at once (for tinkering)

Handy if you want to experiment without breaking your working copy: one stable copy on port 4177, and a second "playground" copy on port 4178. If Python is installed, the MCP server also starts automatically on port 8771, shared by both web servers.

pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/Start-DualServers.ps1

• Port 4177 — your stable copy (the master branch)
• Port 4178 — your playground (your current branch, auto-reloads as you change files)
• Port 8771 — MCP server (shared, tools for Claude Code) (requires Python)

On startup this also installs the monoworkstream git hooks (contributors only) — the dynamic per-lane PR gate: alex/, kriskin/, mookman11/, or any <name>/ branch each get one concurrent PR lane, plus the slop + change-record checks. Nothing to do manually.

(If you happen to have make installed — it isn't on Windows by default — make quickstart does the same thing.)

Start automatically when your PC turns on (Windows)

# Run once, in a PowerShell window opened "as Administrator"

.\scripts\Start-Lantern.ps1 -RegisterAutostart

After this your computer starts Keystone on its own every time it boots, and restarts it if it ever crashes. Admin is only needed this one time to register the task.

To undo it later:

.\scripts\Start-Lantern.ps1 -UnregisterAutostart

Logs are saved to logs\lantern-autostart.log.

Voice (text-to-speech)

• Browser voice works out of the box in Chrome and Edge — no setup.
• ElevenLabs (more natural voices): add ELEVENLABS_API_KEY and ELEVENLABS_VOICE_ID to .env.

Discord bot

Add these to .env and the bot starts with the server:

DISCORD_BOT_TOKEN=your_bot_token

LANTERN_DISCORD_GUILD_ID=your_server_id

Voice playback needs ffmpeg: winget install Gyan.FFmpeg.

Tools for AI agents (MCP)

The MCP server starts automatically when you run the dual-boot launcher (if Python is installed):

pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/Start-DualServers.ps1

This launches:

• Port 8771 — MCP server (shared by both web servers, tools for Claude Code)

If you want to run the MCP server standalone on port 8771:

python src/mcp_server/server.py

The MCP server lets coding assistants like Claude Code call Keystone's tools — you only need it if you're using the Claude Code IDE extension or web app with this project.

Share it on the internet (advanced)

You can expose your local Keystone to the public web with a Cloudflare tunnel. See docs/CLOUDFLARE-TUNNEL-DEPLOYMENT.md.

⚠️ Read this first. Putting Keystone on the public internet means anyone with the link can reach it, not just you. Only do this if you understand the risk, keep your keys safe, and don't expose admin/trading features to the public. If you're not sure, don't — the local 127.0.0.1 address is private to your machine and is the safe default.

If something goes wrong

Still stuck? Open an issue on GitHub and paste the error you saw.

Running tests (for contributors)

# Python unit tests

python -m pytest tests/ -q --tb=short



# Node API tests — start the server first, then in a second terminal:

npm run test:api --prefix apps/lantern-garage

Go deeper

• Help & Knowledge Center — friendly guides and every doc in one place
• PROVIDERS.md — all the AI providers and how to configure them
• AGENTS.md — how the AI agent workflow and contribution lanes work
• SECURITY.md — the security model and how to report a problem
• docs/CONVERGENCE-LOOP.md — how Keystone reasons under the hood