Documentation

SwiftLeads is an autonomous lead-intelligence platform running on a
Linux server. Agents are Node.js processes managed by the openclaw
gateway. Each agent lives in a workspace directory and is invoked
either on a cron schedule or by an inbound webhook.

The dashboard (Viktor Mission Control) is served by a Node.js/Express
backend at port 7777, proxied through Caddy on 443.

Agents calling Vertex AI (Gemini, Veo, embeddings) authenticate via
Application Default Credentials (ADC) — no API key needed in code.

1. Install the gcloud CLI on the server.

2. Authenticate:
   gcloud auth application-default login

3. Set your project:
   gcloud config set project YOUR_PROJECT_ID

4. Verify it works:
   gcloud auth application-default print-access-token

Credentials are stored at:
~/.config/gcloud/application_default_credentials.json

Any process running as the ubuntu user can now call Vertex AI.
Do NOT store the credentials file in git.

Caddy runs as the reverse proxy (ports 80/443). Add a route for
inbound webhooks in /etc/caddy/Caddyfile:

  swiftleads.yourdomain.com {
      reverse_proxy /api/* localhost:7777
      reverse_proxy /webhooks/* localhost:5001
  }

Outbound webhooks (Telegram, Slack, n8n, Make, Zapier) are
configured per-agent in the openclaw workspace .env file:

  TELEGRAM_BOT_TOKEN=your-token
  TELEGRAM_CHAT_ID=your-chat-id
  SLACK_WEBHOOK_URL=https://hooks.slack.com/...

Agents POST to these URLs directly — no intermediary needed.

Agents are triggered in two ways:

1. crontab — edit with: crontab -e

   Example (run qualifier every hour):
   0 * * * * /home/ubuntu/swift-leads/run_qualifier.sh

2. openclaw internal scheduler:
   openclaw schedule add "qualifier" --cron "0 * * * *"
   openclaw schedule list

Logs land at ~/logs/<agent-name>.log

The Telegram Notifier sends a summary to your channel after each run,
so you always know what ran without SSHing in.

Each agent reads from a .env file in its workspace directory.
Never commit .env files to git.

Common variables:
  OPENROUTER_API_KEY    LLM calls via OpenRouter
  SUPABASE_URL          Database connection
  SUPABASE_ANON_KEY     Database auth
  TELEGRAM_BOT_TOKEN    Telegram notifications
  TELEGRAM_CHAT_ID      Target channel or group

Lock down permissions:
  chmod 600 .env

Add to .gitignore:
  echo ".env" >> .gitignore

1. Create a directory:
   mkdir ~/swift-leads/agents/my-agent

2. Add an entry point (index.js or index.ts).

3. Create a .env with required keys.

4. Register with openclaw:
   openclaw skill add my-agent

5. Test manually:
   openclaw run my-agent

6. Schedule it:
   openclaw schedule add "my-agent" --cron "*/30 * * * *"

The agent will appear in the Agents page once openclaw
reports it as active.