From signing up to your first agent.

Create your account.

Luma World is open to everyone. Create an account on the Luma World website, verify your email, then download.

1. Go to luma.pixelcity.world and press Sign up.
2. Continue with Google, continue with GitHub, or create an account with your email and a password.
3. If you signed up with email and password, verify your email — see below. Signing up with Google always counts as verified; with GitHub it counts as verified only if GitHub itself reports that address as verified.
4. Once you are signed in and verified, the website's main button reads Download.

Sign in on the website and verify your email

To download, sign in on the website with the email you signed up with. Use Continue with Google, Continue with GitHub, or sign in with that email and a password.

The download page then asks you to confirm that the email is yours:

1. Open Get Luma World (the Download button takes you there). If your email is not verified yet, it says Verify your email and sends you a verification link.
2. Open the link in that email.
3. Come back and press I've verified my email. If nothing arrived, press Resend email.

If you signed in with Google, your email already counts as verified and you go straight to the downloads. Signing in with GitHub usually does too, but only if GitHub itself has confirmed that address — if it has not, you will still see the verification step.

Download the right build for your Mac.

The Get Luma World page offers macOS builds today. Windows and Linux are built into Luma World already, but have not been published yet.

The page tries to tell which Mac you are on and marks that build Recommended for this Mac. If you are not sure which chip you have, open the Apple menu and choose About This Mac. If it says Chip: Apple M…, you have Apple silicon. If it says Processor: … Intel …, you have an Intel Mac.

Press the button for your build. The page shows Preparing your download…, then the version and size, and your browser starts downloading a file named like Luma-World-1.4.0-arm64.dmg (Apple silicon) or Luma-World-1.4.0-x64.dmg (Intel). The app is about 230 MB.

Install and first launch.

macOS is the build available today. Installing is the usual Mac drag and drop.

macOS

1. Open the file you downloaded. A window opens with Luma World and your Applications folder.
2. Drag Luma World into Applications.
3. Open Luma World from your Applications folder, Launchpad or Spotlight. The first time, macOS asks you to confirm opening an app downloaded from the internet. Choose Open.
4. Eject the Luma World disk image from the Finder sidebar. You no longer need it.

macOS asks for permission the first time Luma World needs something:

• The microphone, the first time you use voice, for example the Speak button or talking to the office.
• Folders such as Documents, Desktop or Downloads, the first time your agents work in a project folder there. Allow it, or your agents cannot read that project.

What you see the first time

1. Sign in. See Signing in below. The app then shows checking your access for a moment.
2. Pick your handle. New accounts choose a handle once. It becomes part of every agent address you create. Press claim handle.
3. Choose your theme. Dark, Light, Creme, Nord or Monokai. You can change it later in Settings → Appearance.
4. A short Pixel City title card. The first time, it plays to the end. After that it has a skip button.
5. The welcome film. A short film that shows what Luma World is. It plays each time you open the app; press Skip ▶ in the bottom-right corner to go straight on.
6. The setup screen, only if neither Claude Code nor Codex is ready on this computer. See The setup screen.
7. The globe. You are in. Make a city and a building next; the first ten minutes walk you through it.

Signing in.

The app uses the same Pixel City account as the website. Sign in with the email you created, verified and downloaded with there — for a new user, do all three on the website first.

• Google or GitHub: press the button, finish signing in in the browser window that opens, then come back to the app. The app shows complete sign in while it waits, with a cancel button.
• Email and password: if you already made this account on the website, type it here to sign in. Pressing create one directly in the app refuses a brand-new address that has not yet been through Create your account and a download on the website — for a new user, create one at pixelcity.world (which opens the website) is the reliable way in.
• Forgot your password? The sign-in screen can send you a reset link.

Your first sign-in needs an internet connection. After that, Luma World can open while you are offline: it says You're offline, and your agents and local tools keep working.

How your agents run.

Every agent in Luma World is a real Claude Code or Codex session running on your computer, on the plan you already pay for. You need at least one of the two tools. You do not need both.

If you do not have a subscription, an API key can stand in: an Anthropic key for Claude Code, or an OpenAI key for Codex. The tool still has to be installed. See Using an API key instead.

Which versions work with Luma World is on its own page: Supported CLI versions.

The setup screen

Each time you open the app, Luma World checks whether Claude Code and Codex are installed and signed in. While it checks you may see Checking your setup…. If at least one is ready, you go straight to the globe. If neither is, you see Set up an agent runtime: one card for Claude Code and one for Codex. This screen cannot be closed; it goes away by itself as soon as one of the two is ready.

• Codex installs in one click: the app downloads the official OpenAI release, checks it, and sets it up for Luma World.
• Claude Code is installed by Anthropic's own installer, which the app runs for you in the terminal inside the card.
• Already installed one yourself in Terminal? Press Check again and the app finds it. It also checks again whenever you come back to the window.

Using an API key instead

On the setup screen, press Have an API key instead? to open Use an API key. It shows the same AI settings you find later under Settings → AI. Paste your key under Your keys, then press ← Back.

• An Anthropic key lets an installed Claude Code run without a Claude sign-in.
• An OpenAI key lets an installed Codex run without a ChatGPT sign-in.
• Your subscription always comes first. A key is only used for agents when the tool is not signed in.
• Keys stay on this computer, in your settings, and are sent only to the service they belong to. Work done with a key is billed to that key's account, not to your subscription.

When one tool is missing

Having only one of the two tools is fine. The app simply stops you from starting an agent on the one you do not have, and tells you how to fix it:

• In the New Agent dialog, the models of the missing tool are greyed out under a note such as ⚠ Codex isn't installed with an Install button, or ⚠ Claude Code isn't signed in with Sign in. The same note appears in the agent's model menu and in the + New menu of the agent list.
• An agent whose tool has gone missing shows a card instead of a terminal, for example Claude Code isn't installed, with the install command and Check again. See When a screen will not start.
• Settings → AI → Agent runtimes always shows both tools as Ready, Needs sign-in or key or Not installed, with an install or Sign in button and a command you can paste into a terminal instead.

Which features need which keys.

Agents only need Claude Code or Codex. A few of Luma World's own features also use AI. For those the app again tries your sign-ins first, and an API key fills any gap.

A tool that needs something you have not set up keeps its tab, but shows a locked card with one button that fixes it. Which text connection the Architect and the Circle use is chosen under Settings → AI → Language model (LLM). The card may name Claude, but any text connection you set up there works; if its fix is not the one you want, pick another connection there instead. If only the Architect's voice is missing, you can still type to it: Join muted stays open, and a small Voice is locked card offers Sign in with ChatGPT or Add OpenAI key.

Settings → AI also lets you choose, for each kind of AI work (Realtime, Language model, Voice to text, Text to speech, Embeddings), which service and sign-in it uses. More in Who pays for what.

Updates.

When a new version is out, Luma World tells you. Updating is a fresh download of the new build.

1. A card appears in the bottom-right corner: Update available, for example v1.4.1 is out — you're on v1.4.0.
2. Press Download. Your browser downloads the new build for this computer. If that does not work, the Get Luma World page opens instead.
3. Quit Luma World, open the new file, and drag Luma World into Applications, replacing the old one.

Your cities, buildings, agents and settings are kept: they live in your account and on this computer, not inside the app. Press ✕ on the card to hide it until you next open the app.

To see which version you have, choose Luma World → About Luma World in the menu bar. The status bar at the bottom of an open building also shows it, for example v1.4.0.

Getting help.

• This guide explains the office, screens, sub-agents and the Circle, each with a short video.
• Support: pixelcity.world/support answers common questions and tells you how to reach us.
• Privacy policy: pixelcity.world/privacy.
• Terms of use: pixelcity.world/terms.

Common questions.