A Runtime Instance is a running production VM that serves a dynamic deployment. Static deployments do not have runtime instances; they’re served from MIOSA’s edge directly.

What a runtime instance is

A microVM booted by Firecracker from the customer’s release rootfs (not from the sandbox image, not from the builder image). The release is the customer’s app, fully packaged. The instance:

1. Boots in under a few seconds.
2. Receives PORT, DATABASE_URL, AUTH_URL, and other env vars injected by MIOSA at boot.
3. Starts the configured run_command.
4. Listens on port.
5. Responds to GET health_check_path with 2xx.
6. Joins the deployment’s backend pool; the router starts sending it traffic.

When a runtime instance dies (crash, host failure, configured restart), MIOSA’s reconciler notices and schedules a replacement on another healthy host.

What you control vs what MIOSA controls

You don’t pick a host directly. MIOSA’s scheduler matches your workload’s requirements (CPU, RAM, GPU if requested, region) against the fleet’s free capacity.

Lifecycle

pending  → starting  → healthy   → stopping  → stopped
                    ↘ unhealthy  ─┘
                    ↘ failed

• pending: scheduled, not yet booting.
• starting: VM is booting; health check not yet passing.
• healthy: serving traffic.
• unhealthy: failing health checks; router has removed it from the pool. Reconciler decides whether to restart or replace.
• stopping / stopped: deliberately torn down.
• failed: terminal — exceeded crashloop budget. Reconciler stops trying.

Health checks and the grace period

When a runtime instance starts, it has a configurable grace period (default 60s) to become healthy. During grace, repeated 5xx / connection-refused are tolerated.

After grace, the health check is enforced strictly:

• 3 consecutive failures → instance marked unhealthy, removed from routing.
• If a replacement is needed and starts healthily, the old instance is torn down.
• Repeated rapid failures invoke crashloop backoff: 1s → 2s → 5s → 30s → 5min between restart attempts.

Blue/green during publish

When you publish a new dynamic version, MIOSA does NOT terminate the existing healthy instances first. The sequence is:

1. Start new runtime instances from the new release.
2. Wait until enough new instances pass health checks.
3. Update the router so the deployment’s hostname points at the new instances.
4. Drain (stop accepting new connections) and tear down old instances after old in-flight requests complete.

If step 2 never succeeds, step 3 never runs. The old version stays live, the new version is marked failed.

Replicas

By default, a dynamic service has 1 replica. Increase by setting desired_replicas on the service. The reconciler spreads replicas across hosts and across availability zones where possible.

await miosa.services.update(serviceId, { desiredReplicas: 3 })

Traffic load-balances across all healthy replicas in round-robin (or hash-based if sticky sessions are configured).

Resource sizing

Sizing is per-service, per-deployment. A worker service can be smaller than a web service. A GPU inference service needs a GPU-capable host.

Logs

Runtime instances stream stdout/stderr to MIOSA’s log plane. Logs are retained per the tenant’s plan (default 7 days). Access them through:

• GET /api/v1/deployments/:id/logs — deployment-scoped, all services
• GET /api/v1/services/:id/logs — per-service
• GET /api/v1/runtime-instances/:id/logs — per-instance

Logs include structured metadata: service_id, runtime_instance_id, version_id, host_id. Filter by external_workspace_id to scope to a white-label customer.

See also

• Releases — what runtime instances boot from
• Environments — variable / secret scope
• Domains — how traffic finds your instances
• Rollback — what happens to old instances on rollback