App Developer Guide
AI Cloud apps package a repeatable runtime experience on top of shared platform services: tenant and project context, identity, policy, billing, audit, routing, status, storage, and lifecycle.
Choose The App Family
| Family | Use it for | First proof |
|---|---|---|
| Notebook and IDE | Jupyter, VS Code, interactive workspaces. | Route opens, workspace persists, release works. |
| Inference endpoint | vLLM, OpenAI-compatible APIs, model serving. | /v1/models or health endpoint responds through the managed route. |
| Scheduler | Slurm, RKE2, OpenClaw, distributed jobs. | Job submission, scheduler route, worker cleanup. |
| Compose app | Multi-container app or service stack. | Ports, health, logs, and release cleanup. |
Current Onboarding Model
AI Cloud supports curated app catalog entries and platform-assisted onboarding today. A fully self-service public manifest-registration workflow is still a target capability.
For a new app today, prepare:
- app metadata;
- version metadata;
- image or artifact reference;
- resource requirements;
- input schema;
- endpoints and auth pattern;
- storage mounts;
- health checks;
- release and cleanup expectations;
- launch, connect, and support evidence.
Runnable Handoff Path
Use this path for the first app-developer handoff. It proves the same things an automation or SDK integration needs: identity, project scope, runtime launch, route/API access, credential lifecycle, and cleanup.
| Step | UI path | CLI/API surface | Proof to capture |
|---|---|---|---|
| Confirm project context | Header project selector, then Access > Projects | gpuaas auth whoami, gpuaas context show, GET /api/v1/projects | tenant, project, role, and project ID match the handoff packet |
| Create or select service account | Access > Service accounts | gpuaas service-accounts create; POST /api/v1/projects/{project_id}/service-accounts | service-account ID, slug, project scope, one-time credential custody |
| Mint automation token | tenant-admin or CI secret flow | gpuaas auth service-account-token; service-account token endpoint | short-lived token works without storing a human session in CI |
| Launch supported runtime | Apps > Catalog or runtime-family launch page | gpuaas apps launch; POST /api/v1/apps/instances or v3 app launch endpoint | app instance ID, runtime family, route/readiness status |
| Open route or API endpoint | Workloads > runtime detail > Open/Connect | app instance detail and proxy route readbacks | browser route opens or API endpoint returns health/model list |
| Rotate or disable credential | Access > Service accounts > detail | gpuaas service-accounts rotate-key or disable; rotate/disable service-account endpoints | old credential stops being used; new credential or disabled state is visible |
| Clean up runtime | Workloads > runtime detail > Stop/Release | gpuaas apps instances stop or decommission endpoint | runtime stops, route is removed, billing/usage posture is understandable |
Do not use a personal user token for a long-running app controller, CI job, or runtime reconciler. Use a project-scoped service account, keep project context explicit, and store secrets only in the CI or deployment secret store.
Runtime Proof Matrix
Each app family needs either a working proof in the target environment or an explicit blocker before the app is presented as ready.
| Runtime family | Reference path | Current proof posture | Handoff requirement |
|---|---|---|---|
| Scheduler | Slurm, RKE2, OpenClaw, Headlamp | Reference controllers and app SDK proof exist; target-environment launch/connect depends on runtime/provider readiness. | capture scheduler UI or job-submission proof, worker cleanup, and route/readback evidence |
| Notebook and IDE | Jupyter, VS Code, terminal workspace | Public guide and catalog path exist; target-environment proof must show route open, persistence expectation, stop/release, and cleanup. | capture route open, workspace state, release, and post-release inventory |
| Inference endpoint | vLLM, OpenAI-compatible endpoint | Contract and route pattern exist; remote demo/dev are unavailable and previous vLLM/OpenAI proof was blocked on worker/runtime readiness. | capture /v1/models or health through the managed route, auth boundary, model-readiness state, and cleanup |
| Compose app | OCI/container service stack | Manifest and route pattern exist; public self-service registration is still platform-assisted. | capture declared ports, health, logs, route, and release cleanup |
If the runtime cannot be proven, the guide should name the blocker and owner. Do not replace missing runtime proof with a manifest-only screenshot.
Manifest Shape
The manifest direction is JSON/YAML and contract-driven. This example uses the same concepts as current launchable OCI fixtures.
{
"profile": {
"kind": "gpuaas.launchable_oci_workload",
"schema_version": "v1",
"slug": "jupyterlab",
"display_name": "JupyterLab",
"support_level": "platform_curated",
"launch_mode": "existing_allocation"
},
"artifacts": {
"primary_image": {
"source": "platform_registry",
"artifact_name": "runtime-cpu",
"digest_required": true,
"media_type": "application/vnd.oci.image.manifest.v1+json"
}
},
"parameters": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"workspace_mount": {"type": "string", "default": "scratch"},
"host_port": {"type": "integer", "default": 8888}
}
}
},
"resources": {
"gpu": {"min_count": 0, "default_count": 1, "placement": "allocation_local"},
"cpu": {"min_cores": 2},
"memory": {"min_gib": 4}
},
"network": {
"endpoints": [
{
"name": "web",
"port": 8888,
"type": "http",
"auth_pattern": "header_injected_jwt",
"managed_ingress": {
"enabled": true,
"route_mode": "host",
"client_auth_mode": "browser_oidc",
"route_family": "browser_app",
"default_open_path": "/lab",
"websocket_required": true
}
}
]
}
}
Endpoint Patterns
| Endpoint type | Typical app | Client auth mode |
|---|---|---|
| Browser HTTP | Jupyter, VS Code, dashboards. | browser_oidc |
| API HTTP | OpenAI-compatible inference endpoints. | api_bearer |
| TCP | Internal app protocol where supported. | App-specific credential or service identity. |
| Job submission | Scheduler apps. | Project/user identity plus scheduler adapter. |
Do not put environment-specific public hostnames into the app manifest. Host binding is an environment/platform concern.
API And CLI Anchors
Use the CLI And SDK Guide for login, local credential storage, service-account token minting, idempotency, and SDK examples. Use CLI, SDK, And APIs for the public API model. Generated REST reference pages are published in the engineering portal until the public contract browser is ready for self-service use.
Builder-critical API areas:
| Area | API surface |
|---|---|
| service accounts | GET/POST /api/v1/projects/{project_id}/service-accounts, rotate, disable, delete |
| app catalog | app catalog and app version endpoints |
| app launch | v3 app launch precheck and submit endpoints |
| app instance lifecycle | get, stop, upgrade, rollback, decommission app instance |
| app runtime credentials | issue, rotate, reconcile, disable, and sweep runtime credentials |
| route/readiness | app instance route/readiness and platform-proxy route readbacks |
| storage | storage buckets, grants, credentials, and attachments |
Readiness Checklist
An app is ready for user testing when:
- the manifest declares all required inputs;
- image artifacts are digest-pinned or promoted through the approved artifact path;
- launch works in a clean project;
- the connect action lands on the expected route;
- health checks prove the app is ready;
- logs and status help users understand failure;
- release cleanup is tested;
- billing, storage, quota, and support behavior are documented.
- service-account rotation or disable behavior has been tested when automation credentials are part of the app path.
App Team Handoff
Send the platform team:
- manifest package;
- artifact digest or registry location;
- supported runtime family;
- required GPU/CPU/memory/storage;
- endpoint names, ports, and auth pattern;
- launch and readiness test plan;
- release cleanup behavior;
- owner and escalation contact.