> For the complete documentation index, see [llms.txt](https://pharaoh.so/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pharaoh.so/docs/setup/headless.md).

# Headless / SSH / CI

Connect Pharaoh in environments without a browser: VPS, containers, SSH sessions, CI pipelines.

**Prerequisite:** [Install the GitHub App](/docs/setup/github-app.md) first.

## Setup

Run the device flow CLI:

```bash
npx @pharaoh-so/mcp
```

1. The CLI prints a URL and a one-time code
2. Open the URL on any device with a browser
3. Enter the code and authorize with GitHub
4. The MCP connection starts via stdio

Requires Node.js 18+.

## Configure with your AI tool

For any tool that supports stdio MCP transport, add this to its MCP config:

```json
{
  "mcpServers": {
    "pharaoh": {
      "command": "npx",
      "args": ["@pharaoh-so/mcp"]
    }
  }
}
```

For Claude Code specifically:

```bash
npx @pharaoh-so/mcp
```

The device flow runs on first connection. After authorization, the token is cached locally.

## Verify

Ask your AI tool:

```
What modules does this codebase have?
```

It should call `get_codebase_map` and return a module breakdown with file counts, function counts, and dependency relationships.

## What happens automatically

* Your AI tool calls Pharaoh tools before making architectural decisions - checking for duplicate functions, understanding callers, mapping module boundaries
* Every push to your default branch refreshes the graph within minutes
* No config files or per-repo setup needed after the initial install
* Pharaoh tools return structured data in minimal tokens so the AI has room to reason

## Troubleshooting

**`npx` fails or command not found:** Ensure Node.js 18+ is installed. Run `node --version` to check. Install from [nodejs.org](https://nodejs.org/) or via your package manager.

**Device code expired:** Codes expire after 15 minutes. Run `npx @pharaoh-so/mcp` again to get a new code.

**Connection works once then fails on restart:** The cached token may have expired. Re-run the device flow to get a fresh token.

**"No repos found" after authorization:** The GitHub App must be installed on the correct org or account. Go to [github.com/apps/pharaoh-so/installations/new](https://github.com/apps/pharaoh-so/installations/new) and verify the installation.

**Firewall blocks outbound connections:** Pharaoh requires HTTPS access to `mcp.pharaoh.so` (port 443) and `github.com` (port 443) for the OAuth flow.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pharaoh.so/docs/setup/headless.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.