Installation & Setup

By the end of this page, you’ll have Viberia installed, your CLI providers configured, and the app ready for its first launch tutorial.

Prerequisites

Before you install Viberia, gather the following:

• A Mac running macOS. Viberia ships as a .dmg for macOS today; Windows and Linux builds are in development and not yet available for download.
• At least one of the supported CLI providers installed and signed in:
  • Anthropic Claude CLI (the primary provider — recommended for first-time users)
  • OpenAI Codex CLI
  • Google Gemini CLI
• A folder where Viberia can store its own data and where your projects can optionally live. Most users let Viberia create a ~/Viberia/ directory the first time it runs.

Note: You only need one CLI provider to get started. Viberia will let you add the others later from Settings. If you don’t already have a CLI installed, install one before continuing — the loading screen will not pass until at least one binary is detected.

1. Download and install

Grab the latest Viberia release from the distribution channel you were given. The build artifact is a .dmg for macOS.

Open the .dmg, drag Viberia.app to your Applications folder, then double-click it. The first time you launch, macOS may show a security prompt because the binary is new — allow the app to open.

2. The first launch sequence

The very first launch differs from subsequent launches. Here’s what to expect.

The loading screen

A loading screen appears for at least a second and a half with a rotating set of tips. Behind the scenes, Viberia is starting its local services and detecting your CLI providers. The screen will dismiss itself once the app is ready — there’s nothing to click.

If the loading screen never goes away, see Troubleshooting → engine not starting.

The tutorial trigger

On a fresh install, the Chief of Staff drawer slides open and the tutorial begins automatically. The tutorial is a 14-scene walkthrough that:

1. Welcomes you and asks which CLI providers you want to enable.
2. Lets you pick a visual theme.
3. Asks you to opt into anonymized analytics (you can decline).
4. Offers a Guided path (use your own folder) or a Quick path (a sandbox folder Viberia creates at ~/Viberia/Tutorial-Demo/).
5. Walks you through creating your first project, dropping HQ, setting up a team, and running a real first task.

If you’d rather skip the tutorial for now, dismiss it — you can re-run it any time from Settings → Tutorial. See Your First Project for a written walkthrough of the same flow.

3. Configure your CLI binaries

If the tutorial didn’t already capture them, set the paths to your CLI binaries explicitly. Open Settings → CLI Configuration and verify each provider you intend to use.

Provider	Setting field	Typical path
Anthropic Claude	Claude CLI path	/usr/local/bin/claude or ~/.local/bin/claude
OpenAI Codex	Codex CLI path	/usr/local/bin/codex
Google Gemini	Gemini CLI path	/usr/local/bin/gemini

To find a binary’s path from a terminal:

which claude
which codex
which gemini

Paste the output into the corresponding field. Each provider has a Test button next to its path field — click it to confirm Viberia can invoke the CLI. A green check means the binary responded; a red error means the path is wrong or the CLI isn’t installed.

For provider-specific details (sign-in, models, defaults), see the dedicated integration pages:

• Anthropic Claude
• OpenAI Codex
• Google Gemini

Note: If you change a CLI binary path while agents are running, restart Viberia so every agent picks up the new path.

4. Grant Full Disk Access

Viberia’s agents read and write files in folders you choose, and they invoke CLI binaries that themselves need to reach across your filesystem. macOS requires Full Disk Access for this to work.

To grant it:

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Click the + button and select Viberia.app from your Applications folder.
3. Toggle Viberia on in the list.
4. Quit and relaunch Viberia.

If you skip this step, agents will silently fail on file operations, and the tutorial’s first real task (“Add a button that says ‘Hello, Viberia’”) will not produce any files. You can verify the setting later in Settings → Permissions, which shows the current access state.

5. Set your default permission mode

Open Settings → Permissions. Viberia ships with two modes:

• Standard — every tool call from an agent prompts you to Allow or Deny. You can also choose Allow always to auto-approve that tool for that agent for the rest of the session. This is the default and the recommended starting point.
• YOLO — every tool call is auto-approved. Use this only for sandboxed or throwaway projects where you trust every agent in the project.

You can change the mode globally or per agent. For details, see Permission Modes.

6. Verify your setup

Run through this checklist before moving on:

• The loading screen completes and the world map appears.
• The HudShelf is visible along the bottom with a New Project button.
• The Chief of Staff drawer tab is visible on the right edge.
• Settings → CLI Configuration shows at least one provider with a green check.
• Settings → Permissions shows Full Disk Access granted.

If any of these are missing, see Troubleshooting — most first-launch issues are covered there.

What just happened

You’ve installed Viberia, taught it where your CLI providers live, and granted the OS permissions agents need to do real work. The app is now ready to host projects, buildings, and agents that read and write files on your behalf.

Next: Your First Project