Safe, secure and cost-effective.
Connect your live data streams; Lens turns them into a cited knowledge graph your agent can reason over, through MCP, a REST API or its own assistant. It runs on your hardware with local models or any cloud model, private by default and cost-aware.
curl -fsSL https://raw.githubusercontent.com/adeelahmad/lense/main/install.sh | shThat one line is all: it opens an installer in your browser that checks the computer, then either installs with the
defaults in one click (with a model server it finds on the computer) or asks how Lens should run (in Docker or a
microsandbox microVM), the AI model and its key and any extras. Either way it installs what's
missing (Docker included), starts Lens and opens its setup page (details).
Run it again to update. On Windows, run irm https://raw.githubusercontent.com/adeelahmad/lense/main/install.ps1 | iex
in PowerShell; or skip the terminal and double-click the launcher for your system from the
latest release. On a Mac with Apple silicon,
Lens.app from the same release installs Lens, runs it without Docker and keeps it in
the menu bar (built, early: not signed yet).
Deployment covers servers and Cloudron; there are also packages for
Synology, QNAP and Proxmox.
The checks say which of these CI proves.
To work on the code instead, make run builds and runs everything from a checkout, make setup-code prints the
first-admin setup code, and make dev runs it with hot reload; see Get started.
AI doesn't lack intelligence. It lacks structure. Lens gives your agent eyes. Without structure, every prompt is a guess about who you are and what happened. Lens supplies the people and things involved, how they relate, what happened when, and the source of each fact, so your agent stops guessing.
Lens is one private AI hub for your whole li 8000 fe. Every source is a sensor: recordings, documents, email, calendars, web pages, chat rooms, devices and webhooks all flow in, and everything becomes memory you can trust, because every answer cites where it came from, down to the second of a recording or the line of a document. It runs on your own hardware, from a Raspberry Pi to the cloud, and you own every byte.
Lens is built first for agents and AI assistants. People talk to their agent in chat, by voice, or in Slack, WhatsApp and other chat rooms; the web app is for setup, settings, pipelines and workflows, review, debugging and the charts that show what is in the archive and what it cost.
Lens is also infrastructure to build on. An app built on Lens, such as an email responder or a customer manager, starts with real, structured context (who is involved, what was said, what was decided, with sources) instead of a blank prompt. Apps reach it the same way agents do: through the MCP server, the REST API and OAuth sign-in, limited to what their person may read.
Everything below is built and merged, and each item links to the checks that prove it: tests, clicks journeys and measured numbers (requirements and their checks). Work that is still in a pull request is listed under In progress, and what comes next under Planned.
- Connect your agents. Lens is an MCP server (
/mcp): agents search, find assets by face, voice, entity, topic, type, content type or date in one call, find what was said about a day, classify an asset or a text with the decision model, read assets' text and notes, cite exact moments, find similar content, explore the graph with Cypher or SPARQL or browse it as folders and files, suggest topics and graph changes, edit and merge entities and topics (with undo), write notes and make podcasts. They sign in with OAuth and see only what their person may read; the account menu copies the MCP address in one click. A namespace can also have an MCP server of its own (/mcp/<namespace>) and answer OpenAI's chat completions API for any app, cited from that namespace alone, each off until its owner turns it on, with API keys that open that one namespace and nothing else. The same folders and files can be mounted over S3, WebDAV, NFS or SMB (S3 and WebDAV also at the web app's address, through remote access), so file managers and scripts read Lens too, and a file copied in over S3 or WebDAV is imported where it was put. The web app runs on the same REST API, so an agent can do what a person can. (MCP, one namespace's MCP server, chat completions, API, the graph as files, authentication; checks) - Ask, and get cited answers. A chat assistant on every page, and by voice, searches your archive by words (and by
meaning, once turned on), reads it, cites it and acts on it with tools: changes wait for your approval. Once an admin
turns them on, it also searches the web and reads pages, cited like the archive, and runs Python and bash in a sandbox
of each conversation's own. Regenerating an answer or editing a question makes a new version beside the old one, and
nothing is lost. Each answer keeps a record of what produced it (the model, its tools, how long it took and what it
cost), opened from its header. It reads answers aloud with a speech provider, macOS
sayor StyleTTS2 on this machine (opt-in), and/clearand/compactkeep long conversations short. Each namespace can have its own assistant with its own name, instructions and memory, answering in Telegram and Slack (built in, with voice notes and files), in Discord, Matrix, WhatsApp and other chat rooms through Matterbridge, and by email at an address of its own that you email or forward things to. (Chat, web search, code sandbox, answer records, chat rooms, email, speech providers; checks) - Extend the assistant. Add tools (a prompt, a web request, a graph drawn on the canvas, or sandboxed Python),
skills, hooks and MCP servers, by code, on the canvas or just by asking. Remote MCP servers connect by address, and
ones that run as a program (
npx,uvx) run in a sandboxed container of their own, off until you turn it on. Add one with a form or by pasting another app's config, its tokens sealed and each of its tools switched on or off. Install skills and plugins from marketplaces in the open plugin format, or from a repository or an archive. (Extending the assistant, adding an MCP server, the MCP runner; checks) - Bring in everything. Watched folders on S3, Dropbox, Google Drive, OneDrive, SFTP, SMB, WebDAV or local disks (a local folder in four clicks); IMAP mail, Gmail and Google Workspace, iCal calendars and Google Calendar; a built-in MQTT broker, syslog and webhook streams; import webhooks for scanners and phone shortcuts. Google accounts connect with Connect with Google once Lens has a Google client, and Dropbox, OneDrive and Google Drive can sign in through rclone on the Lens server, with no app of your own to register. Upload audio, video, PDFs, Office files, photos, JSON and zip or tar archives, and, with an Apache Tika server (an opt-in extra), documents nothing else here can read; capture web pages one at a time, from a link list or a bookmarks file, by API or by asking the assistant, from private networks you allow in Settings too; and import videos and podcasts by their address (off by default). (Sensors, processing, Apache Tika, import webhooks; checks)
- Clip from the browser. The Lens web clipper for Chrome, Edge, Firefox and Safari turns a page, a selection or a part you pick into Markdown, lets you look it over, and sends it to a namespace. New releases reach installed copies through the browser's store or a self-hosted update file. In Chrome and Edge, its side panel is a chat with the assistant, which can also use that browser on the sites you allow (open, read, click, type), asking before anything that sends, deletes, buys or posts. (Web clipper, the assistant in your browser; checks)
- Understand it. Transcription, people recognised by voice (long recordings go to a speech provider in pieces that
fit its limits), text on screen and in scans, faces (off by default), NSFW pictures flagged by a model on your own
server (off by default, per namespace), entities and topics in a knowledge graph you can explore, query with Cypher or
SPARQL, and see as it was at any version. Every entity has its own page at a wiki address
(
/wiki/<namespace>/<Name>), and entities, topics and people are edited and merged from their lists, the graph or an asset, with Undo instead of a confirm. Names get their real types (people, places, organisations, events, works) by rules, without a model. Find what is most like a passage, an asset, a topic or an entity, in a Similar tab on every asset or by selecting text anywhere, and, with anytopdf, photos by what they show. Pages and shots are described in words by the model provider's vision model or, off by default, by Florence-2 on your own server. Transcripts can be cleaned up before analysis (stutters, "um"s, spacing and, with a local model, punctuation put back), entities found by spaCy instead of the rules, and the dates people say read as days on the calendar, each off by default. (Graph, entity pages, similar content, graph history, topics, video, NSFW classification, long recordings, cleaning up transcripts, dates; checks) - Learn from it. Make a two-host podcast episode about what you pick, every claim cited and checked against its source, read aloud in two voices. Keep notes beside every asset, entity and topic, written by you or the assistant, in a tree where notes are renamed, moved, copied and pinned (pins are your own) and each note shows the notes it's inside and the ones inside it, with today's note one click away, templates to start from, a search by their words, a download as Markdown, and Undo and Recently deleted instead of a confirm. Export an asset or a collection as an evidence PDF with everything Lens found about it, or the parts you pick. (Podcasts, notes, evidence PDFs; checks)
- Automate it. Pipelines and workflows on a canvas, routines on a schedule, batch runs over a collection, and notifications to webhooks, Slack, Discord and Matterbridge. Everything that happens in Lens (new assets, emails, calendar events, files, what people say to Lens, sensor readings, notes, graph changes, runs, budget warnings) is kept as a stream of activities in W3C Activity Streams form, which agents read through the API, MCP and the assistant, and people review on the Timeline page (and Latest on Home), marking what they've seen. Automations act on that stream, on a schedule, at a time or when their own webhook is called: they test conditions, then tell you in your own chat app, ask the model or the agent, use a tool, call a web address (its credentials kept sealed), run a workflow, pipeline or routine, or change assets and notes. A Classify node in a workflow sorts an asset into labels, content types or topics, acting only on a sure answer. Anything that reaches outside Lens or changes more than what set it off asks first, until you let it run on its own: on the Approvals page or, for a change inside Lens, with a yes in the chat it told you in; agents can decline an approval but never give one. Each automation has limits and budgets, and agents make, try and run them over MCP and in the assistant, or draft one from a sentence; the studio to draw them in the web app is planned. (Processing, notifications, automations, approvals, timeline; checks)
- See what it costs. An activity ledger of every model call, with reports, charts and budgets that cap spending. Setup asks for one overall budget after a cloud model, with a soft limit that warns and a hard limit that stops paid calls. A meter in the top bar shows spend against the budget, and the Costs page breaks it down by day, model and what cost most. Routine choices go to small decision models, and the LLM only when it adds value. (Activity and costs, budgets, the meter; checks)
- Keep it up to date and backed up. Lens checks for a new release once a day and tells admins by email or a notification. One click in Settings › Updates (or one API call) upgrades it through a small agent on the machine, showing each step, and rolls back when the new version doesn't start; nothing installs unless an admin says so. The same agent changes whether other devices reach Lens and which edition runs, from Settings. Settings › Backups takes, lists, downloads and restores backups of the database and Lens's files (a file that hasn't changed takes no new room), takes them on any schedule, and can copy each one, encrypted, to a storage connection. Before a version is released, CI upgrades the one before it, holding data, to it, and releases nothing when any of that data is lost. (Updates and backups, backups, the upgrade check; checks)
- Watch it run. Structured logs from every process, read in Settings › Logs and optionally sent to a syslog
server. OpenTelemetry traces and metrics, and a Prometheus
/metricsendpoint, both off until you turn them on, and sending nothing anywhere else. On a Docker install, one switch in the web app (or one API call from an agent) starts Prometheus, node-exporter and Grafana next to Lens, already connected, with the Lens dashboard as Grafana's home. The Analytics page shows admins active people, churn, retention and which features get used, worked out on this machine; the same daily events can also go to a Google Analytics 4 property of your own (off unless you turn it on). (Logging, telemetry, Prometheus, usage analytics; checks) - Stay private and safe. Passkeys instead of passwords, encryption at rest with a key per namespace, roles per namespace (viewer, editor, owner, or custom roles made of permissions), email invitations, removing someone for good, and an audit log. Prompt injection meets several layers: what the assistant reads (recordings, documents, web pages, tool results) reaches the model marked as data, not instructions, and text that reads like instructions to an AI is flagged (by free patterns, or an optional classifier model that runs on your machine and is fetched only when you pick it). Once an answer has read such text, sending anything out, or the browser opening or typing what the assistant wrote, waits for your yes. Chat-room answers have links they built themselves broken up, agents over MCP get the archive as data, and what Lens caught goes into the audit log. Serve Lens over HTTPS, set up in Settings, with certificates from Let's Encrypt or ZeroSSL that renew on their own, answering only for its own domains and, if you choose, only to devices holding a client certificate; or reach it from anywhere through a Cloudflare tunnel with nothing opened on your router. (Encryption, access, prompt injection, HTTPS, remote access; checks)
- Use open standards. RDF and Dublin Core for every record, OAuth for apps and OpenID Connect sign-in, MCP, MQTT, IIIF for publishing, OpenTelemetry and Prometheus for monitoring, and an optional Fedora mirror. (Linked data, IIIF, Fedora; checks)
Lens runs on a small machine. Heavy parts (local speech models, a local LLM, document conversion, an Apache Tika server, the NSFW model, the MCP runner, Fedora) stay off or download only when you turn them on, and any of them can be swapped for a cloud provider instead. Setup asks only what has no default: the model, and a budget for a cloud model. Picking a cloud model provider fills in its address and a model, so only its key is left to paste. Every setting lives in the web app, which works on a phone too: settings are in named groups, a search finds any one by name, and the options most people leave as they are stay folded. (Components, speech providers, local models, cloud model providers; checks)
These are open pull requests, not yet part of Lens:
- The assistant answering questions about Lens itself, from its docs and this server (#400).
- Chat: a conversation exported as Markdown, PDF or JSON (#474).
- Sources: RSS and Atom news feeds (#453).
- Pictures: low-quality images enhanced before they're read (#479).
- Web clipper: signing in, or using your API token, not only an import webhook's (#406).
- Automations: more operators for conditions (#434).
Next, and not in a pull request yet; each links to where it is tracked:
- The automations studio: drawing automations in the web app, joins, and the decide node, where a decision model picks the branch (automations).
- Timeline: what each item caused, and Approve and Decline on waiting approvals (timeline).
- Notes: nesting a note under its project or area without a click, pages in the graph, and wiki addresses for topics, recordings and the other things that have pages (notes).
- Local models: GPU builds of llama.cpp fetched by Lens, and local embedding models (local models).
- Speech providers: their summaries, chapters and entities as optional imports, and per-minute prices in the activity ledger (speech providers).
- Storage: uploads and assets' media in the file store, and a storage key to download (storage).
- Logging: sending straight to Loki or another HTTP endpoint, and client certificates for TLS (logging).
- Proof: each release tested by upgrading an install of the last one, holding data (#482), and the scorecard's install-to-first-answer and Raspberry Pi numbers, not measured yet (#481).
fastapi_backend/ |
FastAPI API (/api/v1), MCP server, the processing engine, and the lens CLI and workers |
nextjs-frontend/ |
Next.js web app with a typed client generated from the API's OpenAPI schema |
extensions/browser/ |
the web clipper browser extension |
installer/ |
the web installer and the double-click launchers |
| SurrealDB | documents, graph edges, the job queue and graph history; word search in a small SQLite index beside it |
The guides are on the docs site and in the docs folder:
- Start: Get started, deployment, microsandbox, configuration, components, updates and backups, remote access, HTTPS
- Agents and apps: MCP server, API, authentication, access
- Use: chat and batch runs, chat rooms, the assistant by email, podcasts, notes, web clipper, the assistant in your browser, sensors, processing, video, NSFW classification, notifications, automations, timeline
- Knowledge: graph and Cypher, graph history, topics, the graph as files, NFS share, SMB share, linked data (RDF), IIIF, Fedora
- Models and cost: local models, speech providers, activity and costs, budgets
- Operate: encryption, storage, database, logging, telemetry, Prometheus, usage analytics
- Build: architecture, web app, technology, API work the design needs, contributing, agent rules
Security, threat model, changelog.
Lens is open source under the MIT License. Optional extras that you install yourself may carry their own
licenses (for example extract-msg, GPL-3.0, for Outlook .msg files); none is part of the default install.
Built on the Next.js FastAPI Template (MIT).