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 |
{
"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.