Mothership
Runtime and automation
Runtime carries a planner-and-tools loop in the background from a profile the app declares, and waits for a person before risky tools. Automation reaches the same execution path from schedules, events and webhooks.
Runtime
Declare runtime_profiles in the app's manifest. Runs go into a durable queue and a separate runtime_worker executes them, so they continue after the browser disconnects.
"runtime_profiles": [{
"id": "review-loop",
"model_profile": "smart", // the AI tier that plans
"tool_set": ["document.classify"], // capabilities used as tools (connectors: connector:<id>/<tool>)
"procedure": "react", // or "plan-execute"
"skill_policy": {},
"system_instruction": "You review documents.",
"max_iterations": 8
}]
const run = await ctx.api.runtime.start({ profile: "review-loop", input: { question: "Summarize the report" } });
for await (const event of ctx.api.runtime.subscribe(run.runId, { transport: "sse" })) {
// run.*, planner.iteration.completed, tool.started|completed, job.linked, output.delta|completed
}
- Start and resume return
202with aqueuedsnapshot. Events are numbered, so a subscriber resumes where it left off (polling by default, SSE optional). - People in the loop:
risk_class: "high"tools always wait for approval. Input requests (decision: "submit"with aninputmatching the schema) and consent (approve/deny) work the same way. Consent never grants extra tool permissions. skill_policy:deny_tools,require_approval,max_tool_calls,allow_ask_user,allow_consent,interrupt_ttl_seconds. Unknown fields are refused.- Between steps the worker re-checks company, membership, claims, release, profile and deployment credentials. A crash at a safe checkpoint resumes; a crash with an external tool's outcome unknown fails as
runtime_execution_uncertaininstead of replaying it.
Jobs and streams
A backend worker's kind: "job" operations report progress and completion through callbacks after :start. At most once, no automatic retry. Concurrency is capped by usage_policy.limits (global, per company, per person). kind: "stream" operations pass the worker's SSE through.
Automation
Declare schedule, event and webhook triggers as trigger_templates in the manifest; the app creates instances. A trigger fires through the same execution path as a direct call, allowlists, claims and concurrency caps included.
"trigger_templates": [{
"id": "nightly-classify",
"source": { "type": "schedule", "interval_seconds": 86400 },
"target": { "type": "capability", "id": "document.classify", "version": "1.0" },
"run_as": "user_delegated", // or "agent_service"
"delivery": "at_least_once",
"configurable_fields": ["interval_seconds"],
"retry": { "max_attempts": 2, "backoff_seconds": 60 },
"concurrency": "forbid"
}]
| Source | How it fires |
|---|---|
| Schedule | interval_seconds. No cron expressions or calendars yet |
| Event | POST /api/v1/automation/instances/{id}/events with an app token |
| Webhook | POST /api/v1/automation/instances/{id}/webhook with X-Mothership-Signature: sha256=<HMAC> (over timestamp, event ID, trigger ID and body) and a timestamp within 300 seconds |
The run_triggers worker delivers them (it is part of the production workers). Every attempt for one event carries the same Idempotency-Key; receivers must honour it to avoid duplicate effects.