Spaces SDK

Build programmable Aster spaces with @aster/spaces.

The Spaces SDK lives in packages/spaces and is published as @aster/spaces. It is the API for declaring programmable spaces: project-scoped environments with their own workspace settings, runtime selections, tools, skills, app access, triggers, and lifecycle hooks.

Distro stores and runs space modules. Gate includes selected spaces in the runtime plan. The SDK gives those modules a stable authoring surface.

Install

npm install @aster/spaces

Define a space

import { Space } from "@aster/spaces"

export default Space.make({
  slug: "release-notes",
  name: "Release Notes",
  description: "Collect changes and draft release notes for a project.",
  workspace: {
    mode: "isolated",
  },
  runtime: {
    executionSurfaceId: "local",
  },
  tools: [
    Space.use.tool("filesystem"),
    Space.use.tool("git"),
  ],
  triggers: [
    Space.trigger.prompt({
      id: "release-notes",
      prefix: "/release",
    }),
  ],
  async run({ input, agent, space }) {
    space.log.info("Drafting release notes")
    return agent
      .with({ tools: ["filesystem", "git"] })
      .session(input.sessionId)
      .prompt(input.content ?? "Draft release notes for this project.")
  },
})

Space.make() validates the module shape and produces a manifest that Distro can store, project into runtime state, and run through the space worker supervisor.

Composition surface

A space can declare:

workspace - shared, isolated, or hybrid workspace behavior
runtime - model, permissions, memory, transcription, execution surface, mode, mounts, timeout, and working-directory choices
extensions, tools, skills, agents, and subagents
mcpServers, companion spaces, and controller spaces
appAccess and plugin backends
triggers for prompts, app events, channels, and tasks
permissions, capabilities, and custom metadata
onStart, onConfigure, onStop, compose, and run hooks

The helper namespace keeps declarations consistent:

Helper	Use it for
`Space.use.extension()`	Enable an extension with optional settings.
`Space.use.tool()`	Enable a tool package or tool capability.
`Space.use.skill()`	Enable a skill.
`Space.use.mcpServer()`	Attach an MCP server.
`Space.use.appAccess()`	Request scoped access to a paired app.
`Space.use.pluginBackend()`	Bind to a plugin-provided backend.
`Space.trigger.prompt()`	Run a space from a prompt prefix or regex.
`Space.trigger.appEvent()`	Run from an external app event.
`Space.trigger.channel()`	Run from a channel event.
`Space.trigger.task()`	Run from a scheduled task.

Runtime context

Space hooks receive runtime APIs for sandbox execution, session creation, events, permissions, storage, logging, extensions, and agent delegation. This keeps space code product-aware without coupling it to deprecated Seed-era services.

Use the Spaces SDK for per-project capability bundles. Use the Gate framework when you need to compose the product runtime itself.