> ## Documentation Index
> Fetch the complete documentation index at: https://docs.doomberg.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Connect your agent to Ithaca in one command — approval, key minting, shell sourcing, and agent registration.

The Ithaca installer links a bring-your-own agent (Codex, Claude Desktop, Cursor, or any MCP client) to the hosted MCP server in a single command. It opens a browser approval flow, mints a scoped API key, writes it to a protected config file, sources it into your shell, and registers the MCP server with your agent.

## Prerequisites

* An MCP-compatible AI agent installed locally (Codex, Claude Desktop, Cursor, or any MCP client)
* Python 3.11+
* An account at [app.doomberg.me](https://app.doomberg.me) (sign in or sign up during the flow)

## The one-liner

```bash theme={null}
curl -fsSL https://app.doomberg.me/install.py | python3
```

That single command downloads the installer and runs it. The installer handles everything else — you never need to copy a key or edit a config file by hand.

## What the installer does

<Steps>
  <Step title="Start a localhost callback server">
    The installer spins up a temporary HTTP server on `127.0.0.1` on an ephemeral port and generates a random `state` token to verify the response.
  </Step>

  <Step title="Open the AgentLink approval page">
    The installer opens your browser to an approval URL showing the agent config — name, MCP endpoint, and the signed-in account. Click **Approve**.
  </Step>

  <Step title="Sign in and mint the API key">
    If you're not already signed in, Clerk authentication runs first. On approval, the app mints a scoped API key (`dmbg_<env>_<keyid>_<secret>`). The plaintext key is returned **once** — only its salted SHA-256 hash is persisted server-side.
  </Step>

  <Step title="Write the config file">
    The key is written to `~/.config/doomberg/mcp.env` with mode `0600` (owner only):

    ```bash theme={null}
    export DOOMBERG_MCP_API_KEY='dmbg_test_<keyid>_<secret>'
    export DOOMBERG_MCP_URL='https://mcp.doomberg.me/mcp'
    ```
  </Step>

  <Step title="Source the env into your shell">
    The installer appends a sourcing block to your shell RC file (`~/.zshrc` or `~/.bashrc`) and runs `launchctl setenv` on macOS so GUI agents pick up the key without a restart.
  </Step>

  <Step title="Register the MCP server with your agent">
    The installer detects your agent and registers the MCP endpoint. For Codex:

    ```bash theme={null}
    codex mcp add doomberg \
      --url https://mcp.doomberg.me/mcp \
      --bearer-token-env-var DOOMBERG_MCP_API_KEY
    ```
  </Step>
</Steps>

## Default scopes

| Scope             | Grants                                                          |
| ----------------- | --------------------------------------------------------------- |
| `data:read`       | Call any data-layer MCP tool or read an MCP resource            |
| `strategy:author` | Call `propose_strategy`                                         |
| `runs:write`      | Call `run_skill` to create durable runs                         |
| `runs:cancel`     | Call `cancel_run`                                               |
| `approvals:read`  | Call `list_approvals`                                           |
| `artifacts:read`  | Call `get_artifact`                                             |
| `deploy:backtest` | Submit backtest runs                                            |
| `deploy:paper`    | Request paper-trading promotion (still requires human approval) |

`deploy:live` is deliberately unissuable — paper-only is enforced at the code level.

## Next steps

<Steps>
  <Step title="Restart your agent">
    GUI agents cache environment variables at launch. Restart them so they pick up the key.
  </Step>

  <Step title="Run the starter prompt">
    Paste this into your agent:

    ```text theme={null}
    Use Ithaca to research NVDA — pull price history, screen peers,
    check fundamentals and insider activity, propose a momentum strategy,
    and backtest it.
    ```
  </Step>

  <Step title="Watch it live">
    Open [app.doomberg.me](https://app.doomberg.me) → **Sessions**. Your agent's research session streams live via SSE.
  </Step>
</Steps>

## Troubleshooting

<Accordion title="Key not found / 401 Unauthorized">
  1. Run `echo $DOOMBERG_MCP_API_KEY` in a fresh terminal. If empty, source the file: `. ~/.config/doomberg/mcp.env`
  2. Restart GUI agents (Codex Desktop, Claude Desktop) — `launchctl setenv` only affects processes launched after it runs.
  3. Check the web UI → **Settings → API Keys**. If the key shows `revoked: true`, re-run the installer.
</Accordion>

<Accordion title="Agent not seeing the server">
  1. For Codex: `codex mcp list` should show `doomberg` pointing at `https://mcp.doomberg.me/mcp`.
  2. The agent must support streamable-HTTP transport. stdio-only clients need a local server (see [MCP Connection](/agent/connection)).
  3. The key needs `data:read` scope to list tools.
</Accordion>

<Accordion title="Installer flags">
  | Flag        | Default                       | Purpose                                             |
  | ----------- | ----------------------------- | --------------------------------------------------- |
  | `--app-url` | `https://app.doomberg.me`     | Web app base URL                                    |
  | `--mcp-url` | `https://mcp.doomberg.me/mcp` | MCP endpoint                                        |
  | `--name`    | `doomberg`                    | Server name registered with the agent               |
  | `--client`  | `codex`                       | Which agent client to auto-register                 |
  | `--timeout` | `300`                         | Seconds to wait for browser approval                |
  | `--no-open` | (off)                         | Print the approval URL instead of opening a browser |
</Accordion>