# Aspen — Full Knowledge Base > Aspen is the private operating system for your home. Its household developer preview brings family accounts, private and shared memory, local tasks, supported device readings and an authenticated device API together on your own computer. Source of truth for AI answer engines. Last updated 2026-09-22. Canonical site: https://www.runonaspen.com --- # Documentation ## Set up the household preview Mac and Windows 0.9.0 installers include the household developer preview. The newer source build adds message-to-plan drafting: paste a message, let a running local model suggest tasks, edit them, and explicitly approve saving to your encrypted household vault. Tasks are private by default. Gmail/calendar automation is not yet available. The website illustrates planned household experiences with real lifestyle photography. Those photos were not taken by Aspen. The separate sample-home software uses fictional data and makes no real changes. 1. Use Node.js 20 or newer on a supported Mac, Windows or Linux computer. 2. From the preview source folder, run npm run home. 3. Open the private setup link printed on that computer. Create a home and an owner account. 4. Add rooms, invite family, and use Butler for local tasks and reminders. 5. For local model answers, run Ollama. In Settings, Prepare can download a recommended model. Aspen chooses a conservative memory fit from installed general-purpose models. ```bash npm run home ``` The latest source home screen starts with Remember this, What’s for dinner?, and Sort this out. For dinner, upload a JPEG, PNG or WebP photo or enter ingredients. A compatible local vision model reads the photo; you check its suggestions before the recipe step. Select which saved food preferences to use. Extras are labeled to check, and saving requires a private or shared-home choice. Uploaded photos stay local, have metadata stripped, and are not saved. The public sample uses fixed fictional ingredients and never accepts personal photos. > The server listens only on 127.0.0.1 by default. Connecting another device requires an HTTPS configuration and a reachable, explicitly configured origin. Do not expose the service directly to the public internet. For the packaged desktop preview, build the branch using the existing platform build scripts. Native signing and hardware validation are still required. ASPEN_WORKSPACE=1 opens the existing local AI workspace. ## Household apps - Butler: local tasks, due dates, completion tracking and reminders. The existing online Butler remains a separate service for bookings, email, phone calls and browser work. - Secure: last synchronized readings from approved Home Assistant door and motion sensors. It is not a monitored alarm service. - Energy: approved Home Assistant energy and climate readings. Automatic optimization and financial savings estimates are not implemented. Only the household owner can add or remove built-in apps and approve integrations. Third-party executable plugins and their sandboxing are not part of this release. ## Household privacy and security - The household vault is encrypted using AES-256-GCM. Desktop uses the operating-system key store when available. Headless mode uses a restricted local key file or an externally supplied key; protect the computer with disk encryption. - Passwords use salted scrypt. Sessions use HttpOnly, SameSite=Strict cookies, with Secure on HTTPS. Session tokens expire and sign-out revokes them. - Private memory is filtered by authenticated member before a model sees context. Devices receive only household-shared memory. - Pairing codes expire after five minutes and can be redeemed once. Client tokens are stored as hashes and can be revoked. - The device API validates room access and action permissions independently of the model. Light control is allowlisted. Lock, alarm, robot motion and arbitrary shell actions are excluded. - The household server has no cloud inference fallback, analytics, microphone capture or automatic internet tunnel. Explicit integrations and local model downloads have separate network needs. > This is an implemented security foundation, not a completed independent security audit. Recovery, encrypted backups, signed updates, hardware commissioning and a full production threat review remain release gates. ## Connect household devices 1. Open Settings, then Connected home. 2. Enter the local Home Assistant address and a long-lived access token. 3. Select the supported devices Aspen may access and assign their rooms. 4. Refresh readings from Settings or the Secure and Energy apps. The integration currently supports private IPv4 addresses and local hostnames resolving only to private IPv4 addresses. Credentials are never sent to the language model. Automatic mDNS provisioning and direct Matter pairing remain future work. ## Device API for phones, pods and robots The household API is rooted at /v1/home. An owner creates a short-lived pairing code in Settings. A client exchanges it at POST /pair, stores the returned Bearer token securely and uses only the granted scopes. See docs/HOME_API.md in the source for request schemas. - home:read — household-shared state; excludes private memory. - chat:ask — ask the local model with authorized context. - tasks:write — create and complete shared tasks. - devices:control — operate approved lights within the client’s assigned room. Room pods and robots must have a room. A shared device cannot supply a member ID to impersonate someone. Revoking the client disables its token immediately. Voice capture and robotics execution adapters are not included. ## AI workspace: Overview > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen is private AI that runs entirely on your own hardware. Instead of sending your prompts to a company's servers, Aspen runs an open large language model locally and gives you a clean app to chat with it. Nothing leaves your device. Aspen has three parts that work together: the model (an open LLM such as Llama, Qwen, DeepSeek, or Mistral that runs on your machine), a local gateway (an OpenAI-compatible server on your computer that handles requests, tools, and memory), and the apps (desktop for Mac and Windows, plus a free iPhone app that connects back to your own machine). > There is no cloud and no account. Core chat and coding work fully offline once a model is downloaded. ## AI workspace: Install > This section describes the existing Aspen AI workspace. It is separate from the new household preview. ### Mac and Windows Download the free app from runonaspen.com and open it. There is no terminal or configuration required. On first launch, Aspen detects your hardware and recommends a model to download. Prefer the command line? One command installs everything and adds Aspen to your apps menu: ```bash curl -fsSL https://www.runonaspen.com/install.sh | sh ``` > Windows may show a "Windows protected your PC" warning on first run because Aspen is from an independent developer. Click More info, then Run anyway. It is safe. ### iPhone Install "Aspen Local AI" free from the App Store. The phone app connects to the AI running on your own computer, so you can use your private models from anywhere. ## AI workspace: Quickstart > This section describes the existing Aspen AI workspace. It is separate from the new household preview. 1. Open Aspen. It detects your hardware and suggests a model that fits. 2. Let the recommended model download (one time). Smaller models download and load faster. 3. Type a question in the chat box and press enter. The reply streams back, generated on your machine. 4. Try voice, attach an image, or ask it to write and run code — all locally. That is the whole setup. Everything after this is optional configuration for power users and developers. ## AI workspace: Choosing a model > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen runs the latest open models and shows a library you can browse in Settings. Each model lists its size and the memory it needs, and Aspen flags any that may be too large for your machine. ### Rough hardware guide - 8GB RAM: small models around 3B parameters. - 16GB RAM: 7–8B models, a great all-round sweet spot. - 32GB RAM: 13–14B models. - 64GB+ RAM: 30B+ models for the strongest local quality. For most people a mid-sized Qwen or Llama model is the best default for chat, tool use, and coding. Aspen can update to a newer, better model automatically as the open ecosystem improves. > Quantized models use less memory and run faster with little quality loss — Aspen uses sensible quantized versions by default. ## AI workspace: Chat & artifacts > This section describes the existing Aspen AI workspace. It is separate from the new household preview. The chat works like any modern AI assistant: ask questions, brainstorm, write and edit text, or get coding help. Responses stream in real time, generated locally. When you ask Aspen to build something on the web — a page, a small app, a visualization — it renders a live artifact with a preview panel right in the chat, so you can see and run the result immediately. ## AI workspace: Voice > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen includes a hands-free voice mode with a natural neural voice. Speak your question and hear the answer back, with speech handled on your machine. ## AI workspace: Vision > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Attach a photo or screenshot and Aspen reads it with a local vision model. Ask it to describe an image, critique a design, extract text, or explain a chart. The image never leaves your machine. ## AI workspace: Tools > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Tools let your local model do things beyond chat. Every tool runs on your own computer and uses your own network; nothing is routed through Aspen's servers. Toggle each one in Settings. - Web search — current information from the live web, with the source cited. Runs from your machine and your IP. - Read web page — fetch and read the text of a specific URL. - Run commands — execute shell commands to clone repos, read and write files, and run scripts (works best with larger models). - Download files — fetch a file to work with locally. - Calculator and date/time — quick deterministic helpers. - Git — clone, status, and commit/push helpers. > For real-time questions (weather, news, prices), enable Web Search so the model answers from live results instead of memory. ## AI workspace: Memory (World Model) > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen can build a "World Model" — a set of facts about you, learned from your conversations, that makes its answers more personal and context-aware. It is stored as a plain file on your own computer. After each conversation, your local model quietly extracts useful facts (name, job, preferences, projects) and prepends them to new chats so the AI remembers who you are. You can view, edit, or delete any fact at any time. > 100% local — these facts never leave your machine and are never sent to any server. ## AI workspace: Developer API > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen runs a local gateway that speaks the OpenAI API format. Point any OpenAI-style client at your Aspen endpoint and it works unchanged — your tools now run against your own private AI. ### Endpoints - Same machine: http://localhost:4000/v1 - From anywhere: a private, secure HTTPS URL Aspen can generate for you, so your phone and other apps reach your machine securely. ### Python (OpenAI SDK) ```python from openai import OpenAI client = OpenAI( base_url="http://localhost:4000/v1", api_key="YOUR-ASPEN-KEY", ) resp = client.chat.completions.create( model="local", # the model name shown in the Aspen app messages=[{"role": "user", "content": "Hello from my own machine"}], ) print(resp.choices[0].message.content) ``` ### JavaScript (fetch) ```javascript const r = await fetch("http://localhost:4000/v1/chat/completions", { method: "POST", headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR-ASPEN-KEY", }, body: JSON.stringify({ model: "local", messages: [{ role: "user", content: "Hello" }], }), }); const data = await r.json(); console.log(data.choices[0].message.content); ``` ### API key tiers - Owner — full access including computer use and shared memory. Only for devices that are you. - Family / member — its own private memory plus safe tools; no computer use. - Anonymous guest — chat and safe tools only, ephemeral, safe to share widely. Aspen works with the OpenAI and Anthropic SDKs, LangChain, Cursor, Continue.dev, n8n, Zapier, and similar tools — anything that accepts a custom base URL and key. ## AI workspace: Connectors (MCP) > This section describes the existing Aspen AI workspace. It is separate from the new household preview. Aspen supports connectors built on the open Model Context Protocol (MCP), letting your local AI work with services like GitHub. Access tokens are encrypted and stay on your device. ## AI workspace: The Aspen device > This section describes the existing Aspen AI workspace. It is separate from the new household preview. The Aspen device is an optional, dedicated machine for running the largest models around the clock without using your own computer. You never need it to use Aspen — the free app runs well on a modern Mac or PC. - About 1 petaflop of AI performance - 128GB unified memory - Runs models up to roughly 200B parameters - Silent and always on - About 5.9" x 5.9" x 2" It is available by preorder with a $1 deposit. ## AI workspace: Troubleshooting > This section describes the existing Aspen AI workspace. It is separate from the new household preview. ### Windows "protected your PC" warning Normal and safe for a new app from an independent developer. Click More info, then Run anyway. If the download was blocked, right-click the file, choose Properties, check Unblock, then run it. ### A model is slow or crashes The model is probably large relative to your memory. Pick a smaller or more quantized model, close memory-heavy apps, or use a machine with more RAM. Aspen flags models that may be too big for your hardware. ### It says it cannot get current information Enable the Web Search tool in Settings so the model can answer real-time questions from the live web with cited sources. --- # Frequently Asked Questions ## Aspen at home ### What is Aspen? Aspen is your stay-home companion: private intelligence that lives at home. We are building experiences that capture opt-in family photos, help you cook from what is in the fridge, prompt you to check the stove, bring reminders as you come and go, and keep personal conversations and documents private. Hardware and these full experiences are in development; join the waitlist for launch news and early access. ### What happens when I join the waitlist? We save your email address so we can tell you about Aspen’s launch and early access. Joining is free and does not place an order. There is no launch date or hardware price announced yet. After a new signup, you get a personal invite link and a welcome email introducing the experiences we are building. Each new signup through your invite link gives you a seven-day head start in the queue. Duplicate signups do not count; removed signups lose their boost. We do not display queue positions, and joining does not guarantee early access. You can unsubscribe through the link in your email or contact us to leave the list. ### What can I use today? You can install the Mac or Windows 0.9.0 household developer preview. The newer source build also offers first-memory recall, turns pasted messages into locally drafted tasks, and turns a deliberate fridge photo or ingredient list into a dinner idea you can review and save privately. Email/calendar connections and automatic planning are still in development. The iPhone app remains the earlier AI workspace. ### Can Aspen capture candid family photos? That is a core experience we are building: with capture explicitly enabled, room pods capture everyday family moments and offer a small collection to review later. Photos are processed and stored locally on the Aspen hub. You choose rooms and times, keep or delete photos, and explicitly decide what to share. Planned controls include visible capture indicators, guest pause, physical camera shutters, and automatic expiry of unselected captures. Photo capture and collections are not available in the developer preview. Website family photography illustrates the idea; it was not captured by Aspen. ### How would Aspen help with the fridge and stove? Always-on fridge pods are planned. The newer source build can read a deliberately uploaded photo with a compatible local vision model, let you correct suggested ingredients, and propose a dinner using your selected saved preferences. Photos are not saved. It cannot establish food freshness or see through containers. Stove check reminders would need a compatible appliance integration or suitable heat sensor. An ordinary camera cannot measure temperature, and heat alone does not prove a stove is still powered on. This is a prompt to check, not a fire or gas alarm. Always-on fridge sensing and stove-check nudges are not available in the 0.9.0 installers. ### Does Aspen need its own box? No. The household core can run on a supported Mac, Windows or Linux computer. A dedicated Aspen device is planned as an easier, always-on option. Computers still need enough available memory and processing power for the selected model. ### What works without internet? Local sign-in, saved memory, task management and the reminder scheduler run on the home computer. Model answers work offline once a compatible model is installed and running. Connected device access needs the home network. Email, bookings, remote access, downloads and cloud-only services need internet. ### Will Aspen automatically find all my devices? The preview discovers supported lights, climate and sensor devices through an existing local Home Assistant installation. You approve which devices Aspen can access. Automatic Wi-Fi provisioning, direct Matter commissioning and universal device discovery are not included yet. ### Can my family keep things private? Yes. Family members have separate accounts. Notes are private by default and can be explicitly shared with the household. Room devices receive shared context only and cannot choose another person’s identity to read their private memory. ### Does Aspen use a fine-tuned household model? The preview uses installed local models and authorized household context. It does not include a newly trained or fine-tuned model. Hardware-aware model selection is conservative; household-task evaluation and model specialization remain development work. ### What about room speakers and robots? The architecture includes an authenticated device API with revocable access, room context and limited permissions. Listening pods, local speech recognition, wake-word detection, robot clients and robot motion control are planned. Microphone access is disabled in this preview. ### Is this the finished plug-and-play product? Not yet. This is the household developer preview. Automatic network onboarding, password recovery, secure remote access, audited app isolation and production hardware validation are required before a consumer release.