App Engine hosts

An App Engine host is the always-on workspace VM that runs App Engine containers. This page covers the host model, its lifecycle, how a publish reaches it, and how MIOSA proves the app is live.

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 api POST /docker-deploy/hosts/ensure -d '{"workspace_id": "<workspace-id>"}'
miosa api GET /docker-deploy/hosts?workspace_id=<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.lumen.app
program.acme.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 deploy create --from-sandbox <sandbox-id> 
  --name my-app 
  --dir /workspace 
  --run-command "npm run start" 
  --port 3000 
  --type docker_deploy 
  --wait 
  --wait-timeout 900s 
  --json

To publish a new version without changing the deployment URL, reuse the same --name.

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 deploy get <deployment-id> --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, check the deployment’s public contract and, for App Engine, the host it runs on:

miosa deploy get <deployment-id> --json
miosa api GET /docker-deploy/hosts/<host-id>

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	`lumen.app`	Default customer preview/deployment domain
Workspace	`acme.lumen.app`	Client or expert workspace domain
Deployment	`program.acme.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.