11. Glossary, Configuration & Build

A reference appendix: the full glossary, the build system, and the server/CLI configuration.

11.1 Full glossary

11.2 Build system (root Makefile)

graph TD
    deps["make deps
(tidy shared → cli → server)"] --> build
    build["make build"] --> buildcli["make build-cli
GOWORK=off → rysh-cli/ry"]
    build --> buildsrv["make build-server
→ rysh-server/bin/rysh-server"]
    buildcli --> install["make install → ~/.local/bin/ry"]
    build --> release["make release VERSION_TAG=x.y.z
tags shared → cli → server"]
    release --> snapshot["make release-snapshot
(goreleaser, CLI cross-platform)"]

Why GOWORK=off for the CLI? rysh-cli and rysh-server have conflicting charmbracelet dependency versions, so the CLI is kept out of the unified go.work module graph and built in isolation. The committed go.work includes only rysh-proto, rysh-server, and rysh-shared, with replace directives pointing the two rysh-ai/* modules (rysh-shared, rysh-proto) at their local paths.

Caveat — make workspace drifts from the committed go.work. The workspace Makefile target runs go work init ./rysh-cli ./rysh-server ./rysh-shared, which would include rysh-cli and omit rysh-proto — the opposite of the committed go.work. Do not regenerate go.work from that target; treat the committed file as authoritative.

Chrome extension build

Vite (vite.config.ts) builds popup.html → a React bundle in dist/assets/[name].js (stable names so the manifest needs no edits), then a copyExtensionFiles plugin copies the static service worker, auth page, manifest, and icons into dist/. Tailwind + PostCSS for styling.

11.3 Server configuration (rysh-server)

TOML file (path via RYSH_SERVER_CONFIG, default server.config) with environment overrides that always win.

Environment overrides (selected)

RYSH_SERVER_CONFIG          path to the TOML config
RYSH_SERVER_HOST/PORT
RYSH_DB_HOST/PORT/USER/PASSWORD/NAME
RYSH_JWT_SECRET
RYSH_NATS_HOST/PORT/WS_PORT/DATA_DIR/MAX_PAYLOAD
RYSH_LOG_LEVEL
RYSH_STRIPE_SECRET_KEY / _PUBLISHABLE_KEY / _WEBHOOK_SECRET / _SUCCESS_URL / _CANCEL_URL
RYSH_SHARES_WORKSPACE
RYSH_AGENT_API_KEY / _MODEL / _BRAVE_API_KEY / _MAX_TOKENS / _SYSTEM_PROMPT
RYSH_WHATSAPP_*                       (phone, token, app secret, verify token, api version, ...)
RYSH_CHATBOT_ENABLED / _DEFAULT_MODEL / _DEFAULT_MAX_TOKENS / _SESSION_TIMEOUT / _MAX_MESSAGE_LENGTH / _WIDGET_PATH / _CDN_URL
RYSH_ENCRYPTION_KEY

Feature flags (conditional subsystems)

11.4 CLI configuration & runtime

• Session prefix — set per session via SetSessionPrefix so multiple daemons coexist.
• Workspace config — each workspace has its own upstream endpoint and API key (drives sharing/credentials/limits via rysh-server REST).
• Logging — disabled by default; debug tees to /tmp/rysh/logs/rysh-<session>-<ts>.log. RYSH_LOG_MESSAGES=true enables the actor-comms message log (.rysh/actor-comms.log).
• Provider keys — Anthropic API key enables the real agentic provider; Brave key enables web_search; Deepgram/OpenAI keys enable voice transcription.
• Working-dir artifacts — .rysh/ (state), .rysh-notes.md (project_notes tool), RYSH.md (durable project memory written by the memory_edit tool, capped at 64 KB and auto-loaded into the system prompt each session), .rysh/pipelines/*.rysh.yaml (rysh_build_pipeline), declarative .rysh/agents/<name>/SKILL.md / .rysh/humanoids/<name>/SKILL.md skill files (project-local ./.rysh preferred, else $HOME/.rysh), .rysh/mcp.json (external MCP servers, consumed by ##mcp), and .rysh/forge/ (Rysh Forge integrations.json index + per-integration specs and generated artifacts).
• Agent prompts — all agentic prompts live as markdown under rysh-cli/rysh-cli-agent-prompts/ and are embedded into the binary at build time (//go:embed, prompts.go) — editing one and rebuilding changes the prompt; they are not runtime files. Empty/missing files fall back to in-package constants in internal/agentic/prompts.go.

11.5 Deployment shape

graph TB
    subgraph dev["Developer machine"]
        CLI["rysh daemon + TUI"]
        Chrome["Chrome + extension"]
    end
    subgraph cloud["Cloud"]
        Server["rysh-server binary"]
        PG[("PostgreSQL")]
        Stripe["Stripe"]
        FB["Firebase"]
        Server --- PG
        Server -. webhook .- Stripe
        Server -. verify .- FB
    end
    Site["Customer website
(embedded widget.js)"]
    Anthropic["Anthropic API"]

    CLI <-->|"NATS over WS
(ws.{id}.*, ACL-confined)"| Server
    Chrome <-->|"NATS over WS"| Server
    Site <-->|"chatbot widget proto"| Server
    CLI --> Anthropic
    Server --> Anthropic

The server is a single self-contained binary (embeds NATS + serves the React dashboard from web/dist + serves widget.js); it needs only PostgreSQL and, optionally, Stripe/Firebase/Anthropic credentials. The CLI runs locally and connects to the server for collaboration, channel credentials, and limits. The extension and the website widget connect to the server's NATS WebSocket proxies.

11.6 Cross-references

• Protocol details → 3. Messaging & Protocol
• The agent loop → 4. Agentic Engine
• Per-component internals → 5–9
• How it all flows → 10. End-to-End Flows