Space Agent is a browser-first AI agent runtime designed to enable AI agents to reshape their own interface, tools, and workflows in real-time. Unlike typical AI platforms where the agent is isolated within a fixed UI, Space Agent treats the browser as the primary application runtime app/L0/_all/mod/_core/documentation/docs/architecture/overview.md7-12 letting the agent live inside and extend the same framework that renders the UI. This allows the agent to build pages, widgets, and capabilities dynamically in the running workspace README.md33-35
Space Agent follows a thick frontend and thin backend design philosophy. The frontend runtime under app/ handles the core application logic, UI, prompt orchestration, and agent execution. The backend runtime under server/ acts as minimal infrastructure providing page shells, authentication, API endpoints, module file access, and an outbound fetch proxy app/L0/_all/mod/_core/documentation/docs/architecture/overview.md7-14 AGENTS.md45-52
The CLI entrypoint (space.js plus commands/) is responsible for starting and supervising the runtime environment app/L0/_all/mod/_core/documentation/docs/architecture/overview.md20-27
Space Agent organizes the runtime modules and customizations across three logical layers:
| Layer | Description | Storage Location |
|---|---|---|
| L0 | Firmware — Immutable core system modules | Preinstalled base layers in L0 |
| L1 | Group customware — Shared, modifiable by groups | Customware paths at CUSTOMWARE_PATH/L1 |
| L2 | User customware — Per-user modifiable overlay customware | Customware paths at CUSTOMWARE_PATH/L2 |
These layers ensure a clean separation of firmware base, group configurations, and user overrides. The frontend module system serves files from /mod/... URLs backed by L0/L1/L2 filesystem paths resolved in precedence order (L2 > L1 > L0). The admin UI is typically clamped to L0 only (maxLayer=0) to preserve stability app/L0/_all/mod/_core/documentation/docs/architecture/overview.md45-58
The following diagram maps key natural language system components and their corresponding main code entities and directories. This helps relate high-level concepts to concrete implementation locations.
Another diagram bridging Natural Language "Frontend" and "Agent" components to key code modules and runtime objects shows these relationships:
Sources:
app/L0/_all/mod/_core/documentation/docs/architecture/overview.md22-33 server/AGENTS.md79-98 README.md30-66 app/AGENTS.md1-70 app/L0/_all/mod/_core/framework/AGENTS.md1-64
The frontend (app/) is the core runtime engine, providing the main app shell, UI components, module loading, and runtime extension points. It uses a custom module system with layered resolution and a global space API object for UI framework features such as routing, component hydration (<x-component>), and Alpine.js integration.
The frontend handles the authenticated app shell, admin shell, panels and widget layouts, visual styling, and user cryptography for client-side encryption app/L0/_all/mod/_core/documentation/docs/architecture/overview.md9-14
For details, see Frontend Application Runtime.
The AI agent consists primarily of two surfaces: the Onscreen Agent (a floating overlay with avatar UI) and the Admin Agent for stable control and debugging. The prompt system builds text-based instructions and supports "skills" implemented via plain text SKILL.md files the agent can create and modify dynamically.
It supports remote LLM providers via OpenRouter and local LLM inference using HuggingFace/Transformers.js with WebGPU acceleration README.md52-53 app/AGENTS.md44-46 This modular, flexible architecture enables the agent to expand capabilities efficiently without bulky tool-call JSON.
For details, see AI Agent Runtime.
The backend (server/) is designed as a "thin" infrastructure layer. It handles:
index.html, admin.html, login.html, etc.)It is not a general app server but facilitates security, data integrity, session management, and routing for module delivery server/AGENTS.md79-98
For details, see Backend Server Runtime.
Space Agent can run as a standalone desktop app using Electron, which hosts the browser runtime locally, or as a server-based app managed through the node space CLI.
The CLI supports commands for server startup (serve), zero-downtime supervision (supervise), user and group management, parameter configuration (params.yaml), and package releases README.md98-116 commands/lib/supervisor/auth_keys.js1-76
For details, see CLI Commands and Runtime Parameters and Desktop App and Packaging.
The backend uses the layered customware storage to resolve file requests, favoring user overrides:
/mod/... is resolved from L2 if present, else L1, else L0.Sources:
server/AGENTS.md82-86 app/L0/_all/mod/_core/documentation/docs/architecture/overview.md49-56 server/lib/git/git_history.js1-15
To start exploring and running Space Agent locally:
Clone and Install Dependencies
Create Admin User
Use the CLI to create an admin user:
Start the Server
Run the local infrastructure server:
Development Mode
Run with auto-reloading for development:
For more detailed instructions on environment setup, running the desktop app, or managing multi-user deployments, see Getting Started.
Space Agent embraces a documentation-first approach. The AGENTS.md files are source-of-truth contracts governing module ownership, workflows, and coding rules in every directory subtree, forming a hierarchical DOX framework AGENTS.md1-95
Core documentation files include:
/AGENTS.md — project-wide instructions and child index/app/AGENTS.md — primary frontend runtime ownership/server/AGENTS.md — backend runtime governance/commands/AGENTS.md — CLI commands domain/packaging/AGENTS.md — desktop and packaging layer/tests/AGENTS.md — verification and test harnessesSee Repository Structure and Documentation System for a detailed map of the repo and documentation policies.
This overview serves as your entrypoint to understanding Space Agent’s design, architecture, and how its subsystems interrelate. For next steps, dive into the child pages for detailed guides and developer reference.
Sources:
app/L0/_all/mod/_core/documentation/docs/architecture/overview.md1-69 README.md26-134 AGENTS.md1-95 server/AGENTS.md79-98 commands/lib/supervisor/auth_keys.js1-76
Refresh this wiki
