Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Diagnostics

Run the built-in diagnostic tool first — it checks all dependencies and reports actionable fixes: 
npx agtos doctor
The doctor command checks Node.js version, Docker, Redis, Ollama, sherpa-onnx models, API credentials, network connectivity, config file validity, and port availability.

​
Common Issues

​
Server won’t start

Symptom: Error: listen EADDRINUSE :::4102Fix: Another process is using the port. Find and stop it, or use a different port:
# Find what's using the port
lsof -i :4102

# Start on a different port
npx agtos start --port 8080
The CLI checks ports 3000, 4100, and 4102 before starting. If any are occupied, it reports which process holds them.
Symptom: Error: agtOS requires Node.js 22 or higherFix: Upgrade Node.js to version 22+. Use nvm for easy version management:
nvm install 22
nvm use 22
Symptom: Server starts but warns about missing credentialsFix: Run the setup wizard:
npx agtos setup
The wizard validates credentials against the actual provider API before saving. You need at least one of:
  • ANTHROPIC_API_KEY (Anthropic, sk-ant-api03- prefix)
  • OPENAI_API_KEY (OpenAI, sk- prefix)

​
Voice pipeline issues

Symptom: Voice sessions connect but transcription never triggersPossible causes:
  1. Models not downloaded: Run npx agtos models download --default to get the default model set (~460MB)
  2. VAD threshold too high: Lower it with SHERPA_VAD_THRESHOLD=0.2 (default is 0.3)
  3. Microphone not capturing: Check browser permissions or device configuration
  4. Wrong audio format: The server expects 16-bit PCM, 16kHz, mono, little-endian
Symptom: tts_start and tts_end messages appear but no audible audioFix: Ensure the TTS model is downloaded and the audio format matches:
# Check model status
npx agtos models list

# Download default TTS model
npx agtos models download kokoro-int8-multi-v1
If using the browser, verify that AudioContext is in the running state (some browsers require a user gesture to start audio).
Symptom: Transcription takes several secondsFix:
  • Use the Moonshine Tiny model for fastest transcription: SHERPA_STT_MODEL=moonshine-tiny-en-int8
  • Increase STT threads: SHERPA_STT_NUM_THREADS=4
  • If using speaches, ensure GPU acceleration is enabled
  • Use streaming STT for real-time partial results: download the Zipformer streaming model with npx agtos models download zipformer-streaming-en-20m

​
Memory issues

Symptom: 503 Memory system not available or memory search returns emptyFix: Episodic and semantic memory require Redis:
# Start Redis via Docker
docker compose up -d redis

# Or install Redis directly
# macOS: brew install redis && brew services start redis
# Ubuntu: sudo apt install redis-server

# Verify Redis is reachable
redis-cli ping  # Should return: PONG
Check the Redis URL: REDIS_URL=redis://localhost:6379
Symptom: Episodic keyword search works but semantic search finds nothingFix: Semantic memory requires both Redis with the RediSearch module and an embedding provider (Ollama):
# Ensure Ollama is running
ollama serve

# Pull the embedding model
ollama pull nomic-embed-text

# Verify the embedding provider
AGTOS_EMBEDDING_PROVIDER=ollama
AGTOS_EMBEDDING_MODEL=nomic-embed-text

​
Connectivity

Symptom: 401 Unauthorized or 403 Forbidden from the Claude APIFix:
  1. Verify your key format: Anthropic API keys start with sk-ant-api03-
  2. Re-run npx agtos setup to validate credentials against the API
  3. Check that the key has not been revoked at console.anthropic.com
  4. If using a custom endpoint: verify ANTHROPIC_BASE_URL
Symptom: ECONNREFUSED 127.0.0.1:11434Fix: Ensure Ollama is installed and running:
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start the server
ollama serve

# Pull required models
ollama pull qwen3:1.7b    # Intent classifier
ollama pull qwen3:4b      # Local query execution
If Ollama is running on a different host: OLLAMA_HOST=http://your-host:11434
Symptom: Claude Desktop shows “Failed to connect to MCP server”Fix:
  1. Ensure agtOS is running: npx agtos status
  2. Verify the MCP port is accessible: curl http://localhost:4100/mcp (should return 405 for GET)
  3. Check your Claude Desktop config (claude_desktop_config.json):
{
  "mcpServers": {
    "agtos": {
      "url": "http://localhost:4100/mcp"
    }
  }
}
  1. Restart Claude Desktop after config changes

​
Docker

Symptom: Docker container can’t connect to Ollama on the hostFix: Use host.docker.internal instead of localhost:
OLLAMA_HOST=http://host.docker.internal:11434
On Linux, you may need --network=host or additional Docker network configuration.

​
Getting Help

  • GitHub Issues: github.com/agtos-ai/agtos/issues
  • System diagnostics: npx agtos doctor (captures all dependency and config status)
  • Health API: curl http://localhost:4102/api/health (shows per-service status)
  • Logs: Set LOG_LEVEL=debug for verbose output