API Keys & BYOK Setup
Bring Your Own Key - Configure AI providers for semantic search and plan generation
Semantic search finds memories based on meaning, not just exact keyword matches.
Text Search (without API key)
Search: "authentication problem"
Only finds memories containing those exact words. Misses: "login issues", "JWT token expired", "user can't sign in"
Semantic Search (with OpenAI key)
Search: "authentication problem"
Finds all related memories: "login issues", "JWT token expired", "user can't sign in" - because they mean similar things.
How it works
- When you store a memory, OpenAI converts it to a vector embedding (a list of 1,536 numbers representing its meaning)
- When you search, your query is also converted to an embedding
- ACE finds memories with similar embeddings using pgvector in your database
- Results are ranked by semantic similarity, not keyword frequency
BYOK (Bring Your Own Key) means you provide your own API keys for AI services like OpenAI, Anthropic, or Google.
Why BYOK?
Semantic search requires calling OpenAI's API to generate embeddings. Each embedding costs a tiny amount (~$0.000002), but across thousands of customers this adds up.
Since ACE stores all your data in your own database (not ours), it makes sense for you to also control your own AI costs. This keeps ACE sustainable and gives you full transparency over what you're paying for.
Your API keys and all memory data are stored in your own database - ACE only manages user authentication. You pay AI providers directly for embedding and generation costs.
Cost Control
Pay directly to providers. Use free tiers, set spending limits, choose cost-effective models.
Security
Keys are encrypted at rest. Never displayed in UI. Only boolean flags exposed in API responses.
Flexibility
Switch providers anytime. Use different models for different tasks. No vendor lock-in.
OpenAI
Embeddings + AI Builder
Used for:
- Semantic search (embeddings)
- AI Builder plan generation
Anthropic (Claude)
AI Builder only
Used for:
- AI Builder plan generation (Claude Sonnet, Claude Haiku)
Google (Gemini)
AI Builder only
Used for:
- AI Builder plan generation (Gemini Pro, Gemini Flash)
Get your API keys
Visit the provider links above to create API keys. Copy your keys securely.
Open Dashboard Settings
Navigate to Dashboard → Settings and scroll to the AI Provider Keys section.
Enter your API keys
Paste your keys into the password fields. Keys are encrypted before storage and never displayed again.
Select your preferred models
Choose which models to use for each provider. Click "Refresh Model Lists" to see available options.
Save your settings
Click "Save Settings" to encrypt and store your keys. You'll see checkmarks next to configured providers.
| Feature | OpenAI | Anthropic | |
|---|---|---|---|
Semantic Search | - | - | |
AI Builder (Plan Generation) | |||
Model Selection |
Semantic Search
- With OpenAI key: Vector similarity search using embeddings (most relevant results)
- Without key: Falls back to text search (ILIKE keyword matching)
AI Builder
AI Builder generates complete project plans from a description - creating decisions, architecture docs, issues, patterns, and best practices automatically.
- With any provider key: Describe your project → AI generates a complete plan with linked entities
- Without keys: AI Builder is disabled. You can still create all entities manually via the dashboard or API.
Priority order: User's stored API key → Environment variable (OPENAI_API_KEY, etc.) → Graceful degradation
Encrypted at rest
API keys are encrypted using Fernet (AES-128) before storage in your own database. ACE never sees or stores your keys.
Never displayed
After saving, keys are never shown in the UI. Only boolean flags indicate if a key is configured.
API response protection
GET /settings only returns openai_api_key_set: true/false, never the actual keys.
Namespace isolation
Each namespace has its own settings. Keys from one namespace cannot be accessed by another.
When you run ace login, ACE creates a configuration file at ~/.ace/config.json. This file stores your local authentication, encryption key, and API keys.
Complete File Structure
Field Reference
auth
(created by: ace login)Your authentication credentials from OAuth login.
token- JWT token for API authentication (expires in 7 days)user.email- Your login emailuser.organization- Your organization/namespaceuser.tier- Subscription tier (free/pro/founder/enterprise)user.role- Your role (owner/admin/member)
encryption_key
(auto-generated on first login)Fernet encryption key (AES-128) used to encrypt your AI provider API keys before storing them in your database. This is the key that protects your OpenAI/Anthropic/Google keys at rest.
remote_url
(optional - created by: ace configure --remote)URL of a remote ACE server. If set, all ACE commands will connect to this server instead of localhost:7777. Used for team deployments where ACE is hosted centrally.
api_keys
(created by: ace api-key create)Local API keys you've generated for dashboard or programmatic access. Each key has a description and creation timestamp.
Security Notice
- • File permissions:
0600(owner read/write only) - • Never share or commit this file to version control
- • Add
.ace/to your.gitignore - • The encryption_key protects your stored AI provider keys - losing it means re-entering them
- • Backup this file when migrating machines
Environment Variable Overrides
For deployment scenarios, you can override config values with environment variables:
ACE_DATABASE_ENCRYPTION_KEY - Override encryption_keyACE_REMOTE_URL - Override remote_urlACE_JWT_TOKEN - Override auth.token