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 gateway distribution

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

Workspace layout

Published SDKs (available on npm):

  • packages/sdk — generated gateway client (@aster/sdk).
  • packages/agent — agent authoring helpers, runtime types, and turn primitives (@aster/agent).
  • packages/agent — standalone tool-package authoring helpers (@aster/agent).
  • packages/authoring — extension authoring primitives (@aster/authoring).
  • packages/authoring — plugin authoring primitives (@aster/authoring).
  • packages/services — shared runtime service contracts exposed via @aster/services/*.

Internal packages:

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

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

Gateway composition model

Aster separates reusable behavior into composable distribution 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 the active gateway distribution, not by a global bootstrap file.

Accuracy model

The docs site separates generated reference from curated prose:

  • API shape comes from 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.