Aspen 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.

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.

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.

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

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).

AI workspace: Install

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:

curl -fsSL https://www.runonaspen.com/install.sh | sh

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

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

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.

AI workspace: Chat & artifacts

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

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

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

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.

AI workspace: Memory (World Model)

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.

AI workspace: Developer API

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)

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)

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)

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

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

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.