API Reference / Docker Deploy

Docker Deploy is the dedicated workspace appliance path for customers who need many containerized apps on one always-on MIOSA-managed host.

Use the regular Deployments API for the deployment object. Use the Docker Deploy API to choose templates and provision the workspace-level appliance host.

Endpoints

GET  /api/v1/docker-deploy/templates
GET  /api/v1/docker-deploy/templates/:id
GET  /api/v1/docker-deploy/hosts?workspace_id=:workspace_id
POST /api/v1/docker-deploy/hosts/ensure
GET  /api/v1/docker-deploy/hosts/:id

POST /api/v1/sandboxes/:id/deploy
POST /api/v1/deployments/:id/publish

All endpoints require Authorization: Bearer <msk_*>. Mutations should include an Idempotency-Key header.

List templates

GET /api/v1/docker-deploy/templates

Returns curated container deployment templates such as Next.js app, Next.js static site, React/Vite, static HTML, Python API, Node API, and compose-backed app patterns.

Response:

{
  "data": [
    {
      "id": "nextjs-app",
      "name": "Next.js App",
      "runtime": "node",
      "build_command": "npm install && npm run build",
      "run_command": "npm start",
      "port": 3000,
      "health_check_path": "/"
    }
  ]
}

Get template

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

Use this when your UI needs the template defaults before creating or publishing a deployment.

List workspace hosts

GET /api/v1/docker-deploy/hosts?workspace_id=550e8400-e29b-41d4-a716-446655440000

Returns Docker Deploy appliance hosts visible to the caller.

Response:

{
  "data": [
    {
      "id": "78745c76-d5e6-4541-b651-1018f7cc0d89",
      "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
      "computer_id": "cmp_...",
      "runtime_base_url": "https://workspace-one.deploy.miosa.ai",
      "status": "active",
      "appliance_status": "healthy",
      "appliance_version": "miosa-docker-deploy-2026.06",
      "agent_configured": true
    }
  ]
}

Ensure workspace host

POST /api/v1/docker-deploy/hosts/ensure

Creates or returns the dedicated Docker Deploy appliance host for a workspace. This is the step that turns on the one-machine deployment center for that workspace.

Body:

{
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "region": "us-central",
  "size": "standard",
  "appliance_image": "registry.miosa.ai/docker-deploy/appliance:2026.06",
  "metadata": {
    "customer": "Clinic IQ"
  }
}

Response:

{
  "data": {
    "id": "78745c76-d5e6-4541-b651-1018f7cc0d89",
    "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
    "computer_id": "cmp_...",
    "status": "provisioning",
    "appliance_status": "booting",
    "agent_configured": false
  }
}

Get host

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

Returns the latest status for one appliance host. A deployment should not be considered Docker Deploy ready until the host is active and the deployed app health check passes through that host.

Publish from sandbox

POST /api/v1/sandboxes/:id/deploy

Body:

{
  "name": "Dr Smith Lead Magnet",
  "deployment_type": "docker_deploy",
  "docker_deploy_template_id": "nextjs-app",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "660e8400-e29b-41d4-a716-446655440001",
  "build_command": "npm install && npm run build",
  "run_command": "npm start",
  "port": 3000,
  "health_check_path": "/",
  "external_workspace_id": "clinic_123",
  "external_project_id": "lead_magnet_456"
}

The backend packages the sandbox, ensures the workspace Docker Deploy host exists, installs the release on that appliance path, waits for the app route health check, then returns the deployment and public URL.

Publish existing deployment

POST /api/v1/deployments/:id/publish

Use the same Docker Deploy fields when publishing a new version of an existing deployment:

{
  "source_sandbox_id": "sbx_...",
  "deployment_type": "docker_deploy",
  "docker_deploy_template_id": "nextjs-app",
  "build_command": "npm install && npm run build",
  "run_command": "npm start",
  "port": 3000,
  "health_check_path": "/"
}