Quick Start

1. Go to chat.pocketcode.in
2. Sign in with your Open WebUI admin account (first signup = admin)
3. Pick a model from the dropdown at the top center of the chat window
4. Type a message → press Enter

Pull a New Model

Models are pulled inside the Ollama container. You can do this from Open WebUI's admin panel OR via the web terminal:

docker exec ollama ollama pull llama3.2:3b
docker exec ollama ollama pull qwen2.5:7b
docker exec ollama ollama pull nomic-embed-text   # for RAG embeddings

Or in Open WebUI: Settings → Admin Panel → Models → Pull a model from Ollama.com. Type the model name (e.g. llama3.2:3b) and click pull.

Common Tasks

Upload a document for Q&A (RAG):

1. Click the 📎 paperclip icon in the chat input
2. Select a PDF, DOCX, MD, or TXT file
3. Ask questions about it — the model reads the document and answers

Build a permanent knowledge base:

1. Profile (top right) → Workspace → Knowledge → + Create Knowledge
2. Name it (e.g. "Company Docs") → upload multiple files
3. Open WebUI chunks the docs, embeds them with nomic-embed-text, stores in ChromaDB
4. In any chat, reference the collection with #Company Docs

Create a custom model with a pinned system prompt:

1. Workspace → Models → + Create a model
2. Choose base model (e.g. llama3.2), add a system prompt, save
3. Now appears in the chat model dropdown

Use as OpenAI-compatible API for other tools:

curl https://chat.pocketcode.in/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:3b",
    "messages": [{"role":"user","content":"Hello"}]
  }'

API key is in Settings → Account → API Keys. Click "Create new secret key".

Useful Settings

This Setup's Quirks

Resources

• Official docs
• GitHub
• Ollama model library

Quick Start

1. Go to sim.pocketcode.in
2. Sign up (first time) or sign in
3. Click + New Workflow
4. Drag blocks from the left panel onto the canvas, connect them with lines
5. Click Run in the top right to test

Block Types

Connecting to Models

Inside any Agent block:

• Local Ollama: Provider = Ollama, base URL is auto-set to http://ollama:11434
• Cloud models via OpenRouter: Provider = OpenAI, base URL = http://openrouter-proxy:4000, API key = whatever you set in LiteLLM config (or leave blank if disabled)
• Direct Claude API: Provider = Anthropic, paste your Anthropic API key

Build Your First Workflow — Hello World

1. Drag Agent block onto canvas
2. Set model: llama3.2:3b
3. Set system prompt: "You are a helpful assistant."
4. Set user message: "What is 2+2?"
5. Click Run → see the output in the right panel

Add Tools to an Agent

Tools let agents take actions. Click an Agent block → Tools tab → add:

• HTTP request — agent can call any URL
• JavaScript — agent can execute code
• Knowledge base — agent can query a Qdrant collection
• Memory — agent can read/write to short-term memory

Common Tasks

Schedule a workflow to run daily:

1. Add a Schedule block → set cron (e.g. 0 9 * * * = daily 9am)
2. Connect it to your first Agent block
3. Click Deploy in top right
4. Workflow now runs automatically

Expose workflow as a webhook (for external apps):

1. Add a Webhook block as the trigger
2. Deploy → copy the webhook URL
3. Any service can POST JSON to it → triggers the workflow

This Setup's Quirks

Resources

• Sim.ai docs
• GitHub

Quick Start

1. Go to n8n.pocketcode.in
2. Sign in with your owner account (first signup = owner)
3. Click + Add workflow
4. Click + in the canvas → search for a trigger (e.g. "Manual")
5. Add more nodes → connect → click Execute Workflow

Node Categories

Build Your First Workflow — Slack to Ollama

1. Trigger: Slack Trigger (or Webhook for testing)
2. Add Ollama Chat Model node — base URL http://ollama:11434, model llama3.2:3b
3. Add AI Agent node — pass the Slack message as user input
4. Add Slack Send Message node — post the AI response back
5. Click Activate in top right

Common Tasks

Use Ollama directly in a workflow:

1. Add Ollama Chat Model node
2. Credentials → New → Base URL: http://ollama:11434
3. Pick model from dropdown

Use cloud models (Claude/GPT) via OpenRouter:

1. Add OpenAI Chat Model node (yes, even for Claude — OpenRouter is OpenAI-compatible)
2. Credentials → New → Base URL: http://openrouter-proxy:4000, API key: any value (or your LiteLLM master key)
3. Set model name to OpenRouter format (e.g. anthropic/claude-3.5-sonnet)

Query the shared Postgres:

1. Add Postgres node
2. Credentials: Host = sim-db-1, Port = 5432, DB = n8n, User/Pass from your .env
3. Pick operation (Select, Insert, Update)

Receive webhooks from external apps:

1. Use Webhook trigger node
2. n8n shows you the test + production URLs
3. For production (after Activate), URL is https://n8n.pocketcode.in/webhook/<your-path>

This Setup's Quirks

Resources

• n8n docs
• Workflow templates

Quick Start

1. Go to openclaw.pocketcode.in
2. If first-time access, you may see a "Pair device" prompt — see "Device Pairing" below
3. Type a message in the chat input → send

Device Pairing

OpenClaw uses a device pairing system. New browsers/devices need to be approved from the CLI:

docker exec -it openclaw node /app/openclaw.mjs devices list
docker exec -it openclaw node /app/openclaw.mjs devices approve <UUID>

Common Tasks

Switch the active model:

1. Settings (gear icon) → Models
2. Choose from local Ollama or configured cloud providers

Configure cloud model providers:

1. Settings → API Keys → add Anthropic / OpenAI / OpenRouter keys
2. Models become available in the chat selector

Start a new agent session:

1. Click + New Session (sidebar)
2. Pick a model + system prompt template (or custom)
3. Sessions persist in the OpenClaw database

This Setup's Quirks

Resources

• OpenClaw docs (if available)

Quick Start — host CLI (recommended)

Installed in ~/.claude/bin/ on the VPS. Open the web terminal (or SSH in) and:

cd ~/pocketcode-project
claude

If this is the first time, you'll get a sign-in URL — open it in your local browser, paste the returned code. The CLI saves credentials under ~/.claude/; subsequent runs are instant.

Quick Start — containerised variant

Uses a long-running claude-code container with ~/pocketcode-project mounted at /workspace:

docker exec -it claude-code bash
claude

First run prompts for an Anthropic API key. Paste yours from console.anthropic.com → API Keys (or sign in interactively, same as the host CLI).

Basic Usage

• claude — start interactive session in current directory
• claude "fix the bug in main.py" — give a task directly
• claude --continue — resume the last conversation
• /help inside the session — see all commands
• /clear — clear the conversation
• /cost — see token usage and cost

Working with the Stack

Host CLI: just cd into whichever directory matters and run claude. Everything in ~/pocketcode-project is directly accessible.

Containerised variant: ~/pocketcode-project is bind-mounted at /workspace inside the container.

cd ~/pocketcode-project/services/sim          # or /workspace/services/sim in container
claude "review docker-compose.prod.yml and suggest improvements"

Common Tasks

Code review a file:

claude "review operations/manage/start-all.sh and find any race conditions"

Generate a new service config:

claude "create a docker-compose.yml for a Redis instance on the ai-stack network with persistence"

Debug a failing container:

docker logs sim-simstudio-1 --tail 100 > /tmp/logs.txt
claude "read /tmp/logs.txt and tell me why this container is restarting"

This Setup's Quirks

Resources

• Claude Code docs
• npm package

What This Is

A LiteLLM proxy that exposes an OpenAI-compatible API on port 4000. You configure cloud providers (OpenAI, Anthropic, OpenRouter.ai, etc.) once, and any tool that speaks OpenAI's API can use them.

From Inside the Stack

Containers on the ai-stack network reach the proxy at:

http://openrouter-proxy:4000

From Outside (via HTTPS)

https://openrouter.pocketcode.in

Configured Models

LiteLLM supports two configuration styles. Pick whichever matches your install:

A. Single-model CLI form — what the v1.0–v1.5 setup guide installs. Passes the model on the command line, no config file:

docker run -d --name openrouter-proxy --network ai-stack \
  -e OPENROUTER_API_KEY="sk-or-v1-..." \
  -p 4000:4000 \
  ghcr.io/berriai/litellm:main-latest \
  --model openrouter/anthropic/claude-3.5-sonnet --port 4000

Any client calling /v1/chat/completions with any model name gets routed to the single configured model. Simple, good for a one-model lab.

B. Multi-model YAML form — if you want to expose several backends (Claude, GPT-4, Llama, etc.) through one proxy and have clients choose at request time. Mount a config file:

model_list:
  - model_name: claude-sonnet-4
    litellm_params:
      model: anthropic/claude-sonnet-4-20250514
      api_key: os.environ/ANTHROPIC_API_KEY
  - model_name: gpt-4o
    litellm_params:
      model: openai/gpt-4o
      api_key: os.environ/OPENAI_API_KEY
  - model_name: llama-3.3-70b
    litellm_params:
      model: openrouter/meta-llama/llama-3.3-70b-instruct
      api_key: os.environ/OPENROUTER_API_KEY

Then replace the trailing --model … CLI args in the run script with --config /app/config.yaml and mount the file with -v ~/ai-stack/openrouter-proxy/litellm-config.yaml:/app/config.yaml.

Common Tasks

Test from terminal:

curl https://openrouter.pocketcode.in/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "messages": [{"role":"user","content":"Hello"}]
  }'

Add a new model:

1. Edit ~/ai-stack/openrouter-proxy/litellm-config.yaml → add a new entry
2. Restart the container: docker restart openrouter-proxy
3. The new model_name is now usable everywhere

Use from Python:

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.pocketcode.in/v1",
    api_key="any-string"  # disabled in default config
)

response = client.chat.completions.create(
    model="claude-sonnet-4",
    messages=[{"role": "user", "content": "Hello"}]
)
print(response.choices[0].message.content)

This Setup's Quirks

Resources

• LiteLLM docs
• OpenRouter.ai model list

What This Is

The raw Ollama API. Most users interact with Ollama via Open WebUI (recommended for chat) or via the SDK in code. This page covers direct API usage.

Endpoints

Common Calls

List installed models:

curl https://ollama.pocketcode.in/api/tags

Chat completion:

curl https://ollama.pocketcode.in/api/chat -d '{
  "model": "llama3.2:3b",
  "messages": [{"role":"user","content":"Hello"}],
  "stream": false
}'

Generate embeddings (for RAG):

curl https://ollama.pocketcode.in/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "The text to embed"
}'

Pull a new model (from terminal, not API recommended):

docker exec ollama ollama pull llama3.2:3b
docker exec ollama ollama pull qwen2.5:7b
docker exec ollama ollama pull nomic-embed-text

Model Recommendations (CPU mode)

This Setup's Quirks

Resources

• Ollama API reference
• Model library

What This Is

A high-performance vector database for semantic search, RAG retrieval, and similarity matching. Stores embeddings (numerical representations of text, images, etc.) and finds nearest neighbors to a query vector. Bring your own embedding model — Ollama on this server, or any OpenAI-compatible cloud model via the OpenRouter proxy.

This Setup's Access Pattern

Qdrant is the only service that opens at its direct subdomain instead of through the launcher iframe wrapper used by the 8 other tools. The launch-pad card on pocketcode.in for Qdrant points straight to https://qdrant.pocketcode.in/dashboard.

You still get full protection and feature parity with other services:

• Caddy auth_gate still gates the subdomain — anonymous visitors get 302'd to the master login at pocketcode.in
• A session-poll script is injected into Qdrant's HTML response via Caddy's replace-response plugin. It polls /verify every 15 seconds (and on tab focus). When your master session expires, an overlay appears in the Qdrant tab and counts down to redirect — same UX as every other service.

Web UI Layout

When you open qdrant.pocketcode.in/dashboard, the Web UI smart-routes:

• Zero collections → lands on #/welcome (Get Started cards)
• One or more collections → lands on #/collections (collection list)

Left sidebar items:

Internal vs External Access

The v1.10 Query API

Since Qdrant v1.10, the unified Query API at POST /collections/{name}/points/query replaces the older endpoints (/points/search, /points/recommend, /points/scroll). The same endpoint handles:

• Nearest neighbors search (default behavior)
• Search by point ID (recommend-style: "find things similar to point #42")
• Recommendations with positive/negative examples
• Scrolling through points (pagination)
• Random sampling
• Hybrid (dense + sparse) and multi-stage retrieval via prefetch

The older endpoints still work for backward compatibility, but new code should use /points/query.

End-to-End: Create, Embed, Insert, Query

These examples run from the web terminal (or any host shell) using internal Docker networking — no auth needed. From outside the server, use https://qdrant.pocketcode.in with a valid session cookie.

1. Create a collection (768-dim vectors, cosine distance — matches nomic-embed-text):

curl -X PUT http://qdrant:6333/collections/my-docs \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {"size": 768, "distance": "Cosine"}
  }'

2. Create payload indexes BEFORE inserting data (recommended — see the callout below):

curl -X PUT http://qdrant:6333/collections/my-docs/index \
  -H "Content-Type: application/json" \
  -d '{"field_name": "category", "field_schema": "keyword"}'

curl -X PUT http://qdrant:6333/collections/my-docs/index \
  -H "Content-Type: application/json" \
  -d '{"field_name": "created_at", "field_schema": "datetime"}'

3. Get an embedding from Ollama, insert into Qdrant:

EMB=$(curl -s http://ollama:11434/api/embeddings \
  -d '{"model":"nomic-embed-text","prompt":"The quick brown fox"}' \
  | jq -c .embedding)

curl -X PUT http://qdrant:6333/collections/my-docs/points \
  -H "Content-Type: application/json" \
  -d "{
    \"points\": [{
      \"id\": 1,
      \"vector\": $EMB,
      \"payload\": {\"text\": \"The quick brown fox\", \"category\": \"animals\"}
    }]
  }"

4. Query (v1.10 Query API — /points/query):

QUERY_EMB=$(curl -s http://ollama:11434/api/embeddings \
  -d '{"model":"nomic-embed-text","prompt":"fast animal"}' \
  | jq -c .embedding)

curl -X POST http://qdrant:6333/collections/my-docs/points/query \
  -H "Content-Type: application/json" \
  -d "{
    \"query\": $QUERY_EMB,
    \"limit\": 5,
    \"with_payload\": true
  }"

Filtering — Where Most People Trip Up

Filters use three boolean groups combined with field conditions. The groups:

• must — ALL conditions must match (AND)
• should — at least one condition must match (OR)
• must_not — none of the conditions can match (NOT)

Condition types (most common):

Filter inside a query — find similar vectors but only in category animals, excluding inactive ones:

curl -X POST http://qdrant:6333/collections/my-docs/points/query \
  -H "Content-Type: application/json" \
  -d "{
    \"query\": $QUERY_EMB,
    \"limit\": 5,
    \"with_payload\": true,
    \"filter\": {
      \"must\":     [ {\"key\": \"category\", \"match\": {\"value\": \"animals\"}} ],
      \"must_not\": [ {\"key\": \"status\",   \"match\": {\"value\": \"inactive\"}} ]
    }
  }"

Nested payload fields use dot notation: {"key": "metadata.author", "match": {"value": "alice"}}.

Payload Indexes — The Performance Multiplier

If you filter on a payload field, you almost certainly want a payload index on it. Without one, Qdrant filters by scanning every point match — slow on large collections.

Python Client (qdrant-client)

The official Python library is idiomatic and matches the REST API closely:

from qdrant_client import QdrantClient
from qdrant_client.models import (
    VectorParams, Distance, PointStruct,
    Filter, FieldCondition, MatchValue,
)

# From another container on ai-stack network:
client = QdrantClient(host="qdrant", port=6333)

# From host shell:
# client = QdrantClient(host="localhost", port=6333)

# 1. Create collection
client.create_collection(
    collection_name="my-docs",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE),
)

# 2. Create payload index (before inserting)
client.create_payload_index(
    collection_name="my-docs",
    field_name="category",
    field_schema="keyword",
)

# 3. Upsert points
client.upsert(
    collection_name="my-docs",
    points=[
        PointStruct(
            id=1,
            vector=embedding_768,  # list of 768 floats from your embedding model
            payload={"text": "...", "category": "animals"},
        ),
    ],
)

# 4. Query (unified Query API)
result = client.query_points(
    collection_name="my-docs",
    query=query_embedding_768,
    limit=5,
    query_filter=Filter(must=[
        FieldCondition(key="category", match=MatchValue(value="animals")),
    ]),
).points

for hit in result:
    print(hit.id, hit.score, hit.payload["text"])

Common Tasks

List all collections:

curl http://qdrant:6333/collections

Collection info (size, indexed fields, vector params, point count):

curl http://qdrant:6333/collections/my-docs

Scroll through all points (paginated iteration):

curl -X POST http://qdrant:6333/collections/my-docs/points/scroll \
  -H "Content-Type: application/json" \
  -d '{"limit": 100, "with_payload": true, "with_vector": false}'

The response includes next_page_offset; pass it as offset on the next call to continue.

Delete a collection:

curl -X DELETE http://qdrant:6333/collections/my-docs

Snapshot a collection (for backup / portability):

curl -X POST http://qdrant:6333/collections/my-docs/snapshots

Embedding Models in This Stack

Hybrid Search (Dense + Sparse)

Qdrant supports hybrid retrieval: combine a dense semantic vector with a sparse keyword/BM25 vector and fuse the rankings. The v1.10 Query API uses prefetch with reciprocal rank fusion or distance-based reranking. The built-in Hybrid Search tutorial in the dashboard (Tutorial → Hybrid Search) walks through the full setup with sample data.

Multi-Tenancy

For SaaS-style use cases where one collection serves multiple isolated tenants, the recommended pattern:

1. One large collection (not one per tenant — fewer indexes, better RAM use)
2. Every point has a tenant_id in payload
3. Create a keyword payload index on tenant_id
4. Every query filters by tenant: filter: {"must": [{"key": "tenant_id", "match": {"value": "..."}}]}

Built-in tutorial: dashboard → Tutorials → Multitenancy.

Persistence

The qdrant container in this stack mounts a Docker volume at /qdrant/storage. Collections survive container restarts and reboots. To wipe everything (destructive — backs up nothing):

docker stop qdrant
docker rm qdrant
docker volume rm qdrant-data
bash ~/ai-stack/run-qdrant.sh

Resources

• Qdrant official documentation
• Query API reference (v1.10+)
• Filtering guide
• Indexing & payload indexes
• Web UI overview
• Full OpenAPI reference
• qdrant-client Python library

Quick Start

1. Go to pgadmin.pocketcode.in
2. Sign in with email/password from PGADMIN_DEFAULT_EMAIL / PGADMIN_DEFAULT_PASSWORD env vars
3. Add a new server connection (first-time only)

Connect to the Shared Postgres

In pgAdmin: right-click Servers → Register → Server. Then:

What Databases Are There?

Common Tasks

Run a query:

1. Navigate to a database in the tree
2. Right-click → Query Tool
3. Type SQL → F5 to execute

Export a table to CSV:

1. Right-click a table → Import/Export Data
2. Choose Export, set CSV format, browse for output location

Backup the whole stack DB:

docker exec sim-db-1 pg_dumpall -U postgres > ~/ai-stack/backups/all-$(date +%Y%m%d).sql

pgvector queries (Sim.ai uses this):

-- Find vectors closest to a target
SELECT id, content, embedding <-> '[0.1, 0.2, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 5;

This Setup's Quirks

Resources

• pgAdmin docs
• pgvector reference

What This Is

A real bash shell on your VPS, running in your browser. The prompt shows your actual server hostname (root@srv1234:~#) — not a container ID — because ttyd runs as a host systemd service, not in Docker. Full root access: you can apt install packages, run systemctl, edit any file, and of course docker ps / docker exec any container. Perfect for quick admin from your phone, tablet, or any browser, without SSH client setup.

Quick Start

1. Go to terminal.pocketcode.in
2. If not logged in → bounces you to pocketcode.in to log in
3. Terminal loads — you see root@<your-vps-hostname>:~# prompt
4. Type any command and press Enter

Keyboard Shortcuts

What You Can Do

Manage every container:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
docker logs sim-simstudio-1 --tail 50
docker restart n8n
docker exec -it ollama bash

Edit any config file (no SSH needed):

nano ~/ai-stack/caddy/Caddyfile
nano ~/ai-stack/sim/.env
docker exec caddy caddy reload --config /etc/caddy/Caddyfile

Install host packages (you're root, no sudo needed):

apt install -y htop btop ncdu jq tmux tree
htop                          # live process viewer
ncdu /root/ai-stack           # disk usage explorer

Use stack aliases (already loaded — this is your real bash):

ai-start          # bring up all containers
ai-stop           # graceful shutdown
ai-doctor         # full diagnostic
ai-status         # quick container health snapshot
ai-logs n8n       # tail any service's logs
ai-reboot         # restart whole stack

Pull new Ollama models:

docker exec ollama ollama pull qwen2.5:7b
docker exec ollama ollama list

Run Claude Code from here:

docker exec -it claude-code bash
claude "review the start-all.sh script for race conditions"

Query the shared Postgres:

docker exec -it sim-db-1 psql -U postgres -d simstudio
\dt    -- list tables
\q     -- quit

Manage the ttyd service itself:

systemctl status ttyd       # is it running?
systemctl restart ttyd      # clears any stuck sessions
journalctl -u ttyd -f       # live log tail

How This Setup Works

Resources

• ttyd on GitHub — the web terminal binary
• Docker CLI reference

Architecture

One PostgreSQL container — sim-db-1 running pgvector/pgvector:pg17 — hosts every database in the stack. Sim.ai brings it up (it's in the Sim.ai compose file), but pgAdmin, n8n, OpenClaw, and any custom workflow share the same instance. The container sits on two Docker networks simultaneously: sim_default (Sim.ai's own) and ai-stack (the rest of the stack), so anyone can reach it.

The Six Databases

Connection Strings

pgvector Extension

Already installed in every database. Use it for semantic search inside Postgres without needing Qdrant for small datasets:

-- nomic-embed-text returns 768-dim vectors
CREATE TABLE documents (
  id BIGSERIAL PRIMARY KEY,
  content TEXT,
  embedding vector(768),
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Index for fast similarity search
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- Find nearest neighbors
SELECT id, content, embedding <=> '[0.1, 0.2, ...]'::vector AS distance
FROM documents
ORDER BY distance
LIMIT 5;

Common Tasks

Get a psql shell:

docker exec -it sim-db-1 psql -U postgres -d ailab

List all databases:

docker exec sim-db-1 psql -U postgres -l

Backup a single database:

docker exec sim-db-1 pg_dump -U postgres -Fc -d n8n > ~/backups/n8n-$(date +%Y%m%d).pgcustom

Backup everything (pg_dumpall):

docker exec sim-db-1 pg_dumpall -U postgres > ~/backups/all-$(date +%Y%m%d).sql

Restore from backup:

cat ~/backups/all-20260516.sql | docker exec -i sim-db-1 psql -U postgres

Create a new database for your project:

-- via pgAdmin Query Tool or psql shell
CREATE DATABASE my_project;
\c my_project
CREATE EXTENSION vector;

Connection Pool Limits

Default Postgres config allows ~100 concurrent connections. Sim.ai + n8n + OpenClaw typically use ~30. If you start running into "too many connections" errors, increase the limit:

docker exec sim-db-1 psql -U postgres -c "ALTER SYSTEM SET max_connections=200;"
docker restart sim-db-1

This Setup's Quirks

Resources

• PostgreSQL 17 docs
• pgvector reference
• pgAdmin docs

The Network Architecture

Every container in the stack is on the ai-stack Docker network. Docker provides automatic DNS resolution between containers using their container names. Sim.ai's compose stack has its own internal network sim_default, and sim-db-1 straddles both so services on either network can reach it.

Internal Hostnames

Inside any container on ai-stack, these hostnames resolve automatically:

Why Use Internal Hostnames?

• Faster — stays inside Docker, no DNS over the internet, no TLS handshake
• More reliable — no dependence on external DNS or Caddy being up
• No auth wall — gateway auth is at Caddy; internal calls skip it (intentional: they're already trusted within Docker)
• Container IPs change on restart, but the hostname always resolves to the current IP

Common Patterns

n8n calling Ollama: In n8n's Ollama Chat Model credentials, set Base URL to:

http://ollama:11434

n8n calling OpenRouter (cloud models) via the proxy:

Base URL: http://openrouter-proxy:4000
API Key:  any-non-empty-string

Sim.ai calling Ollama: already wired via Sim.ai's OLLAMA_URL=http://ollama:11434 env var.

Custom script calling everything from a terminal:

curl http://ollama:11434/api/tags
curl http://qdrant:6333/collections
curl http://openrouter-proxy:4000/v1/models

Connecting from a brand-new container you create: Add it to the ai-stack network:

docker run -d --name my-app \
  --network ai-stack \
  -e DB_URL=postgres://postgres:PASS@sim-db-1:5432/ailab \
  -e LLM_URL=http://ollama:11434 \
  my-image:latest

Adding a Service to ai-stack

1. Run with --network ai-stack flag (or networks: [ai-stack] in compose)
2. Once started, it can reach every other container by name
3. If it needs to be public via HTTPS, add a Caddyfile block per Tab 13

Auto-SSO Across Services

The gateway at pocketcode.in ships with optional auto-SSO: when you sign in at the apex, hidden iframes silently log you into Sim.ai, Open WebUI, and n8n using credentials stored in ~/ai-stack/auth-gateway/.env. Three things are happening:

Which services auto-SSO works for

The /_sso_init endpoint

Each SSO-enabled subdomain has this Caddyfile block:

sim.pocketcode.in {
    import auth_gate
    handle /_sso_init {
        reverse_proxy auth-gateway:7000 {
            rewrite /sso-init/sim
        }
    }
    reverse_proxy sim-simstudio-1:3000
}

Browser loads /_sso_init in a hidden iframe → Caddy proxies to gateway → gateway logs into Sim.ai server-side → response carries Set-Cookie for the user → iframe posts a status message back to home.html.

What logging out does

• Logout at pocketcode.in: only the gateway cookie is cleared. Service-internal cookies remain valid. But Caddy now sees no gateway cookie → every *.pocketcode.in request gets 302'd to the login page. After re-login, every service is instantly accessible (their sessions never died).
• Logout inside a service (e.g., clicking Sim.ai's own "Logout" button): that service's session cookie is cleared. The next watchdog tick at pocketcode.in (≤ 2 min) re-runs /_sso_init for that service and restores the session.
• Closing the pocketcode tab: Watchdog stops. Sessions naturally expire after their normal TTL. Re-opening pocketcode restarts the watchdog.

Troubleshooting

"Host not found" / "getaddrinfo ENOTFOUND":

• Verify the container is on ai-stack: docker inspect <name> --format='{{json .NetworkSettings.Networks}}'
• If missing, attach it: docker network connect ai-stack <name>
• For sim-db-1 specifically, ai-start auto-reconnects it after Sim.ai recompose

"Connection refused" but container is up:

• The service may not be listening on 0.0.0.0 internally. Inspect: docker exec <name> netstat -tlnp
• Or it's still booting. docker logs <name> --tail 20

n8n shows "Failed to load model catalog" briefly at start:

• Transient Docker DNS race after a recompose. ai-doctor filters it. Self-heals within ~10 seconds.

Resources

• Docker networking
• See Tab 9 (Inter-Service Comms) in the setup guide for initial wiring

What's Mounted Where

Two file paths are mounted inside every relevant service container, so data can flow between them without HTTP roundtrips:

When to Use Which

How to Use From Each Service

From the web terminal:

ls /shared          # Inside the terminal container
ls /uploads
ls ~/ai-stack/uploads   # Same as /uploads — terminal's /root is mounted

From n8n (Read/Write Files node): point at /shared/output.csv or /uploads/input.csv directly. n8n already has both mounts.

From Sim.ai workflows: use the Function block with Node.js fs:

const fs = require('fs');
const content = fs.readFileSync('/uploads/data.json', 'utf-8');
const data = JSON.parse(content);
return { items: data };

From Open WebUI: upload files through the UI (paperclip icon) — they're stored in the open-webui-data volume separately. To make a host file available, copy it to /uploads first, then upload via the UI.

From OpenClaw and custom scripts: Same — read/write to /shared or /uploads within their containers.

Common Workflows

Drop a file from your Mac, process it in n8n:

scp ~/Documents/data.csv root@YOUR_SERVER_IP:~/ai-stack/uploads/data.csv

In n8n: Read Binary File node → /uploads/data.csv → process. n8n sees the file immediately, no restart needed.

n8n writes a result, Sim.ai picks it up:

• n8n workflow ends with a Write Binary File node → /shared/n8n-output.json
• Sim.ai workflow has a Function block reading /shared/n8n-output.json
• Two services collaborating without HTTP or queues

Build a dataset for Qdrant:

1. scp folder of PDFs to ~/ai-stack/uploads/pdfs/
2. From terminal: docker exec -it <some-python-container> python ingest.py /uploads/pdfs
3. Script chunks files, embeds via Ollama at http://ollama:11434, posts to Qdrant at http://qdrant:6333

Inspecting Each From the Host

The bind-mount (/uploads) is trivially visible on the host:

ls -la ~/ai-stack/uploads/
du -sh ~/ai-stack/uploads/

The Docker volume (/shared) lives under Docker's internal storage:

docker volume inspect ai-shared-data
# shows: Mountpoint /var/lib/docker/volumes/ai-shared-data/_data
ls -la /var/lib/docker/volumes/ai-shared-data/_data/

Backup & Restore

Backup /uploads (host bind-mount — just tar it):

tar czf ~/backups/uploads-$(date +%Y%m%d).tar.gz -C ~/ai-stack uploads/

Backup /shared (Docker volume — needs a helper container):

docker run --rm \
  -v ai-shared-data:/data \
  -v ~/backups:/backup \
  alpine tar czf /backup/shared-$(date +%Y%m%d).tar.gz -C /data .

Restore the volume:

docker run --rm \
  -v ai-shared-data:/data \
  -v ~/backups:/backup \
  alpine sh -c "cd /data && tar xzf /backup/shared-20260516.tar.gz"

Permissions Note

This Setup's Quirks

Resources

• Docker volumes docs
• Bind mounts docs
• See Tab 10 (Shared Storage) in the setup guide for initial setup

Recipe 1: Slack-to-Ollama Chatbot (via n8n)

Listen for Slack messages, route through Ollama, respond.

1. In n8n: Slack Trigger → AI Agent (Ollama, model llama3.2:3b) → Slack Send Message
2. Use the message text as user input to the agent
3. Pass the agent output back to Slack channel

Recipe 2: Document Q&A System (Open WebUI + Ollama)

1. Pull embedding model: docker exec ollama ollama pull nomic-embed-text
2. In Open WebUI: Settings → Documents → Embedding Model = nomic-embed-text
3. Workspace → Knowledge → New Collection → upload PDFs
4. In chat, reference with #collection-name

Recipe 3: Scheduled Web Scraping (n8n + OpenRouter)

1. n8n: Schedule trigger (daily 9am) → HTTP Request (fetch URL) → AI Agent (summarize via OpenRouter Claude) → Send Email/Slack
2. Claude does the summarization since it's better at structured output
3. Costs ~$0.01-0.05 per run depending on page size

Recipe 4: Custom RAG Pipeline (Ollama + Qdrant + Sim.ai)

1. Create a Qdrant collection (size 768 for nomic-embed-text)
2. In Sim.ai: build a workflow that takes a query, embeds via Ollama, searches Qdrant, passes top-K results + query to an Agent block
3. Agent uses retrieved context + query to produce grounded answer

Recipe 5: Multi-Model Comparison (LiteLLM)

Compare outputs from local Ollama vs cloud Claude vs GPT side-by-side.

PROMPT="Explain quantum computing in 2 sentences"

# Local Ollama
curl -s http://localhost:11434/api/generate \
  -d "{\"model\":\"llama3.2:3b\",\"prompt\":\"$PROMPT\",\"stream\":false}" \
  | jq -r .response

# Cloud Claude via OpenRouter proxy
curl -s http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d "{\"model\":\"claude-sonnet-4\",\"messages\":[{\"role\":\"user\",\"content\":\"$PROMPT\"}]}" \
  | jq -r '.choices[0].message.content'

Recipe 6: Voice Pipeline (Open WebUI + Whisper)

Open WebUI supports voice input via Whisper. To enable:

1. Settings → Audio → STT Engine: select "Local Whisper"
2. Pick a Whisper model size (base / small / medium)
3. Click 🎤 icon in chat input → speak → transcribed and sent

Recipe 7: Backup & Restore the Stack

Backup (run daily as a cron job or n8n workflow):

#!/bin/bash
DATE=$(date +%Y%m%d-%H%M)
mkdir -p ~/backups/$DATE

# Postgres dump
docker exec sim-db-1 pg_dumpall -U postgres > ~/backups/$DATE/postgres.sql

# Critical volumes (n8n encryption key, Open WebUI chats, etc.)
docker run --rm -v n8n-data:/data -v ~/backups/$DATE:/backup \
  alpine tar czf /backup/n8n-data.tar.gz -C /data .

docker run --rm -v open-webui-data:/data -v ~/backups/$DATE:/backup \
  alpine tar czf /backup/open-webui-data.tar.gz -C /data .

# Caddy data (certs)
docker run --rm -v caddy_data:/data -v ~/backups/$DATE:/backup \
  alpine tar czf /backup/caddy_data.tar.gz -C /data .

# Compress everything
tar czf ~/backups/$DATE.tar.gz -C ~/backups $DATE
rm -rf ~/backups/$DATE

Recipe 8: Manage Stack from the Web Terminal

Everything in this guide can be done from terminal.pocketcode.in in your browser:

ai-start          # bring up all containers
ai-stop           # shut down cleanly
ai-doctor         # diagnostic scan
ai-logs SERVICE   # tail any service's logs
ai-status         # quick health check

The PocketCodeIn stack runs HTTP MCP servers behind Caddy on mcp-*.pocketcode.in subdomains. They are NOT browser-interactive — they're API endpoints consumed by LLM clients. Every MCP uses the same authentication: Authorization: Bearer <MCP_BEARER_TOKEN>, where the token lives in ~/pocketcode-project/secrets/secrets.json under mcp.bearer_token.

mcp-postgres

URL: https://mcp-postgres.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-postgres/
Connects as: postgres superuser → sim-db-1 (5 databases)

Tools exposed

Using from Claude Code (on the VPS)

Already wired up via ~/pocketcode-project/.mcp.json. To launch a Claude Code session that picks it up:

tmux new -s claude
cd ~/pocketcode-project
source secrets/secrets.env    # exports MCP_BEARER_TOKEN
claude                        # reads .mcp.json, connects to mcp-postgres over HTTPS

In the Claude Code session, the MCP tools show up under /mcp. Ask Claude things like "list all tables in the n8n database" or "how many workflows are saved in sim?"

Using from Claude Desktop (on your Mac)

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "pocketcode-postgres": {
      "type": "http",
      "url": "https://mcp-postgres.pocketcode.in/mcp",
      "headers": {
        "Authorization": "Bearer <PASTE MCP_BEARER_TOKEN HERE>"
      }
    }
  }
}

Get the token value with jq -r .mcp.bearer_token ~/pocketcode-project/secrets/secrets.json on the VPS, then paste into the Mac config. Restart Claude Desktop.

Quick verification (manual)

TOKEN="<your MCP_BEARER_TOKEN>"

# Health check — no auth needed
curl https://mcp-postgres.pocketcode.in/health
# → OK

# List databases — proper MCP handshake then tool call
INIT=$(curl -s -D /tmp/h https://mcp-postgres.pocketcode.in/mcp \
  -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"clientInfo":{"name":"curl","version":"0"}}}')

SESSION=$(grep -i '^mcp-session-id:' /tmp/h | awk '{print $2}' | tr -d '\r')

curl -s -X POST https://mcp-postgres.pocketcode.in/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}'

curl -s -X POST https://mcp-postgres.pocketcode.in/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_databases","arguments":{}}}'

mcp-airtable

URL: https://mcp-airtable.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-airtable/
Default base: the call_logs base from secrets.json → airtable.base_call_logs. Override per-tool with the base_id argument.

Tools (full CRUD)

Example: log a call from the voice agent (Phase 4 use case)

create_record(
  table="Call Logs",
  fields={
    "caller_id": "+15551234567",
    "timestamp": "2026-05-20T11:23:45Z",
    "duration_sec": 142,
    "transcript": "Caller: Hi, I need help with...",
    "summary": "Customer asked about pricing tier; agent quoted KVM 4 plan."
  }
)

mcp-web-search

URL: https://mcp-web-search.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-web-search/
Backend: Brave Search API. Free tier 2000 queries/month. Check quota at api.search.brave.com/app/dashboard.

Tool

Returns {query, total_results, results: [{title, url, description, age, language, is_source_local}]}. On rate-limit (429), returns {error: 'Brave Search rate limit hit', hint: ...} so the LLM can react gracefully.

Example queries

web_search(query="latest news on Anthropic")
web_search(query="Hostinger KVM 8 pricing", country="IN")
web_search(query="MCP protocol spec", freshness="month", count=20)
web_search(query="open source TTS comparison", safesearch="strict")

mcp-sim

URL: https://mcp-sim.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-sim/
What it is: the architectural replacement for the dropped mcp-n8n. Wraps sim.ai's REST API for workflow CRUD + execution — the flagship "Claude Code builds workflows" use case.

Tools (9)

Auth — why service-account login (not API key)

Sim has two auth paths: personal API keys and BetterAuth session cookies. API keys are restricted to per-workflow execution endpoints — they cannot list, create, update, or delete workflows. CRUD requires a real user session. So mcp-sim uses session cookies via auto-login with the operator's credentials (same ones auth-gateway uses for browser SSO). 30-day session TTL; auto-refreshes on 401. SIM_SSO_EMAIL + SIM_SSO_PASSWORD come from secrets.json via regenerate-env.sh.

Example flow — "Claude Code builds a workflow"

# 1. Discover available workspaces
list_workspaces()
# → {workspaces: [{id: "4a5acb0a...", name: "Nishant's Workspace", role: "owner"}]}

# 2. List what's already there
list_workflows(workspace_id="4a5acb0a...")
# → {workflows: [...]}

# 3. Create a new workflow shell
create_workflow(name="YouTube Summarizer", workspace_id="4a5acb0a...",
                description="Take a YouTube URL, return a one-paragraph summary")
# → {id: "wf_xyz...", name: "YouTube Summarizer", ...}

# 4. (Use sim's UI or the state endpoint to populate nodes/edges —
#    this is the part that's still better done visually for now)

# 5. Execute it
execute_workflow(workflow_id="wf_xyz...", input={"url": "https://youtube.com/watch?v=..."})
# → {success: true, output: "...", execution_id: "..."}

# 6. Inspect logs
get_workflow_logs(workflow_id="wf_xyz...")

mcp-n8n

URL: https://mcp-n8n.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-n8n/
What it is: companion to mcp-sim — wraps n8n's public REST API for workflow CRUD + execution. Lives alongside mcp-sim; pick whichever workflow engine fits the task.

Tools (12)

Auth

Uses n8n's public API key (header X-N8N-API-KEY). Minted programmatically via n8n's /rest/api-keys endpoint with all 68 scopes granted. Stored at secrets.json → services.n8n.api_key, exported as N8N_API_KEY by regenerate-env.sh.

yt-dlp-ui (browser UI for downloads/transcripts)

URL: https://ytdl.pocketcode.in (master-login gated)
Source: ~/pocketcode-project/services/yt-dlp-ui/
What it is: a 3-tab single-page web app for using yt-dlp from the browser — with real-time progress bars on downloads. Companion to mcp-yt-dlp (which serves LLM agents). Same dependencies + shared data/downloads/ directory.

Three tabs

1. 📎 Paste URL — paste any yt-dlp-supported URL, click "Get info" to fetch metadata (title, channel, duration, views, thumbnail). Then options panel: resolution dropdown (240→2160 or "max"), audio format/quality dropdowns, optional trim (HH:MM:SS start/end). Three action buttons: Download Video, Extract Audio, Get Transcript.
2. 🔎 Search YouTube — search query + limit → grid of result cards (title, channel, duration, view count). Clicking a card loads it into the URL tab.
3. 📁 Recent files — lists everything in data/downloads/ with one-click "Download" buttons that stream the file to the user's computer.

Real-time progress

When you click Download Video or Extract Audio, yt-dlp-ui runs yt-dlp directly as a subprocess with --newline --progress-template. Each progress line is parsed and emitted as a Server-Sent Event to the browser. The on-screen progress bar fills in real time with downloaded/total MB, current speed, and ETA. Post-processing stages (ExtractAudio, Merger) are shown as status text. On completion, you see a "Done" indicator with a direct "Download to your computer" link.

How it relates to mcp-yt-dlp

Calling yt-dlp-ui for search/metadata internally proxies to mcp-yt-dlp via HTTP+bearer, so there's one canonical implementation of those tools. Downloads run yt-dlp directly in yt-dlp-ui because real-time progress streaming needs subprocess management that doesn't fit MCP's request/response shape.

mcp-yt-dlp

URL: https://mcp-yt-dlp.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-yt-dlp/
Design lineage: tool surface inspired by kevinwatt/yt-dlp-mcp (MIT) — reimplemented natively in Python to match this project's existing FastMCP + subprocess pattern. No Node.js / Deno runtime needed.

Tools (8)

Downloads location

Files written by download_video and download_audio land in ~/pocketcode-project/data/downloads/ on the host. The tool response includes both container path (/downloads/<file>) and host path so other services can reference them.

scp ~/Downloads/cookies.txt root@VPS:/root/pocketcode-project/data/downloads/

Example tool calls

ytdlp_search_videos(query="livekit voice agent tutorial", limit=5)

ytdlp_get_video_metadata_summary(url="https://youtube.com/watch?v=...")
# → {title, channel, duration_str, view_count, description_preview, ...}

ytdlp_download_transcript(url="https://youtube.com/watch?v=...", language="en")
# → {url, language, text}   (timing-stripped, ready to summarize)

ytdlp_download_audio(url="...", format="mp3", quality="192")
# → file lands at ~/pocketcode-project/data/downloads/<id>_<title>.mp3

voice-playground — browser harness + outbound dialer

URL: https://voice.pocketcode.in (master-login gated)
Source: ~/pocketcode-project/services/voice-playground/
What it is: a single-page app with two tabs — Audio test with agent (talk to Adrian from your browser) and Outbound AI call (dial a real phone, listen + watch live transcript, schedule callbacks, view call history).

Architecture (end-to-end)

The diagram below traces every path the playground supports — browser-only test calls (left side), outbound PSTN dial-outs (middle), the agent's runtime pipeline (LLM/STT/TTS + tools), and the operational data plane (voice_pg + Qdrant + Airtable outbox + scheduled-callback auto-dialer).

Flow narrative

1. Audio Test path. Browser POSTs /api/token → voice-playground mints a LiveKit token, pre-creates the room with metadata (llm, tts, agent_name, agent_gender, product_kb="audio_test_mode.md") → browser joins room and publishes mic → the livekit-agent worker auto-dispatches into the room → STT→LLM→TTS pipeline → audio streams back to the browser.
2. Outbound path. Browser POSTs /api/dial with to_number, optional supervisor_number, prompt, model, voice → voice-playground calls LiveKit's CreateSIPParticipant with wait_until_answered=True → LiveKit SIP gateway dials Twilio → Twilio rings the destination → on pickup, the SIP participant joins the room and the agent joins too. The same call returns an observer LiveKit token the browser uses to listen in + render the WhatsApp-style live transcript.
3. Per-turn pipeline (preemptive). Deepgram emits interim transcripts → LLM starts generating BEFORE end-of-turn confirmation (saves ~300–600 ms first-token) → tokens stream into the TTS plugin → audio frames flow to LiveKit and out to the caller. The ML turn detector decides when the user really IS done, instead of relying on pure VAD silence.
4. Tools at runtime. The LLM may call kb_search (embed via Ollama nomic-embed-text → cosine search over voice_pg.kb_chunks), caller_memory (Qdrant voice_calls filtered by caller_number), web_search (Brave Search via mcp-web-search), lookup_caller (mcp-postgres), transfer_to_supervisor (CreateSIPParticipant for the supervisor number, with hold music + 3-attempt retry), schedule_callback (INSERT into voice_pg.callbacks with scheduled_for, validated against the 48-hour window), or hang_up (DeleteRoom).
5. End-of-call writes. Agent finalises the calls row in voice_pg (outcome, duration, summary), pushes the summary vector into Qdrant for future-caller lookup, and enqueues an Airtable write in voice_pg.airtable_outbox. The outbox worker drains pending rows to Airtable every 8 s — Airtable outage no longer drops calls.
6. Auto-dialed callbacks. The scheduled-callback worker polls voice_pg.callbacks every 30 s with a 60 s look-ahead. Due rows trigger another CreateSIPParticipant → LiveKit → Twilio → PSTN. Failed dials push scheduled_for back 5 minutes. The UI's Pending callbacks card surfaces each row with scheduled time + buttons to ✕ Cancel or ✓ Mark done.

Architecture

Browser
  │  (master-login JWT via auth_gate)
  ▼
voice-playground  (FastAPI, this service)
  ├── GET /          static index.html + livekit-client SDK
  └── POST /api/token  mints a short-lived LiveKit access token
                       (api_secret stays server-side)
  │
  ▼  (browser uses the token to join)
LiveKit Cloud (Germany 2 region)
  │
  ▼  (Dispatch Rule SDR_xxts7WxxddQj — same one used for PSTN)
livekit-agent  →  Silero VAD → Deepgram STT → Claude → ElevenLabs TTS

UI features

• Big call button — tap to start, tap again to hang up. Visual pulsing while connected.
• Status pill color-coded for idle / connecting / connected / agent-present / error.
• Dual VU meters — your mic level (Web Audio API analyser on the local track) + the agent's voice level (MediaElementSource analyser on the playback element).
• Conversation log — system events + transcripts if the agent publishes them via LiveKit's data channel.
• Info chips — room name, your identity, agent identity, live call duration.
• Advanced (collapsed) — custom room/identity overrides for testing scenarios where you need to re-join a specific session.

vs the PSTN path

livekit-agent — Adrian, the voice agent

NOT a browser-visible service. Python worker that registers with LiveKit Cloud and waits for dispatched calls. Source: ~/pocketcode-project/services/livekit-agent/.

Persona

The agent is Adrian, a representative from Pocket Code dot IN. Greets every call with "Hi, this is Adrian, a representative from Pocket Code dot IN, and this is a test call. How are you doing today?" Never reveals it's an AI. Configurable via AGENT_NAME / AGENT_ROLE / AGENT_GREETING env vars. Listens for the caller calling it by name ("Adrian") as an attention signal.

Persona name + gender pronouns follow the selected voice. Pick Orpheus (male) → agent introduces as Orpheus, refers to itself with he/him; Stella (female) → Stella, she/her; neutral → they/them. Wired by the voice-playground server from each voice's catalog entry into the room metadata, then injected as a "Self-reference" block into the system prompt at call time. The chosen agent_gender is also persisted on voice_pg.calls.agent_gender for analytics.

Supervisor number is optional. With one set, transfer_to_supervisor() dials with hold music + 3-attempt retry. Without one, it apologizes, promises a 24-hour callback (logged in voice_pg.callbacks with scheduled_for = now() + 24h), and hangs up cleanly.

Pipeline

Twilio DID (+1 534-231-0196)
   │  SIP trunk
   ▼
LiveKit Cloud SIP gateway
   │  WebRTC room (one per call)
   ▼
livekit-agent container
   ├── VAD     : Silero (in-process ONNX, tuned for phone audio)
   ├── STT     : Deepgram Nova-3 (streaming, en, endpointing=200ms)
   ├── LLM     : Anthropic Claude Haiku 4.5 (streaming; Sonnet via env override)
   ├── TTS     : Deepgram Aura aura-2-orpheus-en (young male, English)
   │             — OR ElevenLabs with a cloned voice id (USE_ELEVENLABS_TTS=1)
   └── Tools   : mcp-postgres.query (caller lookup)
                 mcp-web-search.web_search (mid-call queries)
                 hang_up (LLM calls when caller says bye → deletes room)
                 mcp-airtable.create_record (end-of-call → call_logs table)

Latency knobs (all streamable end-to-end):
   min_endpointing_delay=0.4s, max_endpointing_delay=2.0s, allow_interruptions=True
   barge-in: caller talking over Adrian instantly cuts his TTS

Tools available to Claude during the call (14 function tools)

As of Phase 5.7q the agent exposes 14 function tools. The LLM calls them as needed mid-conversation; results stream back into the next turn.

End-of-call logging (Airtable call_logs)

On any disconnect, the agent writes one row. The write is wrapped in try/except so call teardown cannot crash on an Airtable failure.

• caller_number — E.164 phone (e.g. +15551234567)
• created_at — UTC ISO timestamp of call start
• duration_seconds — seconds between connect and disconnect
• transcript — full STT transcript (capped at 8000 chars)

Cost protection

CALL_MAX_DURATION_SEC (default 600 s) starts a watchdog at call connect. If the call runs past the limit (stuck conversation, looping LLM, dead audio), the watchdog forcibly deletes the room. Set to 0 to disable.

What's needed before a real call works

The agent registers as a LiveKit worker on startup. Both PSTN directions are configured via API (no dashboard clicking) — see the project CHANGELOG for the exact recipes. High-level:

1. Twilio — buy a DID, create an Elastic SIP Trunk, add an Origination URL pointing at the LiveKit SIP gateway, associate the DID. For outbound, set a Termination Domain + attach a Credential List for SIP digest auth.
2. LiveKit Cloud — create an Inbound Trunk + a Dispatch Rule (auto-creates rooms with prefix call-). For outbound, create an Outbound Trunk pointing at the Twilio termination domain with those creds.
3. Airtable — create a base + call_logs table with the four fields above. Mint a PAT with data.records:read, data.records:write, schema.bases:read. Store the base ID under secrets.json → airtable.base_call_logs.

Testing without a real phone

Open voice.pocketcode.in. Click the 📞 button to talk to Adrian directly from the browser (LiveKit mints a publisher token, browser publishes mic, agent auto-joins). Or use the dial-out card to call any phone — the browser joins the same room as an observer so you can listen + watch live transcripts.

Logs from the running worker

docker logs livekit-agent --tail 30 -f

mcp-voice — outbound PSTN calling

URL: https://mcp-voice.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-voice/
Auth: Authorization: Bearer ${MCP_BEARER_TOKEN}

Thin MCP wrapper over LiveKit's CreateSIPParticipant Twirp API. Lets any agent (or the dial-out card on voice-playground) place outbound calls to a real phone number. The voice agent worker auto-joins the room and talks to the callee.

Tools

How outbound is wired (one-time API setup)

• Twilio Elastic SIP Trunk has a termination domain (e.g. pocketcode-livekit.pstn.twilio.com) and a Credential List with a generated SIP digest user/password.
• LiveKit Outbound Trunk ST_xxxxxxxx points at that termination domain with those creds; allowed caller-ID is the Twilio DID we own.
• dial_phone uses wait_until_answered=True — the agent only joins the room once the callee picks up, so the greeting doesn't play into ringing dead air.

Example dial from curl

TOKEN=$(jq -r .mcp.bearer_token ~/pocketcode-project/secrets/secrets.json)
# (initialize + notifications/initialized first — see services/mcp-voice/README.md)
curl -sk -X POST https://mcp-voice.pocketcode.in/mcp \
  -H "Authorization: Bearer $TOKEN" -H "Mcp-Session-Id: $SID" \
  -H "Accept: application/json, text/event-stream" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"dial_phone","arguments":{"to_number":"+15551234567","prompt":"Confirm Tuesday 3pm dentist."}}}'

mcp-voice-history — read-only call history MCP (8th)

URL: https://mcp-voice-history.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-voice-history/
Auth: Authorization: Bearer ${MCP_BEARER_TOKEN}

Read-only HTTP MCP over the voice agent's operational store on the existing sim-db-1 Postgres (database voice_pg). Every call writes through here, so this MCP is the canonical entry point for any "show me what happened" question from any AI client.

Tools

Operational data plane (voice_pg + Qdrant)

The agent and the voice-playground share a Postgres database voice_pg with 8 tables — callers, calls, turns, tool_invocations, events, callbacks, airtable_outbox, kb_chunks (pgvector). Plus a Qdrant collection voice_calls for cross-call memory. None of this is a new container — it's all on the existing sim-db-1 and Qdrant instances.

• pgvector KB RAG. The product KB markdown is chunked + embedded (Ollama nomic-embed-text, 768 dims) into kb_chunks. Agent's kb_search tool retrieves only the top-4 relevant chunks per question — full KB doesn't ride in the prompt.
• Qdrant cross-call memory. End-of-call summary is embedded + upserted with caller_number as filterable payload. Agent's caller_memory tool surfaces past calls for returning callers.
• Airtable outbox. Agent writes to airtable_outbox synchronously; the voice-playground background worker (_outbox_loop, 8 s) drains it to Airtable's Call Logs table. Airtable outage no longer drops calls.
• Pending callbacks. When a supervisor transfer fails after 3 attempts, a row lands in callbacks. Surfaces in voice.pocketcode.in's "⏰ Pending callbacks" card with a 📲 Dial-back button.

mcp-gmail — Gmail send / draft / read / search / labels (Phase 4, 9th MCP)

URL: https://mcp-gmail.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-gmail/
Auth: Authorization: Bearer ${MCP_BEARER_TOKEN}

HTTP+Bearer MCP wrapping Google's Gmail API. Five tools so your AI helpers — and the voice agent's send_followup_email tool — can write emails on your behalf. Single Google Cloud Console OAuth Desktop client covers both Gmail and Calendar APIs; the refresh token lives at secrets.json.services.google.oauth_refresh_token (single source of truth after the Phase 6b consolidation).

Tools

mcp-gcal — Calendar availability + Meet booking (Phase 4, 10th MCP)

URL: https://mcp-gcal.pocketcode.in/mcp
Source: ~/pocketcode-project/services/mcp-gcal/
Auth: Authorization: Bearer ${MCP_BEARER_TOKEN}

HTTP+Bearer MCP wrapping Google's Calendar API. Seven tools for availability checks, slot finding, and event creation with auto-generated Google Meet links. Shares the OAuth refresh token with mcp-gmail — one Desktop client covers both APIs. The voice agent's find_demo_slots + book_demo tools call this MCP.

Tools

mcp-hostinger — manage the VPS / DNS / domains / billing (11th MCP)

URL: https://mcp-hostinger.pocketcode.in/  (note: the MCP endpoint is the root path /, NOT /mcp like every other server)
Source: ~/pocketcode-project/services/mcp-hostinger/
Auth: Authorization: Bearer ${MCP_BEARER_TOKEN}

Wraps Hostinger's official API MCP (hostinger-api-mcp) — 118 tools spanning the whole Hostinger control panel: VPS lifecycle, DNS zones, domain registration/transfer, billing, shared hosting, and email. Lets your AI helpers inspect and operate the very VPS this stack runs on. Bearer-gated through Caddy like the other MCPs.

Tool surface (118 tools, by area)

code-server — browser VS Code

URL: https://code.pocketcode.in
Source (unit): ~/pocketcode-project/operations/host/systemd/code-server.service
Runs as: host systemd service — NOT a container. Same posture as ttyd.

Browser-accessible VS Code IDE — the same thing your Mac VS Code is, but running on the VPS. Lets you edit any file in ~/pocketcode-project/, control Docker, and run claude from the integrated terminal — all without a separate Mac install. Auth is via Caddy auth_gate (the master login cookie); code-server itself runs --auth none so there's no double-login.

What's pre-wired

• Workspace: /root/pocketcode-project opens by default.
• claude on PATH: symlinked at /usr/local/bin/claude, also on $PATH via ~/.bashrc.
• Env: systemd unit sources secrets/secrets.env, so ANTHROPIC_API_KEY, OPENROUTER_API_KEY, and MCP_BEARER_TOKEN are present for the integrated terminal + Claude Code IDE extension.
• Docker control: the integrated terminal can run docker ps, docker exec ..., ai-doctor, etc. natively (no socket mount needed — it's the host).

Claude IDE extension

Install once via the IDE's Extensions panel (Ctrl+Shift+X) — search "Claude Code", install anthropic.claude-code. It reads your ANTHROPIC_API_KEY from the env or you can use the Pro/Max account OAuth flow. Open VSX rate-limits aggressively, so we don't auto-install at boot; manual install through the UI handles retries naturally.

Network posture

• Binds 0.0.0.0:8773 on the host.
• UFW: ALLOW 127.0.0.1 + 172.17.0.0/16 + 172.18.0.0/16; DENY anywhere else. Same model as ttyd.
• Caddy proxies code.pocketcode.in → host.docker.internal:8773. Service-wrapper iframe shell on top-level navigation; deep paths (WebSockets, assets) fall through to the upstream.

Restart it

systemctl restart code-server
systemctl status code-server --no-pager | head -5