diff --git a/SETUP_API_KEYS.md b/SETUP_API_KEYS.md new file mode 100644 index 00000000..00ee3836 --- /dev/null +++ b/SETUP_API_KEYS.md @@ -0,0 +1,232 @@ +# Aurelio API Key Setup Guide + +> **Goal:** Configure all AI API keys so the Aurelio VS Code extension and Aurelio Web portal work correctly with local and remote (Proxmox CT 206) execution. + +--- + +## Table of Contents + +1. [Quick Overview: Which Key Goes Where](#1-quick-overview-which-key-goes-where) +2. [How to Get Each Key](#2-how-to-get-each-key) +3. [Google Vertex ADC Setup](#3-google-vertex-adc-setup) +4. [CT 206 (Proxmox) Configuration](#4-ct-206-proxmox-configuration) +5. [Troubleshooting](#5-troubleshooting) + +--- + +## 1. Quick Overview: Which Key Goes Where + +| Key | `replica/.env` | `replica/extensions/aurelio-vscode/.env` | `replica/aurelio-web/server/.env` | `/root/.env` on CT 206 | +|-----|:--:|:--:|:--:|:--:| +| `KIMI_API_KEY` | ✅ | ✅ | — | ✅ | +| `GEMINI_API_KEY` | ✅ | ✅ | — | ✅ | +| `JULES_API_KEY` | ✅ | ✅ | ✅ | ✅ | +| `ANTHROPIC_API_KEY` | ✅ | ✅ | — | ✅ | +| `OPENROUTER_API_KEY` | ✅ | — | — | ✅ | +| `GOOGLE_APPLICATION_CREDENTIALS` | ✅ | — | — | ✅ | +| `GOOGLE_CLOUD_PROJECT` | — | — | ✅ | — | +| `VERTEX_PROJECT_ID` | — | — | ✅ | — | +| `VERTEX_LOCATION` | — | — | ✅ | — | +| `ANTIGRAVITY_API_KEY` | — | — | ✅ | — | +| `CDP_HOST` / `CDP_PORT` | — | — | ✅ | — | +| `ZOTERO_API_KEY` | ✅ | — | — | — | +| `IEEE_API_KEY` | ✅ | — | — | — | +| `ANNAS_ARCHIVE_KEY` | ✅ | — | — | — | + +**Legend:** +- `replica/.env` — Global workspace keys (research, knowledge, shared AI keys). +- `replica/extensions/aurelio-vscode/.env` — Keys for **local** VS Code execution. +- `replica/aurelio-web/server/.env` — Keys for the Aurelio Web backend server. +- `/root/.env` on CT 206 — Keys for **remote** Kimi / Jules execution on Proxmox. + +> ⚠️ **Critical:** CT 206 does **not** inherit keys from your workstation. You must manually copy them to `/root/.env` inside the container. + +--- + +## 2. How to Get Each Key + +### 2.1 Kimi (Moonshot AI) + +1. Go to . +2. Sign up / log in with your account. +3. Navigate to **API Keys**. +4. Click **Create API Key**. +5. Copy the key and paste it into: + - `replica/.env` → `KIMI_API_KEY` + - `replica/extensions/aurelio-vscode/.env` → `KIMI_API_KEY` + - `/root/.env` on CT 206 → `KIMI_API_KEY` + +### 2.2 Gemini / Google Vertex AI + +1. Go to . +2. Sign in with your Google Cloud account. +3. Click **Create API key**. +4. Select your Google Cloud project. +5. Copy the key and paste it into: + - `replica/.env` → `GEMINI_API_KEY` + - `replica/extensions/aurelio-vscode/.env` → `GEMINI_API_KEY` + - `/root/.env` on CT 206 → `GEMINI_API_KEY` + +> For **Vertex AI** (server-side), you also need: +> - `GOOGLE_CLOUD_PROJECT` — your GCP project name. +> - `VERTEX_PROJECT_ID` — usually the same as `GOOGLE_CLOUD_PROJECT`. +> - `VERTEX_LOCATION` — e.g. `europe-west4` or `us-central1`. + +### 2.3 Jules (Google AI Agent) + +1. Go to . +2. Sign in with your Google account. +3. Open **Settings** → **API Keys**. +4. Generate a new key. +5. Copy the key and paste it into: + - `replica/.env` → `JULES_API_KEY` + - `replica/extensions/aurelio-vscode/.env` → `JULES_API_KEY` + - `replica/aurelio-web/server/.env` → `JULES_API_KEY` + - `/root/.env` on CT 206 → `JULES_API_KEY` + +### 2.4 Anthropic Claude + +1. Go to . +2. Sign up / log in. +3. Click **Create Key**. +4. Give it a name (e.g., "Aurelio-VSCode"). +5. Copy the key and paste it into: + - `replica/.env` → `ANTHROPIC_API_KEY` + - `replica/extensions/aurelio-vscode/.env` → `ANTHROPIC_API_KEY` + - `/root/.env` on CT 206 → `ANTHROPIC_API_KEY` + +### 2.5 OpenRouter + +1. Go to . +2. Sign up / log in. +3. Click **Create Key**. +4. Copy the key and paste it into: + - `replica/.env` → `OPENROUTER_API_KEY` + - `/root/.env` on CT 206 → `OPENROUTER_API_KEY` + +> OpenRouter is optional but highly recommended as a fallback unified gateway. + +--- + +## 3. Google Vertex ADC Setup + +If you want to use **Application Default Credentials** (ADC) instead of a raw API key for Vertex AI: + +### 3.1 On your workstation (local development) + +```bash +# Install the Google Cloud CLI if you haven't already: +# https://cloud.google.com/sdk/docs/install + +# Authenticate with your Google account: +gcloud auth application-default login + +# Verify the credential file exists: +ls ~/.config/gcloud/application_default_credentials.json +``` + +Then in `replica/.env`: + +```bash +GOOGLE_APPLICATION_CREDENTIALS=/home/$USER/.config/gcloud/application_default_credentials.json +``` + +### 3.2 On CT 206 (Proxmox container) + +```bash +ssh root@ssh.portugalfuturista.org -p 22206 + +# Inside CT 206: +gcloud auth application-default login +# (follow the OAuth link printed in the terminal) + +# Verify: +ls /root/.config/gcloud/application_default_credentials.json +``` + +Then in `/root/.env` on CT 206: + +```bash +GOOGLE_APPLICATION_CREDENTIALS=/root/.config/gcloud/application_default_credentials.json +``` + +> **Alternative:** Download a service-account JSON from the [GCP Console](https://console.cloud.google.com/iam-admin/serviceaccounts) and set `GOOGLE_APPLICATION_CREDENTIALS` to its absolute path. + +--- + +## 4. CT 206 (Proxmox) Configuration + +CT 206 is the dedicated container for remote Kimi and Jules execution. + +### 4.1 Automated helper script + +We provide a convenience script that prints the exact text to paste into `/root/.env`: + +```bash +cd /home/fcunha/portugalfuturista/replica +./scripts/setup-proxmox-env.sh +``` + +Copy the output block and paste it into `/root/.env` on CT 206. + +### 4.2 Manual steps + +```bash +# 1. SSH into CT 206 +ssh root@ssh.portugalfuturista.org -p 22206 + +# 2. Edit /root/.env +nano /root/.env + +# 3. Paste the keys (example): +KIMI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +JULES_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +GEMINI_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +GOOGLE_APPLICATION_CREDENTIALS=/root/.config/gcloud/application_default_credentials.json + +# 4. Secure the file +chmod 600 /root/.env + +# 5. Verify in a new shell +source /root/.env +env | grep -E 'KIMI|JULES|ANTHROPIC|GEMINI|OPENROUTER' +``` + +### 4.3 Why CT 206 needs its own `.env` + +When the Aurelio VS Code extension dispatches tasks remotely, it runs commands like: + +```bash +ssh root@ct206 "uvx kimi-cli --task '...'" +``` + +The `uvx` process on CT 206 reads environment variables from the **container's shell**, not from your workstation. Therefore, all keys must be present in `/root/.env` (or exported in `.bashrc`). + +--- + +## 5. Troubleshooting + +| Symptom | Likely Cause | Fix | +|---------|-------------|-----| +| "KIMI_API_KEY not set" in VS Code | Missing key in `replica/extensions/aurelio-vscode/.env` | Add the key and reload the window. | +| "KIMI_API_KEY not set" on CT 206 | Missing key in `/root/.env` on the container | SSH in, add the key, `source /root/.env`. | +| "Permission denied" on `/root/.env` | File is readable by others | Run `chmod 600 /root/.env`. | +| Vertex AI "Unauthorized" | ADC not set up or expired | Re-run `gcloud auth application-default login`. | +| Jules tasks fail silently | `JULES_API_KEY` missing on CT 206 | Verify the key is exported in the remote shell. | +| Web portal cannot reach CDP Bridge | Wrong `CDP_HOST` or `CDP_PORT` | Check that CT 212 is running and reachable from the web server. | + +--- + +## Security Checklist + +- [ ] `.env` files are listed in `.gitignore`. +- [ ] Real API keys are never committed to Git. +- [ ] `/root/.env` on CT 206 has permissions `600`. +- [ ] Service-account JSONs are stored outside the repository. +- [ ] Rotate keys immediately if accidentally exposed. + +--- + +*Last updated: 2026-06-03* diff --git a/scripts/setup-proxmox-env.sh b/scripts/setup-proxmox-env.sh new file mode 100755 index 00000000..b8db6f00 --- /dev/null +++ b/scripts/setup-proxmox-env.sh @@ -0,0 +1,73 @@ +#!/usr/bin/env bash +# ============================================================================= +# setup-proxmox-env.sh +# ============================================================================= +# This script prints the exact content that must be appended to /root/.env +# on Proxmox CT 206 (the Kimi / Jules remote execution container). +# +# Usage: +# 1. Run this script on your workstation: +# ./scripts/setup-proxmox-env.sh +# +# 2. Copy the output block below. +# +# 3. SSH into CT 206: +# ssh root@ssh.portugalfuturista.org -p 22206 +# +# 4. Paste the block into /root/.env (create it if it does not exist): +# nano /root/.env +# +# 5. Verify the variables are loaded in a new shell: +# source /root/.env && env | grep -E 'KIMI|JULES|ANTHROPIC|GEMINI|OPENROUTER' +# +# IMPORTANT: +# • NEVER commit real API keys to Git. +# • /root/.env should have permissions 600 (chmod 600 /root/.env). +# • These keys are consumed by `uvx kimi-cli` and `uvx jules-cli` dispatches. +# ============================================================================= + +cat <<'EOF' + +# ============================================================================= +# CT 206 — Aurelio Remote Execution Environment +# Added: $(date -Iseconds) +# ============================================================================= + +# Kimi (Moonshot AI) — https://platform.moonshot.cn/ +# REQUIRED: KIMI_API_KEY must be set for `uvx kimi-cli` remote dispatches. +KIMI_API_KEY= + +# Jules (Google AI) — https://jules.google.com/ +# REQUIRED: JULES_API_KEY must be set for `uvx jules-cli` remote dispatches. +JULES_API_KEY= + +# Anthropic Claude — https://console.anthropic.com/settings/keys +# OPTIONAL but recommended for multi-model routing. +ANTHROPIC_API_KEY= + +# Gemini / Google Vertex — https://aistudio.google.com/app/apikey +# OPTIONAL but recommended for multi-model routing. +GEMINI_API_KEY= + +# OpenRouter — https://openrouter.ai/settings/keys +# OPTIONAL: unified gateway for Claude, GPT, Gemini, etc. +OPENROUTER_API_KEY= + +# Google Application Default Credentials +# If using Vertex AI on CT 206, set the path to a service-account JSON, +# or run `gcloud auth application-default login` inside the container. +GOOGLE_APPLICATION_CREDENTIALS=/root/.config/gcloud/application_default_credentials.json + +# ============================================================================= +EOF + +echo "" +echo "✅ Copy the block above and paste it into /root/.env on CT 206." +echo "" +echo "Quick SSH command:" +echo " ssh root@ssh.portugalfuturista.org -p 22206" +echo "" +echo "Then run:" +echo " nano /root/.env" +echo " chmod 600 /root/.env" +echo ""