portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 71
replica-omnisciente/SETUP_API_KEYS.md
AI Agent 262cf3c2b5 docs: add API key setup guide and Proxmox environment script 
- SETUP_API_KEYS.md: Instructions for configuring external API keys
  (Kimi, Jules, OpenAI, etc.)
- scripts/setup-proxmox-env.sh: Automated environment setup for Proxmox
  nodes and containers
2026-06-07 21:27:53 +01:00

232 lines
7.6 KiB
Markdown
Raw Blame History

# 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 <https://platform.moonshot.cn/>.
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 <https://aistudio.google.com/app/apikey>.
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 <https://jules.google.com/>.
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 <https://console.anthropic.com/settings/keys>.
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 <https://openrouter.ai/settings/keys>.
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*
Reference in a new issue View git blame Copy permalink