Docs · Install
Install Lyriks, then fix what goes wrong.
Four steps: get your key, run one command, claim your installation, connect your agent. The usual problems are listed at the end.
Step 1
Get your key
Ask for a free Community licence key on the Get started page: an address is all it takes. The mail comes from support@lyriks.io, usually within a minute, and carries the key and the command below. Keep the key private, as you would a password.
It goes to that address and to no other, because the key names it: your installation later checks the pair, so receiving the mail is what makes the installation yours.
Asking twice is harmless. The same address always receives the same key. Nothing is duplicated, and no second licence is ever issued.
If the email does not arrive
Give it five minutes first, then work down this list.
- Search the whole mailbox for “lyriks”Not just the inbox: Spam, Junk, Gmail Promotions, Outlook Other. A mail carrying a key and a shell command is exactly what a filter puts aside.
- Re-read the address you typedOne wrong letter and the key went to a mailbox that is not yours. Ask again with the right one.
- Ask again from the formThe same address always receives the same key. Three sends an hour per address is the ceiling.
- Allow the sender, then ask againAdd support@lyriks.io to your contacts or allow list. On a company mailbox, the mail is often quarantined by a rule you never see.
- Try an address you own personallyIf a corporate filter is eating it, a personal address proves it in a minute. The licence names the address, so choose deliberately.
- Write to usMail support@lyriks.io. A person reads that mailbox, can see whether the key was issued, and re-sends it by hand. You can also ask on our Discord, the link is just below the FAQ.
Installing while you wait is fine. The command needs no key, and the appliance comes up and waits. A Community install stays closed until the mail lands.
Step 2
Run one command
No folder to make, no flags to pass, no account to create. Run it from wherever your terminal opens: the installer creates its own folder, ~/lyriks, in your home directory and installs everything there. Pick your system.
Linux & macOS
In a terminal:
$ curl -fsSL https://get.lyriks.io | shRun it as yourself, not with sudo: it asks for your password itself, only for the steps that need it (installing Docker, letting your user use it, a kit directory outside your home). Docker missing? It is proposed, and the official Docker install script runs only after you consent (it will ask for your password). On macOS the same question installs Docker Desktop: through Homebrew when you have it, otherwise straight from Docker's own installer. A Mac on macOS 12 or 13 gets the last Docker Desktop that still runs there, installed the same way.
Windows
In a normal PowerShell window, not an administrator one: Lyriks must land in your own session, next to the browser you will use it from.
> irm https://get.lyriks.io/windows | iexLyriks runs Linux containers, so Windows needs WSL2 and Docker Desktop. Both are proposed (through winget) and each waits for your consent. Installing WSL needs one administrator window and a reboot, after which you run the command again from a normal window. You never have to touch WSL yourself: the script hands over to the Linux installer inside your distribution and Lyriks ends up at ~/lyriks in there, used from your Windows browser.
The one thing it asks you. Before downloading anything, the installer offers to take your licence key if you already have it. Press Enter to skip: the claim screen asks for the key either way, so nothing later depends on answering here.
What the command does, in order
- Checks the machineArchitecture, operating system, Docker and Docker Compose. Nothing is downloaded before the checks pass.
- Proposes what is missingEach install is named and waits for your consent. Prefer to do it your own way? Decline, install it, run the command again.
- Fetches the appliance and installs itThe kit lands in ~/lyriks, then runs its own doctor and install: containers, database, everything.
- Proves the install worksA smoke test runs last. Success is announced only after it passes, so a green message means a working appliance.
- Tells you where to goYour Lyriks is at http://localhost:3000, ready to be claimed.
Want to see it first? Both scripts are plain text, here: install.sh and install.ps1. And --dry-run prints every command the installer would run, without running any of them.
Useful variants
--yesconsents to every proposed install up front (Windows:$env:LYRIKS_YES = '1'before the command).--port 8080serves Lyriks on another port (Windows:$env:LYRIKS_PORT = '8080').--license-key lyk_...activates the licence during the install (Windows:$env:LYRIKS_LICENSE_KEY = 'lyk_...'). Optional, and it does not shorten the claim: that screen asks for your address and your key either way.--reinstalldestroys an existing install, data included, then installs fresh. Without it, re-running repairs in place and keeps your data.
Flags go after sh -s --, like this: curl -fsSL https://get.lyriks.io | sh -s -- --yes --port 8080.
Step 3
Claim your installation
The installer creates no account and asks for no identity, on purpose: the person who owns the licence is the person who claims the box. Open http://localhost:3000. Under Claim this installation:
- Your address and your keyThe address the licence was issued to and the key itself. Both are checked against each other, and the key never leaves the machine.
- Your passwordChoose it now. This creates the administrator account, signs you in, and closes the claim window for good.
Claim it before anyone else can. On a machine others can reach, the first person to open a fresh install is the one who claims it. Do this step right after installing.
Day one
Once you are in
Connect your AI client
Lyriks speaks MCP, so your assistant can read and author your projects directly. It is optional: Lyriks works exactly the same without it. Register it once for your machine, not for one folder.
$ claude mcp add --scope user --transport http lyriks http://localhost:3000/mcpClaude Code
$ codex mcp add lyriks --url http://localhost:3000/mcpOpenAI Codex
$ gemini mcp add --transport http lyriks http://localhost:3000/mcpGemini CLI
Cursor, Windsurf and other clients configured by file take the same URL, http://localhost:3000/mcp. Then sign in: there is no token to copy, the client opens your browser on the Lyriks sign-in page, you click Allow access, and the connection is kept from there.
Then follow the First steps to check the connection and write your first spec.
Manage the install
Everything happens from the kit directory, ~/lyriks:
./lyriks statusshows what is running,startandstopdo what they say../lyriks updatemoves to the current release, keeping your data, and./lyriks rollbacksteps back../lyriks backup createtakes a backup you can restore later../lyriks destroy --confirmremoves the stack and its data. That one is final.
After a reboot
Nothing to launch. Lyriks restarts with Docker, so the whole appliance comes back on its own. The only thing that has to start is Docker, and only Linux does that for you:
- macOS: open Docker Desktop (Cmd+Space, type Docker, Enter). It is ready when the whale in the menu bar stops animating.
- Windows: open Docker Desktop from the Start menu and wait for the whale in the notification area to settle.
- Linux:
sudo systemctl enable --now docker, once, and Docker starts with the machine from then on.
Then reopen http://localhost:3000: same account, same data. Lyriks is not inside the Docker Desktop window: the product is the browser tab, and the containers need a minute before the page answers.
When it goes wrong
The usual suspects
I restarted my machine and Lyriks does not answer any more
Start Docker: it is what your reboot switched off, and Lyriks restarts by itself right after. On a Mac, press Cmd + Space, type Docker, press Enter, and watch the whale icon in the menu bar at the top right until it stops animating. On Windows, open Docker Desktop from the Start menu. Then reload http://localhost:3000, giving it a minute. Nothing appears inside the Docker Desktop window itself, and nothing should: it runs the engine, the app is the browser tab. Details in After a reboot.
Still nothing once Docker is running? The stack was stopped at some point. From Terminal, cd ~/lyriks && ./lyriks up, then ./lyriks status.
The email with my key never arrived
Search the whole mailbox for lyriks, spam and the hidden tabs included, then ask again on the Get started page (lyriks.io/get-started): the same address always receives the same key, so a second request costs nothing. If your company filters mail hard, an address you own personally settles it in a minute.
Still nothing? Write to support@lyriks.io and we send the key by hand. The full list, cause by cause, is in If the email does not arrive.
The claim screen refuses my key
It says which of the four it is, and each has its own fix:
Issued to a different address. The key and the address you typed do not name the same person. Use the address the mail was sent to, spelled exactly as it appears there. Want a different address on the licence? Ask again on the Get started page (lyriks.io/get-started) with that one, and claim with the key that comes back.
Not valid for this installation. Nearly always a copy that lost characters. Copy the key from the mail whole, from lyk_ to the last character, with no space before or after.
The system clock is set in the past. The machine’s date is wrong, so a valid key reads as not yet issued. Correct the date and time, then try again.
Issued under a signing key we have retired, or too old to name an address. Both mean the key is genuine but superseded: write to support@lyriks.io and we re-issue it.
Several wrong tries in a row are throttled for a few minutes. That is the claim screen protecting itself, not your key being refused: wait, then try again.
Docker is installed but the command says it cannot reach it
The daemon is not running, or your user is not allowed to use it yet. The installer tells the two apart: it starts Docker for you, or adds you to the docker group and bridges the rest of the run (with sg docker, or sudo where that cannot work). Group membership takes effect at your next login, so open a new shell before running ./lyriks by hand.
If Docker itself is stopped: sudo systemctl enable --now docker. On macOS and Windows, start Docker Desktop and wait for its whale icon to settle.
Windows: it asks for WSL, or nothing appears in the browser
Say yes to WSL, reboot when asked, let Ubuntu finish its first-run setup, then run the command again. Use a normal PowerShell window, never an elevated one: an elevated install lands in the administrator’s session, invisible from your own browser. If Docker Desktop is running but the distribution cannot see it, enable it under Settings, Resources, WSL integration.
The registry is unreachable
The installer needs outbound HTTPS to registry.lyriks.io. Behind a corporate proxy or a captive portal, that is usually what fails. Authorise the host, or configure Docker’s proxy settings, then run the command again.
Something failed halfway
Run the same command again. Every step reconciles, your data lives in Docker volumes and is preserved, and a repair is the default. Use --reinstall only when you truly want to start from zero, data included.
I installed without a key
Nothing is lost and nothing has to be reinstalled: the appliance is running and waiting to be claimed. What it will not do is open, because claiming asks for your address and your key together. Get the key on the Get started page (lyriks.io/get-started), it takes a minute, then claim the install that is already there. Not arriving? If the email does not arrive walks the causes.
Still stuck
Reply to the email that carried your key: it reaches us. No email to reply to? Write to support@lyriks.io, which is the same mailbox and is read by a person, or ask on our Discord (link below). From inside Lyriks, the Leave us feedback button in the header files the same thing with your versions attached.
Still stuck? Talk to us. Join the team and other users on Discord, or write to support@lyriks.io. You can also use the contact form.