Zum Hauptinhalt springen

Ein Repository verbinden

Dies ist der häufigste Ablauf: Du hast ein Almirant-Konto (SaaS oder Self-Hosted) und möchtest, dass dein lokales Repository als Projekt erscheint, mit KI-Agenten, die aus deiner IDE erreichbar sind (Claude Code, Codex, OpenCode, Cursor usw.).

Geschätzte Dauer: 2 Minuten.

Voraussetzungen​

  • Das installierte CLI (bun add -g almirant@latest oder npm i -g almirant).
  • Ein Almirant-Konto. Falls du noch keines hast, erstelle eines auf almirant.ai oder stelle deine eigene Instanz nach der Self-Hosted-Anleitung bereit.

Schritt 1 - Authentifizieren​

Wähle den Befehl danach, bei welchem Backend du dich authentifizierst:

# SaaS
almirant login

# Self-hosted-Instanz
almirant login --api-url https://almirant.miempresa.com/api

Das CLI öffnet den Browser für OAuth und speichert das Konto mit Berechtigungen 600 in ~/.almirant/config.json.

Tipp

Du musst login nur einmal pro Backend ausführen. Wenn du mit mehreren Instanzen arbeitest (z. B. gleichzeitig SaaS und Self-Hosted), führe almirant login einmal pro Instanz aus, vergib mit almirant accounts rename Bezeichnungen und wechsle mit almirant use das aktive Konto. Siehe Mit mehreren Konten arbeiten.

Schritt 2 - Das aktive Konto auswählen​

Wenn du mehr als ein Konto hast, verwende Bezeichnungen. In vier Monaten erinnerst du dich an local-m1pro, nicht an eine lange URL.

almirant accounts list
almirant accounts rename 1 prod-saas
almirant accounts rename 2 local-m1pro
almirant use local-m1pro
almirant current

Schritt 3 - Das Repository verbinden​

Wechsle in das Stammverzeichnis des Repositorys, das du verbinden möchtest, und führe Folgendes aus:

cd mi-repo
almirant link

Das CLI:

  1. Liest deine gespeicherten Konten und verwendet das aktive Konto oder lässt dich eines auswählen.
  2. Listet die Projekte dieses Kontos auf und lässt dich eines auswählen oder ein neues erstellen.
  3. Führt einen almirant-Eintrag unter Verwendung des lokalen stdio-Proxys in .mcp.json zusammen.
  4. Kopiert die Skill-Vorlagen nach .claude/skills/ und .agents/skills/.

Wenn dies dein erstes Mal ist und du noch kein almirant login ausgefuhrt hast, verwende statt link almirant init - init startet innerhalb desselben Befehls auch den OAuth-Ablauf.

Schritt 4 - In deiner IDE überprüfen​

Offne das Repository in deinem Agenten und fordere zum Beispiel Folgendes an:

Liste meine Almirant-Work-Items auf

Wenn du die Liste siehst, ist alles verbunden. Wenn du Unauthorized erhaltst, prufe:

  • Ob .mcp.json im Stammverzeichnis des Repositorys vorhanden ist.
  • Ob --account in .mcp.json auf ein vorhandenes Konto zeigt (almirant accounts list).
  • Ob der lokale API-Schlüssel noch gültig ist (almirant current zeigt nur das Präfix, nicht das Geheimnis).
  • Ob das Backend lauft und erreichbar ist, insbesondere bei Self-Hosted.

Was in deinem Repository bleibt​

Nach link enthalt dein Repository Folgendes:

mi-repo/
├── .mcp.json              ← arranca almirant mcp proxy; no contiene tokens
├── .claude/
│   └── skills/            ← plantillas de skills para Claude Code
└── .agents/
    └── skills/            ← mismo contenido, para agentes no-Claude

Der erzeugte MCP-Eintrag folgt diesem Muster:

{
  "mcpServers": {
    "almirant": {
      "type": "stdio",
      "command": "almirant",
      "args": ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id>"]
    }
  }
}
Info

Der API-Schlüssel befindet sich in ~/.almirant/config.json, nicht in .mcp.json. Der Proxy hängt das Bearer-Token im Speicher an, wenn der Agent ihn startet.

Codex .codex/config.toml​

Wenn du Codex verwendest und der MCP-Server in .codex/config.toml deklariert wird, verwende denselben Proxy:

[mcp_servers.almirant]
command = "almirant"
args = ["mcp", "proxy", "--project-id", "<project-id>", "--account", "<account-id-or-label>"]

Schreibe keine Bearer-Tokens in .codex/config.toml. Wenn dieses Repository immer dem aktiven Konto folgen soll, lasse --account weg; für Teamarbeit oder alte Repositories sollte es per ID festgelegt bleiben.

Von alten Konfigurationen migrieren​

Wenn deine .mcp.json type: "http", url und Authorization: Bearer ... enthält, führe erneut Folgendes aus:

almirant link

Falls dieses Token jemals in Git war, rotiere es:

almirant config rotate api-key --account <ref>

Mehrere Konten und Projekte verwalten​

Wenn du mit mehr als einem Konto arbeitest (typisch: personliches Konto und Unternehmen oder SaaS und interne Instanz), siehe Mit mehreren Konten arbeiten.

Um das verbundene Projekt eines bereits initialisierten Repositorys zu ändern, führe almirant link erneut aus und wähle das neue Projekt - das CLI schreibt den almirant-Eintrag in .mcp.json neu und behält andere Server bei.