@kortix/sandbox 0.4.1

package/opencode/skills/KORTIX-secrets/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: kortix-secrets
+description: "Simple global environment variable manager. Set ENV vars once, available everywhere - like .zshrc for the entire sandbox."
+---
+
+# Kortix Secrets - Global ENV Manager
+
+Universal environment variable storage that persists across container restarts and makes secrets available to all applications (Node.js, Python, Go, Bash, etc.) via standard `process.env` / `os.environ` / `$ENV` patterns.
+
+## Core Concept
+
+Like `.zshrc` sets environment variables for your shell sessions, Kortix Secrets sets environment variables for your entire sandbox environment. Set once via API, available everywhere until explicitly deleted.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────┐
+│ API Request (set ANTHROPIC_API_KEY)    │
+├─────────────────────────────────────────┤
+│ Encrypted Storage (/app/secrets/)      │
+├─────────────────────────────────────────┤
+│ Runtime injection (process.env)        │
+├─────────────────────────────────────────┤
+│ All child processes inherit ENV vars    │
+│ • Node.js apps: process.env.API_KEY    │
+│ • Python scripts: os.environ['API_KEY']│
+│ • Bash scripts: $API_KEY               │
+│ • Go binaries: os.Getenv("API_KEY")    │
+└─────────────────────────────────────────┘
+```
+
+## API Endpoints
+
+All endpoints use the kortix-master server (default: `localhost:8000`).
+
+### List all environment variables
+```bash
+curl http://localhost:8000/env
+```
+
+**Response:**
+```json
+{
+  "ANTHROPIC_API_KEY": "sk-ant-...",
+  "REPLICATE_API_TOKEN": "r8_...",
+  "DATABASE_URL": "postgresql://..."
+}
+```
+
+### Get specific environment variable
+```bash
+curl http://localhost:8000/env/ANTHROPIC_API_KEY
+```
+
+**Response:**
+```json
+{
+  "ANTHROPIC_API_KEY": "sk-ant-api-key-here"
+}
+```
+
+**404 Response (if not found):**
+```json
+{
+  "error": "Environment variable not found"
+}
+```
+
+### Set environment variable
+```bash
+curl -X POST http://localhost:8000/env/ANTHROPIC_API_KEY \
+  -H "Content-Type: application/json" \
+  -d '{"value": "sk-ant-your-key-here"}'
+```
+
+**Response:**
+```json
+{
+  "message": "Environment variable set",
+  "key": "ANTHROPIC_API_KEY", 
+  "value": "sk-ant-your-key-here"
+}
+```
+
+The variable is immediately available in `process.env` and persists across restarts.
+
+### Delete environment variable
+```bash
+curl -X DELETE http://localhost:8000/env/OLD_API_KEY
+```
+
+**Response:**
+```json
+{
+  "message": "Environment variable deleted",
+  "key": "OLD_API_KEY"
+}
+```
+
+## Usage Patterns
+
+### Setting API Keys
+```bash
+# Set multiple API keys
+curl -X POST localhost:8000/env/ANTHROPIC_API_KEY -H "Content-Type: application/json" -d '{"value":"sk-ant-..."}'
+curl -X POST localhost:8000/env/OPENAI_API_KEY -H "Content-Type: application/json" -d '{"value":"sk-..."}'
+curl -X POST localhost:8000/env/REPLICATE_API_TOKEN -H "Content-Type: application/json" -d '{"value":"r8_..."}'
+
+# Verify they're set
+env | grep API_KEY
+```
+
+### Database URLs and Config
+```bash
+# Set database connection
+curl -X POST localhost:8000/env/DATABASE_URL \
+  -H "Content-Type: application/json" \
+  -d '{"value":"postgresql://user:pass@localhost:5432/mydb"}'
+
+# Set application config
+curl -X POST localhost:8000/env/NODE_ENV \
+  -H "Content-Type: application/json" \
+  -d '{"value":"production"}'
+```
+
+### Checking Current Environment
+```bash
+# See all managed secrets
+curl localhost:8000/env
+
+# Check specific value
+curl localhost:8000/env/DATABASE_URL
+
+# See what's actually in the environment
+env | grep -E "(API_KEY|TOKEN|SECRET|DATABASE|_URL)"
+```
+
+### Cleaning Up
+```bash
+# Remove old/unused secrets
+curl -X DELETE localhost:8000/env/DEPRECATED_API_KEY
+curl -X DELETE localhost:8000/env/OLD_DATABASE_URL
+```
+
+## Cross-Language Access
+
+Once set via the API, environment variables are available in all languages:
+
+### Node.js
+```javascript
+// Automatically available
+console.log(process.env.ANTHROPIC_API_KEY);
+console.log(process.env.DATABASE_URL);
+```
+
+### Python
+```python
+import os
+
+# Automatically available
+api_key = os.environ.get('ANTHROPIC_API_KEY')
+db_url = os.environ['DATABASE_URL']
+```
+
+### Bash/Shell
+```bash
+#!/bin/bash
+# Automatically available
+echo "API Key: $ANTHROPIC_API_KEY"
+echo "Database: $DATABASE_URL"
+```
+
+### Go
+```go
+package main
+import "os"
+
+func main() {
+    apiKey := os.Getenv("ANTHROPIC_API_KEY")
+    dbURL := os.Getenv("DATABASE_URL")
+}
+```
+
+## Security Features
+
+- **AES-256-GCM Encryption**: All values encrypted at rest
+- **Secure File Permissions**: Secret files have 0o600 permissions 
+- **Key Derivation**: Master key derived from KORTIX_TOKEN + salt
+- **No Plaintext Logging**: Values not exposed in server logs
+- **Persistence**: Survives container restarts, not rebuilds
+
+## Integration with Other Skills
+
+### Use in skill implementations
+When your skills need API keys, they can access them directly:
+
+```typescript
+// In a skill implementation
+const apiKey = process.env.ANTHROPIC_API_KEY;
+const replicateToken = process.env.REPLICATE_API_TOKEN;
+```
+
+### Common patterns for skill setup
+```bash
+# Set up a skill's dependencies
+curl -X POST localhost:8000/env/ELEVENLABS_API_KEY -H "Content-Type: application/json" -d '{"value":"..."}'
+curl -X POST localhost:8000/env/FIRECRAWL_API_KEY -H "Content-Type: application/json" -d '{"value":"..."}'
+
+# Then the skill can use: process.env.ELEVENLABS_API_KEY
+```
+
+## Best Practices
+
+### Naming Conventions
+- Use `UPPER_SNAKE_CASE` for environment variables
+- End API keys with `_API_KEY` or `_TOKEN`
+- Use descriptive prefixes: `DATABASE_URL`, `REDIS_URL`, `SMTP_HOST`
+
+### Organization
+- Group related configs: `DB_HOST`, `DB_PORT`, `DB_NAME`, `DB_PASSWORD`
+- Use service prefixes: `STRIPE_SECRET_KEY`, `STRIPE_WEBHOOK_SECRET`
+
+### Security
+- Rotate API keys regularly by updating them via the API
+- Use environment-specific values: `DATABASE_URL_PROD`, `DATABASE_URL_DEV`
+- Delete unused secrets: `curl -X DELETE localhost:8000/env/OLD_KEY`
+
+### Development Workflow
+```bash
+# Development setup
+curl -X POST localhost:8000/env/NODE_ENV -H "Content-Type: application/json" -d '{"value":"development"}'
+curl -X POST localhost:8000/env/DEBUG -H "Content-Type: application/json" -d '{"value":"true"}'
+
+# Production setup  
+curl -X POST localhost:8000/env/NODE_ENV -H "Content-Type: application/json" -d '{"value":"production"}'
+curl -X DELETE localhost:8000/env/DEBUG
+```
+
+## Troubleshooting
+
+### Variable not showing up?
+```bash
+# Check if it's set in the secret store
+curl localhost:8000/env/YOUR_KEY
+
+# Check if it's in the current environment
+env | grep YOUR_KEY
+
+# Try restarting the server to reload all variables
+```
+
+### Permission errors?
+```bash
+# Check secret file permissions
+ls -la /app/secrets/
+
+# Should show -rw------- (0o600)
+```
+
+### Decryption errors?
+- Verify `KORTIX_TOKEN` is consistent
+- Check if salt file was corrupted
+- May need to recreate secrets if encryption key changed
+
+## File Locations
+
+- **Secrets**: `/app/secrets/.secrets.json` (encrypted)
+- **Salt**: `/app/secrets/.salt` (for key derivation)
+- **Server**: `kortix-master` on port 8000
+
+## API Error Codes
+
+- `200` - Success
+- `404` - Environment variable not found  
+- `400` - Invalid request (missing value, invalid JSON)
+- `500` - Server error (encryption/storage failure)
+
+---
+
+This skill provides the foundation for secure, persistent environment variable management across your entire sandbox environment. Set once, use everywhere, like a global `.zshrc` for all your applications.

package/opencode/skills/KORTIX-semantic-search/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: kortix-semantic-search
+description: "Full semantic search over Desktop files, agent memory, and knowledge. Use when the agent needs to find relevant files or search knowledge semantically."
+---
+
+# Semantic Search
+
+You have a **full semantic search engine** running on this machine, powered by [lss](https://github.com/kortix-ai/lss) (Local Semantic Search). It indexes text files, code, PDFs, DOCX, XLSX, PPTX, HTML, EML, JSON, CSV — virtually everything.
+
+A background file-watcher daemon (`lss-sync`) detects file changes in real time via FSEvents/inotify and re-indexes within seconds.
+
+## How It Works
+
+lss combines **BM25 full-text search** (keyword matching with custom re-scoring) and **embedding similarity** (semantic meaning via OpenAI or local fastembed) using Reciprocal Rank Fusion. Queries can be natural language — you don't need exact keywords.
+
+The database lives at `/workspace/.lss/lss.db`.
+
+## What's Indexed
+
+| Source | Path | Content |
+|--------|------|---------|
+| **Desktop files** | `/workspace` | Code, docs, PDFs, DOCX, XLSX, PPTX, HTML, JSON, CSV — all text-like files recursively |
+| **Agent memory** | `/workspace/.kortix/` | MEMORY.md, memory/*.md, journal/*.md, knowledge/*.md |
+
+Indexed formats: ~80 known extensions (code, markup, config, documents). Unknown extensions are skipped. `.gitignore` patterns are respected.
+
+## Quick Reference
+
+```bash
+# Search EVERYTHING indexed
+lss "your natural language query" -p /workspace -k 10 --json
+
+# Search only agent memory + knowledge
+lss "user deployment preferences" -p /workspace/.kortix/ -k 5 --json
+
+# Search a specific project directory
+lss "database migration strategy" -p /workspace/myproject/ -k 5 --json
+
+# Search without triggering re-indexing (faster, uses existing index)
+lss "query" -p /workspace --no-index -k 10 --json
+
+# Filter by file type
+lss "auth logic" -p /workspace -e .py -e .ts -k 10 --json
+
+# Exclude file types
+lss "config" -p /workspace -E .json -E .yaml -k 10 --json
+
+# Exclude content patterns
+lss "user data" -p /workspace -x '\d{4}-\d{2}-\d{2}' -k 10 --json
+
+# Force re-index a path immediately
+lss index /workspace/important-file.md
+
+# List all indexed files
+lss ls
+
+# Check index stats and configuration
+lss status
+```
+
+## Search Filters
+
+Narrow results at query time without re-indexing.
+
+| Flag | Meaning | Applied | Example |
+|------|---------|---------|---------|
+| `-e EXT` / `--ext` | Include only these extensions (repeatable) | In SQL, pre-scoring | `-e .py -e .ts` |
+| `-E EXT` / `--exclude-ext` | Exclude these extensions (repeatable) | In SQL, pre-scoring | `-E .json -E .yaml` |
+| `-x REGEX` / `--exclude-pattern` | Exclude chunks matching regex (repeatable) | Post-scoring | `-x 'test_' -x 'TODO'` |
+
+### Filter Strategy for Agents
+
+**Narrow first, then broaden.** Start with tight extension filters, then remove them if results are insufficient:
+
+```bash
+# 1. Try narrow: only Python source files
+lss "authentication flow" -p /workspace/project -e .py -k 10 --json
+
+# 2. If too few results, broaden to all code
+lss "authentication flow" -p /workspace/project -e .py -e .ts -e .go -e .rs -k 10 --json
+
+# 3. If still insufficient, search everything
+lss "authentication flow" -p /workspace/project -k 10 --json
+```
+
+**Exclude noise, not signal:**
+
+```bash
+# Exclude generated/test code when looking for implementations
+lss "rate limiting" -e .py -x "test_" -x "mock_" -x "fixture" --json -k 10
+
+# Exclude logs and config when looking for code
+lss "database connection" -E .log -E .yaml -E .json -E .toml --json -k 10
+
+# Exclude dates/timestamps from data searches
+lss "customer report" -x '\d{4}-\d{2}-\d{2}' --json -k 10
+```
+
+## JSON Output Format
+
+**Always use `--json` for programmatic parsing.**
+
+```bash
+lss "query" -p /workspace --json -k 10
+```
+
+Returns an array of result arrays (one per query):
+```json
+[
+  {
+    "query": "authentication flow",
+    "hits": [
+      {
+        "file_path": "/workspace/project/auth.py",
+        "score": 0.0345,
+        "snippet": "def authenticate(user, password):\n    \"\"\"Authenticate user with JWT...",
+        "rank_stage": "S3_MMR",
+        "indexed_at": 1738900000.0
+      }
+    ]
+  }
+]
+```
+
+Key fields:
+- `file_path` — Full path to the source file
+- `score` — Relevance score (higher is better)
+- `snippet` — Best-matching text excerpt (~280 chars)
+- `rank_stage` — S1=BM25 only, S3=fusion, S3_MMR=fusion+diversity
+
+## Multi-Query Decomposition
+
+For complex questions, **decompose into multiple specific queries**:
+
+```bash
+# BAD: single vague query
+lss "how does the system work" --json -k 10
+
+# GOOD: decomposed into specific queries
+lss "system architecture overview" "API endpoint design" "database schema" "authentication flow" --json -k 5
+```
+
+Or use a query file:
+```bash
+echo "system architecture overview" > /tmp/queries.txt
+echo "API endpoint design" >> /tmp/queries.txt
+echo "database schema" >> /tmp/queries.txt
+lss -Q /tmp/queries.txt -p /workspace/project --json -k 5
+```
+
+## When to Use lss vs grep
+
+| Use lss | Use grep |
+|---------|----------|
+| Conceptual queries ("how to handle errors") | Exact string ("ERROR_CODE_429") |
+| Fuzzy matching ("something like the email template") | Specific variable name (`userSessionToken`) |
+| Cross-file discovery ("files about API design") | Known file + line search |
+| Natural language ("what's the deploy process") | Regex pattern matching |
+
+## Iterative Search Strategy
+
+For large codebases, use an iterative approach:
+
+```bash
+# Step 1: Broad discovery — find relevant areas
+lss "payment processing" -p /workspace/project -k 20 --json
+
+# Step 2: Narrow by extension — focus on implementation
+lss "payment processing" -p /workspace/project -e .py -k 10 --json
+
+# Step 3: Narrow by path — focus on specific module
+lss "payment processing" -p /workspace/project/src/payments/ -k 10 --json
+
+# Step 4: Read the actual files for full context
+cat /workspace/project/src/payments/processor.py
+```
+
+## Indexing
+
+```bash
+# Index a directory (auto-triggered on first search)
+lss index /workspace/project/
+
+# Index a single file
+lss index /workspace/important.pdf
+
+# The daemon handles real-time updates automatically
+# Use manual indexing only for immediate needs
+```
+
+## Maintenance
+
+```bash
+# Sweep stale entries (files deleted from disk)
+lss sweep --retention-days 90
+
+# Clear all embeddings (forces re-embedding on next search)
+lss sweep --clear-embeddings 0
+
+# Full reset
+lss sweep --clear-all
+```
+
+## Rules
+
+1. **Always use `--json` flag** when searching programmatically. Parse the JSON output.
+2. **Always use `-p <path>`** to scope searches. Never search without a path scope.
+3. **Use `-k` to control result count.** `-k 5` for focused, `-k 20` for broad exploration.
+4. **Decompose complex queries.** Multiple specific queries beat one vague query.
+5. **Read source files for full context.** Snippets are excerpts — always read the full file after finding a match.
+6. **Narrow with filters first.** Use `-e` to target file types before broadening.
+7. **Don't grep when lss is better.** Conceptual, fuzzy, and cross-file queries belong in lss.
+8. **The index auto-updates.** Only use `lss index` for immediate needs. The daemon handles the rest.