Amp CLI Setup Guide

This guide explains how to configure Amp CLI to work with Quotio, enabling you to use both Factory and Amp through a single proxy server.

Overview

Quotio integrates with Amp CLI by:

• Routing Amp management requests (login, settings) to ampcode.com
• Routing Amp model requests through Quotio proxy
• Automatically falling back to ampcode.com for models you haven't authenticated locally

Prerequisites

• Quotio installed and running
• Amp CLI installed (amp --version to verify)

Setup Steps

1. Configure Amp URL

Edit or create ~/.config/amp/settings.json:

mkdir -p ~/.config/amp
cat > ~/.config/amp/settings.json << 'EOF'
{
  "amp.url": "http://localhost:8317"
}
EOF

This tells Amp CLI to use Quotio instead of connecting directly to ampcode.com.

2. Login to Amp

Run the Amp login command:

amp login

This will:

1. Open your browser to http://localhost:8317/api/auth/cli-login
2. Quotio forwards the request to ampcode.com
3. You complete the login in your browser
4. Amp CLI saves your API key to ~/.local/share/amp/secrets.json

3. Fix the Secrets File Format

After login, the secrets file will have URL-specific keys that Quotio can't read. You need to add a simple apiKey field.

Open the secrets file:

cat ~/.local/share/amp/secrets.json

You'll see something like:

{
  "apiKey@https://ampcode.com/": "sgamp_user_01XXXXX...",
  "apiKey@http://localhost:8317": "sgamp_user_01XXXXX..."
}

Edit the file to add the apiKey field:

nano ~/.local/share/amp/secrets.json

Add a new line with just apiKey (copy the value from one of the existing keys):

{
  "apiKey@https://ampcode.com/": "sgamp_user_01XXXXX...",
  "apiKey@http://localhost:8317": "sgamp_user_01XXXXX...",
  "apiKey": "sgamp_user_01XXXXX..."
}

Important: The value should be identical to the other keys - just copy/paste it.

Or use this one-liner to do it automatically:

python3 << 'EOF'
import json
import os

secrets_file = os.path.expanduser('~/.local/share/amp/secrets.json')

with open(secrets_file, 'r') as f:
    data = json.load(f)

# Get the API key from any URL-specific key
api_key = data.get('apiKey@https://ampcode.com/', data.get('apiKey@http://localhost:8317', ''))

if api_key and 'apiKey' not in data:
    data['apiKey'] = api_key
    with open(secrets_file, 'w') as f:
        json.dump(data, f, indent=2)
    print('✅ Added apiKey field to secrets.json')
elif 'apiKey' in data:
    print('✅ apiKey field already exists')
else:
    print('❌ No API key found in secrets.json')
EOF

4. Restart Quotio

For Quotio to pick up the new API key:

1. Quit Quotio from the menu bar
2. Launch Quotio again

Usage

Now you can use Amp CLI normally:

# Interactive mode
amp

# Direct prompt
amp "Write a hello world in Python"

# With specific mode
amp --mode smart "Explain quantum computing"

How It Works

Request Routing

Amp CLI
  ↓
  http://localhost:8317 (Quotio)
  ↓
  ├─ /auth/cli-login → /api/auth/cli-login → ampcode.com (login)
  ├─ /provider/* → /api/provider/* → Quotio Proxy (model requests)
  └─ /api/* → ampcode.com (management requests)

Model Fallback

When Amp requests a model:

1. Local OAuth available? (e.g., you configured provider in Quotio)

   • ✅ Uses your configured provider (no Amp credits)

2. No local OAuth?

   • ✅ Falls back to ampcode.com using your Amp API key
   • Uses Amp credits

Example:

• If you've configured Claude in Quotio, Claude models use your subscription
• Gemini models without local configuration will use Amp credits

Troubleshooting

"auth_unavailable: no auth available"

Problem: Quotio can't find the Amp API key.

Solutions:

1. Verify ~/.local/share/amp/secrets.json has the apiKey field (see Step 3)
2. Restart Quotio to reload the secrets file
3. Check permissions: ls -la ~/.local/share/amp/secrets.json (should be readable)

"Unable to connect"

Problem: Amp can't reach the proxy.

Solutions:

1. Verify Quotio is running (check menu bar)
2. Verify AMP_URL is set: echo $AMP_URL (should show http://localhost:8317)
3. Test the proxy: curl http://localhost:8317/api/user (should redirect or return HTML)

"404 page not found" in browser during login

Problem: Path rewriting isn't working.

Solutions:

1. Make sure you're using the latest Quotio build
2. Manually add /api/ to the URL in the browser if needed

Expired OAuth Tokens

If you have local OAuth tokens that have expired, remove them through the Quotio settings or restart the application.

Authenticating Local Providers (Optional)

To use your own subscriptions instead of Amp credits for specific models, configure providers in Quotio:

1. Open Quotio from the menu bar
2. Go to Settings → Providers
3. Add your API keys for:
   • Google/Gemini
   • OpenAI/ChatGPT
   • Anthropic/Claude

After configuring, those models will now use your subscriptions instead of Amp credits.

Benefits

✅ One proxy for everything - Factory, Amp, and any other tool
✅ Smart fallback - Uses your subscriptions when available, Amp credits when not
✅ Seamless integration - Amp works exactly as before, just through the proxy
✅ Cost optimization - Maximize use of existing subscriptions, minimize Amp credits

Additional Resources

• Amp CLI Documentation
• Quotio GitHub Repository
• Managing Providers