DevPlace REST: Container Manager

Administrator-only endpoints that run supervised container instances per project: desired-state mutations and the reconciler, lifecycle and exec calls, terminal and log websockets, schedules, and the per-user isolation and primary-administrator rules.

Run supervised container instances for a project. There is no in-app image building: every instance runs one shared prebuilt image (ppy:latest) with the project's workspace mounted at /app. Every endpoint is administrator only (docker socket access is root-equivalent). Mutations flip desired state; a single reconciler converges containers to it.

Containers are additionally isolated per user. The primary administrator (the first Admin account) sees and manages every instance, including those attached to private projects. Any other administrator sees instances on public projects plus their own; instances attached to another user's private project are invisible. Managing an instance (edit, lifecycle, exec, terminal, sync, delete, schedules) is restricted to the instance owner (its creator or the owner of its project) and the primary administrator; a non-owner administrator receives 403 on mutations and a view-only detail page.

GET /projects/{project_slug}/containers - Container manager page

The admin per-project container manager UI (instance creation and lifecycle). Returns 404 for an administrator when the project is another user's private project (the primary administrator always has access).

Minimal role: Admin

Parameters

GET /admin/containers - Admin containers list

The admin Containers section, scoped per viewer: the primary administrator sees every instance; other administrators see instances on public projects plus their own. Rows the viewer cannot manage are view-only, and mutations on them return 403.

Minimal role: Admin

GET /admin/containers/data - Admin containers list data

JSON of the viewer-visible instances (decorated with project title/slug and a per-row can_manage flag) for polling.

Minimal role: Admin

Sample response

{
  "instances": [
    {
      "uid": "INSTANCE_UID",
      "name": "staging",
      "status": "running",
      "project_slug": "PROJECT_SLUG",
      "project_title": "My Project",
      "ingress_slug": "my-service",
      "restart_policy": "always"
    }
  ]
}

GET /admin/containers/{uid} - Instance detail page

The dedicated detail page for one instance (lifecycle, logs, metrics, terminal, schedules, ingress, sync).

Minimal role: Admin

Parameters

GET /admin/containers/{uid}/edit - Edit instance page

The edit page for one instance (run-as user, boot language/script/command, restart policy, start-on-boot, limits).

Minimal role: Admin

Parameters

Sample response

{
  "instance": null,
  "project": {},
  "run_as_user": {},
  "boot_languages": [],
  "restart_policies": [],
  "admin_section": "string",
  "user": null
}

POST /projects/{project_slug}/containers/instances - Create an instance

Create and (by default) start an instance; it runs the shared ppy image with the project workspace mounted at /app.

Minimal role: Admin

Parameters

GET /p/{slug} - Container ingress proxy

Public reverse proxy (HTTP and WebSocket) to a running instance published via ingress_slug. The /p/<slug> prefix is stripped before forwarding.

Minimal role: Public

Parameters

POST /projects/{project_slug}/containers/instances/{uid}/{action} - Instance lifecycle

start, stop, restart, pause, or resume an instance (flips desired state).

Minimal role: Admin

Parameters

GET /projects/{project_slug}/containers/instances/{uid}/logs - Instance logs

Recent docker logs of a running instance.

Minimal role: Admin

Parameters

Sample response

{
  "logs": "..."
}

POST /projects/{project_slug}/containers/instances/{uid}/sync - Sync workspace

Run a one-shot bidirectional newer-wins sync between the project files and the container workspace.

Minimal role: Admin

Parameters

Sample response

{
  "exported": 3,
  "imported": 1
}

POST /projects/{project_slug}/containers/instances/{uid}/delete - Delete instance

Remove a container instance and mark its container for removal.

Minimal role: Admin

Parameters

POST /projects/{project_slug}/containers/instances/{uid}/exec - Exec a command

Run a one-shot command inside a running instance and return its output.

Minimal role: Admin

Parameters

GET /projects/{project_slug}/containers/instances/{uid} - Instance detail data

Return the full instance row plus runtime info as JSON.

Minimal role: Admin

Parameters

Sample response

{
  "uid": "INSTANCE_UID",
  "name": "staging",
  "status": "running"
}

GET /projects/{project_slug}/containers/instances/{uid}/metrics - Instance metrics

Return recent metrics ring-buffer and aggregated stats for a running instance.

Minimal role: Admin

Parameters

Sample response

{
  "metrics": [],
  "stats": {}
}

POST /projects/{project_slug}/containers/instances/{uid}/schedules - Create a schedule

Attach a cron, one-time, interval, or delay schedule to an instance.

Minimal role: Admin

Parameters

POST /projects/{project_slug}/containers/instances/{uid}/schedules/{sid}/delete - Delete a schedule

Remove a schedule from an instance.

Minimal role: Admin

Parameters

POST /admin/containers/create - Admin create instance

Create an instance from the admin Containers page: project search-select, run-as user, boot language/script, restart policy, start-on-boot, plus the usual options.

Minimal role: Admin

Parameters

POST /admin/containers/{uid}/edit - Admin edit instance

Update an instance's run-as user, boot language/script/command, restart policy, start-on-boot flag, and resource limits.

Minimal role: Admin

Parameters

POST /admin/containers/{uid}/{action} - Admin instance lifecycle

start, stop, restart, pause, or resume an instance from the admin Containers page (flips desired state).

Minimal role: Admin

Parameters

POST /admin/containers/{uid}/sync - Admin bidirectional sync

Run a one-shot bidirectional newer-wins sync between the project files and the container workspace.

Minimal role: Admin

Parameters

Sample response

{
  "exported": 3,
  "imported": 1
}

POST /admin/containers/{uid}/delete - Admin delete instance

Soft-delete an instance and mark its container for removal.

Minimal role: Admin

Parameters

GET /admin/containers/projects/search - Admin project search

Search projects by title for the admin create form (returns uid, slug, title).

Minimal role: Admin

Parameters

Sample response

{
  "results": [
    {
      "uid": "PROJECT_UID",
      "slug": "PROJECT_SLUG",
      "title": "My Project"
    }
  ]
}

GET /admin/containers/users/search - Admin run-as user search

Search users by username for the run-as-user select (returns uid, username).

Minimal role: Admin

Parameters

Sample response

{
  "results": [
    {
      "uid": "USER_UID",
      "username": "alice"
    }
  ]
}