replica-omnisciente/SETUP_API_KEYS.md

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
2. How to Get Each Key
3. Google Vertex ADC Setup
4. CT 206 (Proxmox) Configuration
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)

# 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:

GOOGLE_APPLICATION_CREDENTIALS=/home/$USER/.config/gcloud/application_default_credentials.json

3.2 On CT 206 (Proxmox container)

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:

GOOGLE_APPLICATION_CREDENTIALS=/root/.config/gcloud/application_default_credentials.json

Alternative: Download a service-account JSON from the GCP Console 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:

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

# 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:

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