shadow-space-app

name	shadow-space-app
description	Build, publish, and operate Space Apps from an agent runtime. Use when an agent needs to create a Space App, expose an agent-hosted service safely, mount it under a Shadow domain, define Space App commands, register host-rendered desktop or mobile widgets, or call installed Space Apps through the shadowob CLI.

Space App

Use this skill when creating, reviewing, publishing, or operating a Space App. An Space App is installed into a specific Shadow server, may expose a full Space App UI and host-rendered widgets, and exposes Buddy-callable commands through the Space App protocol.

This skill is distributed as a standard Skill package. Cloud runtimes receive it through the shadowob plugin's official skill injection, and local runtimes receive it through shadowob-connector; do not depend on a separate docs directory or CLI docs subcommand.

Read References

• Read references/space-app-standard.md before designing or changing a Space App.
• Read references/widgets.md before adding or reviewing a host-rendered widget.
• Read references/scaffold.md before creating a new Space App from scratch or deciding whether to use the scaffold generator.
• Read references/runtime-publish-backup.md before exposing an agent container service, publishing to a shadowob.com subdomain, or designing persistence and backup.

Non-Negotiable Rules

• Keep Space App-owned /api/* separate from Shadow gateway ingress. New Space Apps must expose Shadow platform routes only under /.shadow/*.
• Use the modeled @shadowob/sdk Space App helpers instead of reimplementing manifest rewriting, Shadow command token validation, command request parsing, JSON Schema validation, or actor labels.
• Use shadow.space-app/1 manifests, stable appKey values, stable command names, and explicit permission, action, and dataClass on every command.
• Register small dashboard views through manifest widgets and a read-only command. Never inject Space App HTML, CSS, or JavaScript into the widget host, or implement widget-owned move and resize behavior.
• Buddies must operate installed Space Apps through shadowob space-app discover, shadowob space-app skills, and shadowob space-app call; never hand a Buddy raw HTTP routes, app tokens, or shared secrets.
• For local development, install with --manifest-file; production manifests, iframe URLs, API URLs, icon URLs, and OAuth redirect URIs must be stable HTTPS origins.
• Never publish public http://<ip>:<port> origins in a manifest. If a proxy forwards to a private host, keep the private address out of the public manifest.
• Never load Shadow OAuth inside the Space App iframe. Use a top-level popup or navigation and include allow-popups-to-escape-sandbox on the iframe sandbox.
• Keep iframe URLs stable. Space App UI must call Space App-owned /api/*; it must not call command ingress routes or Shadow gateway routes directly.
• Declare state paths and backup policy before publishing an agent-hosted app. Runtime code, build output, config, secrets, and mutable app state must have separate ownership and lifecycle.
• For a new Space App, start from shadowob space-app generate <app-key> or node scripts/create-space-app.mjs <app-key> unless the user asks for a different stack.

CLI Workflow

shadowob space-app discover --server <active-server-id-or-slug> --json
shadowob space-app skills <app-key> --server <active-server-id-or-slug>
shadowob space-app call <app-key> <command> \
  --server <active-server-id-or-slug> \
  --json-input '{"key":"value"}' \
  --json

For binary command input:

shadowob space-app call <app-key> <command> \
  --server <active-server-id-or-slug> \
  --json-input '{"purpose":"import"}' \
  --file ./input.pdf \
  --json