← JayCorp

Handoff README

For AI systems (and people) picking up work on JayCorp's AI server: how the machine is set up, what runs on it, and how to add or change sites and pages. Facts were checked on the machine on 2026-10-09. No secret values appear here, and none ever should.

1. Read these first

• AGENTS.md: the working rules for every coding agent. Short version: ask before guessing, write the least code, touch only what the task needs, prove it works, Ruby first, everything self-hosted and behind adapters, register every service for observability, secrets only through the adapter, twelve-factor apps.
• CLAUDE.md at the project root: imports AGENTS.md and adds the repo layout and site rules below.
• AGENTS.md is published live at www.ruby.im/AGENTS.md (a symlink into that site), so editing it changes a public page and needs a ruby.im changelog entry.

2. The machine

Installed tools

Not installed today: Node, Docker, Bitwarden bws. AGENTS.md section 11 wants at least two swappable AI providers, so app code that calls Codex or Kimi goes behind an adapter.

3. Repository layout

/home/jayai/Projects/jayai
├── AGENTS.md, CLAUDE.md   rules for agents
├── static_www/            static sites, one folder per domain (this page lives here)
├── apps/live/             the one dynamic app so far
├── observability/         OpenTelemetry + Grafana stack and the service registry
└── secrets/               the secrets adapter

4. Static sites: static_www

• static_www/config.ru: a Rack app run by Puma on 0.0.0.0:8080 (unit static-www). It picks the folder sites/<Host header>/, falling back between www. and bare names, then to sites/_default/. Dotfiles are never served, directory listings are off, .md files show as plain text.
• Caching: every file has an ETag and Last-Modified with Cache-Control: no-cache, so edits show on the next load without any cache busting.
• Network footer: lib/network_footer.rb appends a "More sites" line to every HTML page at serve time, built from the sites/ folders. Pages don't include it themselves. Below it goes a one-line privacy note and the visit script /_jayai/v.js.
• Visitor and scan logging: lib/access_log.rb writes one JSON line per outside request (with probe paths and scanner tools named by lib/scan_probe.rb), and lib/visitor_beacon.rb serves the visit script and logs its browser report at POST /_jayai/v. Both go to journald and Loki. X-Forwarded-For is trusted only from 127.0.0.1 and the edge (10.88.0.1). Visits through the edge have no country yet; ngrok used to add it. See Visitor and scan logging.
• The edge (edge/Caddyfile, installed as /etc/caddy/Caddyfile on the droplet) sends every request to port 8080 over the tunnel. Certificates come from Let's Encrypt on demand, but only for names under the domains in its allow-list.
• Paths that go to an app are routes in the Caddyfile: michigan.im /radio* to radio (8100) and /jellyfin* to Jellyfin (8096); www.ruby.im /grafana* and /live*, and bada.im (opencode, all but its top-level articles) behind the Authelia passkey sign-in at auth.ruby.im and auth.bada.im.
• The ngrok files (run_ngrok.sh, .ngrok-policy.yml, extra-endpoints.yml, edge-rules.yml) are still here but unused.

Live sites

5. Apps: apps/live

Phone monitoring with local AI, at www.ruby.im/live (access token required). A phone streams camera and mic over a WebSocket to a Falcon server on 10.88.0.2:8090 (unit live); ffmpeg splits the stream into clips and frames, and scripts in analyzers/ transcribe audio with whisper.cpp (unit whisper, port 8178) and describe frames with Ollama (unit ollama, port 11434). Sessions are saved under apps/live/sessions/, and bin/summarize writes an AI summary per session through lib/llm.rb (LIVE_LLM=ollama by default, anthropic as the second provider). Details: apps/live/README.md.

New apps go in apps/<name>/ with their own Gemfile, README and user systemd unit, bound to 127.0.0.1 on a port from config. To publish one, bind it to 10.88.0.2 and add a route in edge/Caddyfile.

6. Observability

OpenTelemetry into a local Grafana stack, all on 127.0.0.1 (observability/README.md):

apps, agents ─OTLP :4317/:4318─▶ otelcol ─▶ Prometheus :9090  (metrics, 30 days)
host + GPU metrics, journald ──▶         ─▶ Loki :3100        (logs, 30 days)
health checks ─────────────────▶         ─▶ Tempo :3200       (traces, 7 days)
                                Grafana :3000 reads all three

• observability/services.yml is the registry of every host and service (name, unit, health URL, otel, source, host). Add an entry in the same change that adds a service or site, then systemctl --user restart otelcol.
• Ruby apps use opentelemetry-sdk, opentelemetry-exporter-otlp and opentelemetry-instrumentation-rack, with OTEL_SERVICE_NAME set in the unit (see static_www/config.ru).
• observability/bin/check is the end-to-end smoke test.
• Grafana: http://10.88.0.2:3000/grafana/, dashboards "JayAI overview" and "Site visitors and scans". From elsewhere, www.ruby.im/grafana behind the passkey sign-in.

7. Secrets

• Read secrets only through secrets/lib/secrets.rb (Secrets.fetch("NAME")) or secrets/bin/secret get NAME. secrets/bin/secret names lists names, never values.
• Default provider: the project's own .env (mode 600, git-ignored). Bitwarden Secrets Manager is the second provider, picked with JAYAI_SECRETS=bitwarden.
• Commit a .env.example with names and empty values. Never print, log, commit or paste a secret, and never type a person's password or token yourself; ask them to put it in .env.
• Some secrets predate the adapter (the ngrok authtoken in ~/.config/ngrok/ngrok.yml, the live app's .token); see secrets/README.md.

8. How to add or update a page

1. Edit or create the HTML file in static_www/sites/<domain>/. Plain HTML with inline CSS, matching the site's existing pages (copy the <style> block, light and dark colors, from the home page). No build step.
2. Link a new page from the site's home page (or the relevant section). Don't add a "More sites" footer; the server adds it.
3. Add a changelog entry in the same change, one plain sentence:

   static_www/bin/changelog <domain> "What changed"

   It inserts a dated line at the top of sites/<domain>/changelog.html, creating the page if needed. Every www.ruby.im change needs one; every other site keeps one too.
4. Nothing to restart: the file is live as soon as it's saved. Check it:

   curl -sI https://<domain>/<page>.html

9. How to add a new site

1. Point the domain's @ and * A records at 174.138.65.239 (Name.com; edge/bin/dns add <domain> '*' with the token from ~/.config/environment.d/namecom.conf). For a new domain, also add it to the allow-list in edge/Caddyfile and copy that to the droplet.
2. Create static_www/sites/<domain>/index.html. It's live as soon as DNS resolves; Caddy gets the certificate on the first visit. Use the www. name for the folder if that's the canonical host.
3. Start its changelog: static_www/bin/changelog <domain> "Launched the first version of <domain>.", and link /changelog.html from its footer.
4. Register it in observability/services.yml (unit static-www.service, health https://<domain>/), then restart otelcol.
5. Confirm: curl -sI https://<domain>/ returns 200 with a valid certificate.

10. Useful commands

systemctl --user status static-www live whisper ollama
systemctl --user status otelcol prometheus loki tempo grafana gpu-metrics
ssh edge 'systemctl status caddy authelia wg-quick@wg0'
ssh edge 'journalctl -u caddy -f'
scp edge/Caddyfile edge:/etc/caddy/ && ssh edge 'caddy validate --config /etc/caddy/Caddyfile && systemctl reload caddy'
observability/bin/check
ruby static_www/test/network_footer_test.rb

Provided as is, for information only, with no warranty and no liability. Not legal or professional advice. Security and radio material is for authorized, lawful use only. Full disclaimer.

Visits are logged on our own server: IP address, browser and device details, and pages viewed. We use them to understand traffic and spot attacks, and never share or sell them.