Golden Image

Project structure

project.json's parts choose the frontend and backend halves, and you edit only fixed folders. The app manifest (agents.json) declares the resources and permissions the app uses.

parts

parts in project.json says which halves are active. The backend is either backend (Python) or backend-node (Node), not both.

parts Builds Registration
["frontend"] (default) One frontend app Upload frontend/dist/<release>.zip
["frontend", "backend"] Frontend + Python worker ZIP + private backend connection
["backend"] One backend provider (Python) Private backend connection (URL + pre-shared key)
["frontend", "backend-node"] Frontend + Node worker ZIP + private backend connection
["backend-node"] One backend provider (Node) Private backend connection
project.json
{
  "parts": ["frontend"],
  "repository_contract_version": "1.0.0",
  "ai_tiers": "fast-smart-deep",
  "runtime_secrets": [],
  "data_changes": { "compatibility": "compatible", "migration": "없음", "rollback": "기존 데이터 유지" }
}

Folders

Path Role
frontend/agent/ The app's frontend. src/App.tsx, panels, agents.json (the manifest)
frontend/agent/src/ui/ The shared UI kit (tokens, components, fonts)
frontend/packages/ Vendored SDKs and contracts (sdk-core, sdk-react, agent-contracts)
backend/agent/ The Python worker's app.py and agents.json
backend-node/agent/ The Node worker's app.ts and agents.json
scripts/check.py Schema validation, registration rules, pairing
scripts/preview.sh Local preview (internal host; a public tunnel only by choice)
profiles/ Official profiles (the minimal app …)
Makefile setup / build / check / test / serve / preview

Edit only frontend/agent/ and backend/agent/ (or backend-node/agent/). SDKs, contracts and build scripts are managed by base updates. Write the app's own rules and notes in the "This app" section of AGENTS.md.

The manifest (agents.json)

It declares what the app uses and offers. Mothership validates it at registration and shows company administrators "the access this version asks for".

Field Meaning
agent id, name, description, kind (frontend/backend)
release release_id, artifact_hash (filled by the build)
resources Records (record_schema, scope such as user_private), object storage (api: "storage.objects")
state_namespaces Key/value state (value_schema). Bare keys ("preferences"), no app-id prefix
claims Permission names the app uses; company administrators allow or deny them per member
capabilities.requires, resource_requests Capabilities and shared data other apps offer
connector_requests External tools (MCP) to use
runtime_profiles Runtime profiles
trigger_templates Automation triggers
usage_policy Requests per minute, job concurrency

Mothership compiles each resource declaration into a JSON access policy at publish time and evaluates it on every request. Tenant isolation is enforced in that one application layer.

Contract version

Contract 1.2.0 names the AI tiers fast/smart/deep (1.1.0's smart became deep, and default became smart). Move a 1.1.0 app at once with python3 scripts/rename_ai_tiers.py; make check stops until it has run or been acknowledged. Releases built against 1.1.0 still register and run on Mothership.

Esc