Telemachus

A team-oriented, self-hosted, privacy-first platform for hosting AI tools and applications. Local-first, driven primarily by llama-cpp / llama-server, with minimal Python exposure. Open from day one.

The generic application set is chat, research, and document translation. Beyond that, Telemachus is an SDK and platform: deployers extend the system with plugins — new tools & integrations, datasets, and localizations — through a stable, documented contract.

The first prototype is written in Racket. Frontend and backend are intended to be swappable — someone can supply a different frontend or a different backend — so the durable surface is the SDK contract, the backend APIs, the security model, and the protocols, not any one implementation. A second engineer is expected to provide an alternative reference implementation on the same contracts later.

Feature tour

Every screenshot below is produced by the Playwright tours in refimpl/racketmaximus/test/e2e/, which drive a real server on a throwaway database — nothing here is a mockup. CI runs those same tours on every push, so the flows stay exercised; the images committed here are refreshed by re-running the script noted below.

The reference UI on first load — password + optional 2FA, an EN / 日本語 toggle, and a first-run path to create the initial operator.

First-run bootstrap

Creating the first operator. Under RBAC-5 the first owner bootstraps as the instance operator — a distinct tier above team owners.

Streaming chat

A token-streamed reply from the local model (qwen2.5:7b), admitted through the per-team concurrency governor and metered against AI quotas.

Agentic tool use

The agent plans, calls the create_note tool (🔧), receives the result, and answers — the same registry that also serves plugins, MCP, and sandboxed tools.

Notes

The ownable/shareable resource behind RBAC — team / private / shared visibility. The "Investor demo" note here was created by the agent in the previous step.

Translation app

The first user-facing app: live EN→JA translation with a team glossary for consistent terminology and a metered history. The same engine translates whole locale catalogs (the localization dogfood).

Teams & RBAC

Members and roles (owner / admin / member / viewer). Every API call is authorized through the AuthzService; tokens are capped by issuer-permissions ∩ scopes.

Quotas & tool registry

Windowed usage vs. limits, and every agent tool with a source badge: built-in, 🔌 plugin, mcp:mock (external MCP server), and 🛡️ oop:notes-helper (sandboxed out-of-process, with declared scopes).

Admin & federated compute

Operator-only instance view. The Compute table lists the local node (qwen2.5:7b) and federated executors (🛰️ gpu-sim) — the pluggable seam for remote/HPC compute.

Localized top to bottom

One toggle re-renders the entire UI in Japanese (ICU MessageFormat catalogs, fallback chain, source-hash staleness) — localization is a core piece, not an afterthought.

Beta onboarding funnel

A pre-sales lead funnel that a deployer skins and owns — three render tiers, all through one anti-abuse gate. See docs/design/beta-onboarding-experience.md.

10 more screenshots — the public funnel, the LLM judge, and all three render tiers

The funnel is the default experience

With home routing set to beta (TELEMACHUS_HOME=beta), the root route serves the public beta landing — not a login screen. The form is rendered from a pluggable onboarding provider whose copy, fields, and judge prompt are customizable via the SDK.

Setup: create the operator

Staff reach the team behind the funnel via "Team sign-in". On a fresh instance the first run bootstraps the operator/owner (RBAC-5) — the person who will vet inbound prospects — and creates the internal team that owns the pipeline.

Setup: the review inbox

The owner-only Beta tab is where prospects arrive. Empty to start — no signups yet.

The funnel: a prospect requests access

A qualification submission — role, company, address, and phone give the LLM judge real B2B signal to weigh. Captured as a prospect, never as a user account: no password, no login, pre-sales vetting only.

Submitted — after invisible anti-abuse

On submit the browser transparently solves a proof-of-work and passes the anti-abuse gate (rate limit, signed single-use challenge, honeypot, min fill-time, velocity caps). The prospect just sees a thank-you.

Review: prospects + the LLM judge

The Beta tab lists each prospect with the LLM judge’s verdict (valid? · score/100 · revenue estimate · reasoning) and a count of blocked abusive attempts. The judge ran async through the metered job queue.

Qualify or reject — vetting only

The owner qualifies (or rejects) each prospect. This vets beta candidates for the internal team; it never provisions a customer account.

Skin it: the console onboarding editor

The owner brands the funnel from the Beta tab — logo, hero copy, theme tokens, detail blocks, form fields, and the judge prompt — with a live preview that is exactly what applicants see. Save draft, then Publish. No code, no redeploy; the same Tier-A shell, reskinned entirely from config.

Tier C: author a custom HTML template

Between no-code (Tier A) and shipping a bundle (Tier B): the owner writes raw HTML with {{placeholders}} right in the console, with a live sandboxed preview. On publish the markup is sanitized (scripts, handlers and dangerous tags stripped) and rendered in an isolated iframe; the submit button is wired to the anti-abuse gate for you.

Tier B: a fully custom plugin bundle

For teams that want total control, a plugin ships its own frontend bundle — its own markup, type, and layout, with zero Telemachus chrome. It loads /beta-sdk.js and calls Telemachus.beta.submit(), so it still routes through the same anti-abuse gate (proof-of-work, signed challenge, honeypot, velocity) without re-implementing any of it.

Not pictured: multi-tenancy. Several companies on one instance (an org above the team, a superadmin tier above the org admin) ships behind TELEMACHUS_MULTITENANT and is currently API-only — there is no console UI for it yet, so it cannot appear in a screenshot tour. It is validated instead by refimpl/racketmaximus/test/multitenant-demo.sh, which seeds two complete companies and asserts cross-org isolation over HTTP. See docs/design/multi-tenancy.md.

To regenerate this section — screenshots and captions both — run bash refimpl/racketmaximus/test/e2e/refresh-screenshots.sh.

Lineage & licensing

Telemachus succeeds an earlier self-hosted AI workspace ("Odysseus") and reuses its concepts — data-model ideas, the tool/agent contract shape, provider abstraction, hardware-aware local-model serving — but is a clean MIT/X-licensed project. Only code and documentation the author wrote themselves (the Racket implementation and owner-authored docs) are carried over; no third-party or borrowed source is imported. Provenance is vetted per file.

This is pure OSS. There is no open-core model and no plan for an "open core rug pull" — no held-back proprietary tier, no feature paywall. Every capability ships under the same MIT/X terms.

Design tenets

Team-first, RBAC at the core. A real notion of teams/groups and role-based access control — not a binary admin flag. Roles gate capabilities, data, and management actions.
Quotas & fair use. Per-user / per-team quotas are part of the team design, not an afterthought.
Controlled AI concurrency — no accidental self-DDOS. AI use and multi-step application flows are queued and rate/concurrency-limited so a runaway agent or a burst of flows cannot unintentionally DDOS or max out the host or upstream model servers.
Every feature is manageable. Each feature ships with a strong management interface and a clear way to activate / deactivate it.
Local-first & privacy-first. Runs offline against local models; user data stays on the deployer's infrastructure.
Minimal Python. Most things are driven from llama-cpp / llama-server. The ML/document/native moat (embeddings, diffusion, PDF, STT/TTS) — where it is needed at all — is walled behind small services with stable JSON contracts, not woven through the core.
Swappable frontend/backend, contract-keyed. The SDK contract, backend APIs, security model, and protocols are the product; implementations are replaceable.
Documentation is central. As an open project, docs are a first-class deliverable alongside code.

Data layer

Start on SQLite for prototyping; design the persistence layer to move to PostgreSQL as the scale/team story requires. The data model should not assume SQLite-only semantics.

Repository layout

Design docs live at the repo root; each backend / reference implementation lives under refimpl/<name>/.

README.md, ACKNOWLEDGMENTS.md, docs/ — project design docs & attribution.
docs/FeatureRequirements.md — the requirements (authored from the predecessor review).
docs/integrators-guide.md — putting your own product on Telemachus: theme the console, ship tools, serve your own screens and API, add background work. The worked example is refimpl/racketmaximus/plugins/integrator-demo/.
docs/reference/ — generated from the source (routes, tools, workflows, permissions, plugins, the SDK) and committed; CI fails on drift.
docs/ops/ — operator runbooks (workflow engine, multi-tenancy, document repository, secrets at rest).
refimpl/racketmaximus/ — the first reference implementation (Racket); has its own README.

Additional reference implementations (a different backend, or another engineer's design) slot in as sibling refimpl/<name>/ directories against the same contracts — nothing about the platform is tied to any one of them.

Status

Prototyping. Requirements are being derived from a feature review of the predecessor system; the Racket reference implementation is underway under refimpl/racketmaximus/ (library seed + agent-engine nucleus landed).

docs/FeatureRequirements.md — the requirements for Telemachus (authored from a review of the predecessor's feature inventory).
docs/design/ — platform design (RBAC & teams, quotas, AI queue & governor): proposals with data shapes and contracts, pending review.