Skip to content
Aster
GitHub

Getting Started

Set up the repo, understand the workspace layout, and start the docs site.

Repo prerequisites

  • Node.js 24.13.1
  • Bun 1.3.9
  • Existing native/runtime dependencies required by the selected product runtime

The repo already pins the Node and Bun versions in the root workspace and uses Bun for package management.

Workspace layout

Current product runtime:

  • packages/distro - the default Aster product. Distro assembles auth, routes, sessions, spaces, apps, installables, default plugins, telemetry, marketplace sources, and the HTTP surface that the web and desktop apps use.

Frameworks and SDKs:

  • packages/gate - the Gate framework. It owns product composition contracts, graph validation, runtime planning, Effect service layers, generated SDK metadata, HTTP/server helpers, sockets, database contracts, marketplace contracts, analytics, and observability interfaces.
  • packages/spaces - the Spaces SDK. It provides Space.make(), composition helpers, triggers, lifecycle hooks, runtime context types, and worker supervision primitives for programmable spaces.
  • packages/sdk - the JavaScript/TypeScript client SDK for Aster’s gateway, runtime socket, Apps SDK, and React app-integration hooks.
  • packages/agent - agent authoring helpers, standalone tool-package helpers, runtime types, and turn primitives.
  • packages/authoring - extension, plugin, and host/runtime authoring primitives.
  • packages/services - shared runtime service contracts exposed through @aster/services/*.

Product surfaces and capabilities:

  • packages/app - the shared React application package used by the web and desktop shells.
  • products/web - the browser-hosted product UI.
  • products/desktop - the Electron desktop app.
  • products/docs - this public Astro + Starlight docs site.
  • packages/agent-runner - the container-side agent execution runtime.
  • packages/gate-adapters - concrete providers such as SQLite, PostHog, and OpenTelemetry.
  • capabilities/plugins/helpers - shared plugin helper exports exposed through @aster/plugin-helpers/*.
  • capabilities/plugins/* - core and example plugin packages, including plugins that contribute space extensions and agents.

packages/seed is deprecated and excluded from the active workspace. New runtime, route, product, and space work should start in packages/distro, packages/gate, packages/spaces, the SDK packages, or the relevant capability package.

Local commands

Install dependencies:

Terminal window
bun install

Start the docs site:

Terminal window
bun run dev:docs

Build the docs site:

Terminal window
bun run build:docs

Run the docs verification flow:

Terminal window
bun run check:docs

Product composition model

Aster separates reusable behavior into composable product primitives:

  • extensions
  • tool packages
  • plugins
  • skills
  • apps
  • spaces
  • routes
  • auth modules
  • database modules
  • marketplace sources

Marketplace repos are trusted install sources. A marketplace source is registered from either a local folder or a pinned GitHub ref and publishes installable items through a repo-root catalog.

Bundled defaults are owned by Distro, not by a global bootstrap file. Gate defines how product modules are planned and started. Spaces defines how per-project behavior is declared and run.

Accuracy model

The docs site separates generated reference from curated prose:

  • API shape comes from the OpenAPI document checked in at packages/sdk/openapi.json.
  • SDK metadata comes from the checked-in generated client plus the public entrypoints.
  • Synced technical pages still point back to their canonical package files.

That means the docs build can fail when committed generated artifacts drift from the runtime or SDK sources.