Docker Deploy 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.

How it works

When Docker Deploy is enabled for a workspace, MIOSA provisions one always-on managed Computer for that workspace. That Computer runs:

1. A white-labeled Docker Deploy portal for the workspace.
2. A MIOSA-private deployment agent.
3. One or more app containers created from sandbox 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.

Docker Deploy is not a label on a normal dynamic runtime. For Docker Deploy 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.

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 MIOSA Computer is reachable and the private Docker Deploy agent passes health checks.

Each enabled workspace normally has one Docker Deploy 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 Clinic IQ style setup that might look like:

dr-smith-intake.cliniciq.miosa.app

If the organization configures its own preview/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.

Workspace and project scoping

Docker Deploy follows the same MIOSA attribution model as sandboxes and normal deployments:

organization
  workspace
    project
      sandbox
      deployment
      domains
      data services

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 Docker Deploy

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

miosa deploy --docker-deploy

The backend flow is:

1. Freeze the sandbox files into a release artifact.
2. Ensure the workspace Docker Deploy host is active.
3. Upload the release to that workspace host.
4. Build and run the app as a container on the host.
5. Register MIOSA routing to the returned host port.
6. 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.

Starter templates

Docker Deploy 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 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

Docker Deploy uses two different host-side services:

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:

MIOSA still verifies DNS, issues TLS, and routes traffic. The Docker Deploy 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 Docker Deploy 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.

See also