portugalfuturista/replica-omnisciente
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 68

docs: add API key setup guide and Proxmox environment script

Browse source 
- 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
This commit is contained in:
AI Agent 2026-06-07 21:27:53 +01:00
parent 5d7c1899c7
commit 262cf3c2b5
2 changed files with 305 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

232
SETUP_API_KEYS.md Normal file
View file

@ -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 <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*

73
scripts/setup-proxmox-env.sh Executable file
View file

@ -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=<PASTE_YOUR_KIMI_API_KEY_HERE>
# Jules (Google AI) — https://jules.google.com/
# REQUIRED: JULES_API_KEY must be set for `uvx jules-cli` remote dispatches.
JULES_API_KEY=<PASTE_YOUR_JULES_API_KEY_HERE>
# Anthropic Claude — https://console.anthropic.com/settings/keys
# OPTIONAL but recommended for multi-model routing.
ANTHROPIC_API_KEY=<PASTE_YOUR_ANTHROPIC_API_KEY_HERE>
# Gemini / Google Vertex — https://aistudio.google.com/app/apikey
# OPTIONAL but recommended for multi-model routing.
GEMINI_API_KEY=<PASTE_YOUR_GEMINI_API_KEY_HERE>
# OpenRouter — https://openrouter.ai/settings/keys
# OPTIONAL: unified gateway for Claude, GPT, Gemini, etc.
OPENROUTER_API_KEY=<PASTE_YOUR_OPENROUTER_API_KEY_HERE>
# 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 ""