App Engine

App Engine is MIOSA’s dedicated workspace host model for customers that need many small apps, funnels, lead magnets, APIs, or client sites without creating a new production VM for every deployment. It is the recommended production path for generated apps that should run 24/7 inside a workspace.

How it works

When App Engine is enabled for a workspace, MIOSA provisions one always-on App Engine VM for that workspace. That host runs:

A white-labeled App Engine portal for the workspace.
The private App Engine control service.
One or more app containers created from immutable release artifacts.

The deployment still belongs to the MIOSA organization, workspace, project, and deployment records. The Docker host is execution capacity, not an authorization boundary.

App Engine is not a label on a normal dynamic runtime. For App Engine publishes, MIOSA must wait for the workspace host and private agent to be ready before the deployment can be marked ready. If the host is not active, the publish response stays pending instead of falling back to the standard runtime pool.

App Engine apps are launched as isolated containers on the workspace host. MIOSA records each app target durably so routing and recovery do not depend on transient process state.

Host lifecycle

Create or inspect the workspace host before publishing customer apps:

miosa docker-deploy ensure --workspace <workspace-id>
miosa docker-deploy hosts --workspace <workspace-id>

The host moves through provisioning states until the App Engine runtime is reachable and passes health checks.

State	Meaning
`provisioning`	MIOSA is creating or starting the workspace Computer.
`bootstrapping`	The portal and private deployment agent are being installed.
`active`	The host is healthy and can accept App Engine publishes.
`failed`	MIOSA could not provision or bootstrap the host. Retry after fixing the reported issue.

Each enabled workspace normally has one App Engine host. That host can run many app containers, and MIOSA still accounts deployments individually by organization, workspace, project, and deployment.

Default URL behavior

Until a custom domain is attached, MIOSA returns a managed URL. For a deployment in the OSA tenant, that can look like:

https://my-app.osa.miosa.app

If the organization configures its own preview or deployment domain, workspace and project deployments can use that domain instead:

intake.cliniciq.dev
program.drsmithclinic.com

The exact URL is always returned by the publish/deploy response. Do not construct it in your app. The effective URL hierarchy is:

Deployment custom domain.
Workspace deployment domain.
Tenant deployment domain.
MIOSA-managed tenant URL at https://<deployment-slug>.<tenant-slug>.miosa.app.

Workspace and project scoping

App Engine follows the same MIOSA attribution model as sandboxes and normal deployments:

For multi-tenant products, pass your external IDs when creating workspaces, projects, sandboxes, and deployments. MIOSA stores those for billing, support, and customer mapping.

Publishing to App Engine

Use App Engine when you want a sandbox artifact to run on the workspace Docker host instead of the standard dynamic runtime pool.

miosa sandbox publish <sandbox-id> 
  --path /workspace 
  --slug my-app 
  --build-command "npm run build" 
  --run-command "npm run start" 
  --port 3000 
  --docker-deploy 
  --wait 
  --timeout 900 
  --json

To publish a new version without changing the deployment URL, add --app <deployment-id>.

The platform flow is:

Freeze the sandbox files into a release artifact.
Ensure the workspace App Engine host is active.
Upload the release to that workspace host.
Build the release into a Docker image.
Run the image as a local Docker container on the host.
Record the durable app target and runtime route.
Register MIOSA routing to the returned host port.
Return the live deployment URL.

If the host is still provisioning, the API returns ready: false instead of silently serving the app through a standard runtime.

Proving App Engine deployments

An App Engine deployment is live only when all of these are true:

Proof item	Required state
Deployment row	Exists and has `deployment_product: "docker_deploy"`
Host link	`docker_deploy_host_id` points to the workspace App Engine host
Host health	Host is active and reachable
App target	The deployment has a durable running App Engine target
Container route	The active target has a reachable container route
Public URL	HTTP probe to `public_url` succeeds

Use:

miosa docker-deploy doctor <deployment-id> --probe-path / --json

Updates and recovery

Every publish creates a candidate release. MIOSA keeps the current healthy version serving until the candidate is built, started, health checked, routed, and promoted. A failed candidate does not replace the live version.

Host maintenance can briefly interrupt apps on that host. MIOSA preserves deployment records, release artifacts, domains, data bindings, and desired state while the host is updated. Deployments that were running are reconciled and verified before the host returns to active service.

An intentionally stopped deployment remains stopped. MIOSA does not treat a deliberate stop as a recovery target.

After maintenance, use deployment proof for the public contract and App Engine doctor for host-specific evidence:

miosa deploy prove <deployment-id> --json
miosa docker-deploy doctor <deployment-id> --probe-path / --json

Starter templates

App Engine templates are curated app shapes for agents, SDKs, and the UI. They do not replace your project code. They provide Dockerfile, Compose, command, port, environment, persistence, and design-context defaults before a sandbox or repository is published.

Template	Best for	Runtime
Next.js App	SaaS portals, dashboards, client apps	Node
Next.js Funnel / Landing Page	funnels, lead magnets, campaign sites	Node
Vite React SPA	static React apps, calculators, widgets	Nginx
Express / Node API	webhooks, integrations, lightweight APIs	Node
FastAPI Service	Python APIs, AI helper services, data tools	Python
Static HTML Site	documents, one-page tools, static downloads	Nginx
Compose Full-Stack App	web + API + worker + Postgres + Redis on one host	Docker Compose

Template metadata is returned by:

GET /api/v1/docker-deploy/templates
GET /api/v1/docker-deploy/templates/:id

Use a template id as metadata when creating a deployment so the deployment center can show the intended build shape and recover the defaults later:

{
  "deployment_product": "docker_deploy",
  "metadata": {
    "docker_deploy_template_id": "compose-full-stack"
  }
}

Runtime boundary

App Engine uses two different host-side services:

Service	Visibility	Purpose
Portal	User-facing, white-labeled	Shows the workspace deployment center.
Agent	MIOSA-private network only	Receives release artifacts and starts containers.

Never expose the agent URL, Docker socket, host IP, or internal API key to browsers or customer code. SDKs, MCP tools, and customer apps should call MIOSA APIs; MIOSA talks to the workspace host.

Domains

Domains can be set at several levels:

Level	Example	Use
Organization	`cliniciq.dev`	Default customer preview/deployment domain
Workspace	`drsmith.cliniciq.dev`	Client or expert workspace domain
Deployment	`program.drsmithclinic.com`	Exact app/site/funnel domain

MIOSA still verifies DNS, issues TLS, and routes traffic. The App Engine host only runs the app containers.

What users see

Customers see MIOSA or your white-labeled product language. They should not see provider names, raw host IPs, Docker socket details, or internal agent URLs.

API and SDKs

Use the App Engine host APIs when your app needs to prepare a workspace before a publish:

GET  /api/v1/docker-deploy/hosts?workspace_id=<workspace-id>
POST /api/v1/docker-deploy/hosts/ensure
GET  /api/v1/docker-deploy/hosts/:id

The TypeScript and Python SDKs expose the same host operations. MCP tools are available for agents that need to check or ensure the workspace host before publishing.