---
name: penumbra-setup
description: Install and verify the Penumbra CLI, help a user sign in, and connect an assistant to their Penumbra project through CLI or MCP. Use when the user asks to set up Penumbra or connect their agent.
---

# Set up Penumbra

Help the user reach a working Penumbra connection: install once, authenticate through their browser, choose a project, verify access. Installing a client or adding an MCP address does not grant access; the user approves the connection and the server enforces its permissions.

## Choose the setup path

| The user wants | Use |
| --- | --- |
| An agent to work for them | CLI installation, then a revocable `penumbra connect` connection |
| Their own terminal signed in | CLI installation, then personal `penumbra login` |
| An assistant's remote MCP connector | The MCP section; CLI installation is optional |

Follow the requested path rather than installing every integration. For an agent connection, use a separate named profile such as `penumbra-agent`; don't replace the person's stored login. Reuse that profile only when it already holds the intended agent connection and cell.

## Use current product instructions

This skill is served at https://app.pnbr.io/skills/penumbra-setup/SKILL.md. If a saved copy appears stale, read that URL before installing. Its CLI version comes from the release this App serves. After installation, `penumbra --help`, command-specific `--help` and `penumbra guide` describe the installed CLI. Use those for details and project work; don't invent flags or configuration files.

## Check the current setup

Check the operating system and, if present, `penumbra --version`. The CLI release is 0.28.0. It runs on macOS, Linux and Windows. Reuse a working installation. On any other system, tell the user the CLI isn't available there yet; don't install it through Node.js or npm.

Preserve existing credentials, named profiles and `penumbra.json`. Inspect the selected cell/project before changing it. Do not use a project-specific web link as a signup or installation link. Public guides: https://app.pnbr.io/cli and https://app.pnbr.io/mcp.

## Install the CLI

### Install (macOS and Linux)

Run `curl -fsSL https://app.pnbr.io/install.sh | sh`. The installer opens the user's browser for sign-in; the user chooses Continue installation to return authorization to the waiting terminal. Downloads remain gated. On a remote terminal, set `PENUMBRA_INSTALL_NO_BROWSER=1` for the code-paste fallback and let the user enter the code in their own terminal. Never copy browser cookies, service tokens or passwords. The installer detects the processor and system, verifies the archive checksum and, on macOS, the Developer ID signature.

### Install (Windows)

In PowerShell, run `irm https://app.pnbr.io/install.ps1 | iex`. It works the same way: browser sign-in, `$env:PENUMBRA_INSTALL_NO_BROWSER = '1'` for the code-paste fallback, checksum verification. It installs `penumbra.exe` for the current user without administrator rights and adds its folder to the user's PATH; terminals opened earlier need to be reopened. Inside WSL, use the macOS and Linux command instead.

After installing, confirm `penumbra --version` reports 0.28.0 and continue to the connection section below. `penumbra update` updates this installer-managed distribution using a personal sign-in; `--profile <name>` selects that sign-in. An agent connection or project key does not authorize downloading releases: run the install command again and let the person complete browser sign-in. Interactive terminals show cached update notices; scripts and JSON output do not. Set `PENUMBRA_NO_UPDATE_CHECK=1` to disable notices and background checks.

## Connect the agent with the user's approval

An assistant working for a person uses a revocable agent connection. Start:

```sh
penumbra connect --profile penumbra-agent --base-url 'https://api.pnbr.io'
```

Keep the process open while the user completes sign-in and chooses projects/permissions in their browser. Give them the authorization URL printed by the CLI. On a remote/headless machine, use `penumbra connect --device --profile penumbra-agent --base-url 'https://api.pnbr.io'` and follow the printed device instructions. The user enters any required device code in their own terminal. Do not collect passwords, API keys, tokens or device codes in chat, or approve access for them.

If the user instead wants their personal terminal signed in, use `penumbra login --base-url 'https://api.pnbr.io'` (or `--device` without a browser). Personal login is different from granting an agent access. A new user must first open https://app.pnbr.io/ and finish account/workspace setup; team invitees should accept their invitation with the invited email. Let the user complete signup, terms and consent.

For the agent path, keep `--profile penumbra-agent` on subsequent CLI commands. List available projects with `penumbra projects list --profile penumbra-agent` (omit that flag for the personal default profile). If no project is selected, ask which one to use when multiple are available. `penumbra use <organization>/<project> --global --profile penumbra-agent` selects the agent profile default without writing a repository file. Keep an existing reachable selection unless the user asks to switch. A repository's `penumbra.json` takes precedence. Don't invent project IDs or copy someone else's personal project URL.

## MCP, when requested

The main remote MCP resource is https://api.pnbr.io/mcp. Add it through the assistant's supported connector settings, then have the user sign in and approve its projects and permissions. Restricted Kits have their own addresses; don't substitute a Kit host for the main resource.

For Claude Code:

```sh
claude mcp add --transport http penumbra 'https://api.pnbr.io/mcp'
claude mcp login penumbra
```

Inspect an existing server named `penumbra` before adding or replacing it. Don't alter unrelated connector configuration. For other assistants, use their supported remote HTTP MCP setup rather than guessing a config file. Use https://app.pnbr.io/mcp for the human-readable guide.

## Verify and hand back

Run `penumbra whoami --profile penumbra-agent` and `penumbra status --profile penumbra-agent` for the agent path; omit the profile flag for the personal default profile. Confirm the intended cell, credential kind and project, and report any missing access plainly. For MCP-only setup, confirm the connector is authenticated and can list its available tools. Read `penumbra guide` and `penumbra --help` before project work.

Report the installed version, selected project, connection method and any remaining browser approval. Setup itself should not upload files, change project content, create API keys or run paid inference. If a command fails, read its error and next step before retrying; don't repeatedly launch authorization flows or overwrite working credentials.