DevPlace REST: Dev Workspaces and Tunnels

Workspace lifecycle endpoints for the browser editor attached to a project, the editor-preferences reads and writes, and tunnel creation that publishes a container port on a public HTTPS hostname, with quota and idle-reaping behaviour.

A workspace is a browser editor attached to one of your projects. It runs your project files, a terminal, and preinstalled Python, Rust, Nim and Swift toolchains. sudo and apt install work with no extra setup; ports below 1024 cannot bind, so use a high port and publish it through a tunnel.

The editor opens with a DevPlace Code terminal already running the dpc coding agent and a plain shell beside it, and it trusts every folder, so nothing opens in Restricted Mode. Its appearance and boot behaviour are your own preferences, readable and writable through the two /workspace/editor endpoints below and explained on the workspace editor page. Editor preferences apply on the next workspace start.

A tunnel publishes one port from inside your container on a public HTTPS hostname of the form <port>-<name>.tunnel.pravda.education. Tunnel URLs are public and unauthenticated - anyone with the link can reach whatever you are serving. Forwarding a port in the editor's Ports view creates the tunnel for you through the same endpoint; un-forwarding it does not remove the tunnel.

Workspaces are bounded: a count limit per user, a disk quota, an egress quota, and a tunnel limit. An idle workspace is warned about, then stopped, then warned again, then removed. Every warning arrives as a workspace notification and states exactly what happens next and when.

GET /projects/{slug}/workspace - Read workspace

State, quota usage, idle countdown, tunnels and open moderation flags for your workspace on this project.

Minimal role: Member

Parameters

Sample response

{
  "has_workspace": true,
  "viewer_can_workspace": true,
  "workspace_count": 1,
  "max_workspaces": 2,
  "editor_url": "/projects/my-project/containers/instances/INSTANCE_UID/code/",
  "workspace": {
    "uid": "INSTANCE_UID",
    "status": "running",
    "suspended": false,
    "tunnel_name": "brave-otter",
    "primary_url": "https://brave-otter.tunnel.pravda.education",
    "disk_bytes": 5242880,
    "disk_quota_mb": 2048,
    "disk_percent": 1,
    "egress_bytes": 10240,
    "egress_quota_mb": 10240,
    "egress_percent": 0,
    "idle_stop_minutes": 60,
    "retention_days": 14,
    "max_tunnels": 5,
    "tunnels": [],
    "flags": []
  }
}

POST /projects/{slug}/workspace - Open or resume workspace

Create the workspace if you have none for this project, otherwise resume it. Idempotent. Refused when you are at your workspace limit, over disk quota, or suspended.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/projects/my-project/workspace"
}

POST /projects/{slug}/workspace/stop - Stop workspace

Stop the container. Files and tunnels are kept.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/projects/my-project/workspace"
}

POST /projects/{slug}/workspace/delete - Delete workspace

Remove the workspace and its tunnels. An administrator can restore it.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/projects/my-project/workspace"
}

GET /projects/{slug}/workspace/editor - Read editor profile

The resolved DevPlace editor profile for this workspace: theme, layout, panel preset, font sizes, zoom, boot terminals, how the editor opens, the container size, and where each value comes from.

Minimal role: Member

Parameters

Sample response

{
  "editor": {
    "trust_all": true,
    "theme": "devplace-dark",
    "font_size": 14,
    "terminal_font_size": 13,
    "zoom_level": 0,
    "layout": "standard",
    "panel_preset": "tall",
    "boot_agent": "dpc",
    "boot_shell": true,
    "window_mode": "tab",
    "window_width": 1600,
    "window_height": 1000,
    "cpu_millicores": 2000,
    "cpu_cores": 2.0,
    "memory_mb": 2048,
    "disk_quota_mb": 2048,
    "sources": {
      "theme": "user",
      "font_size": "site"
    }
  },
  "restart_required": false
}

POST /projects/{slug}/workspace/editor - Set editor preferences

Change your own editor preferences. Only the fields you send are changed; within those, an empty string or zero means inherit the site default, and reset drops every preference. Applies on the next workspace start, and the response says whether a restart is needed.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/projects/my-project/workspace",
  "data": {
    "restart_required": true
  }
}

GET /projects/{slug}/workspace/tunnels - List tunnels

Every public tunnel published by this workspace.

Minimal role: Member

Parameters

Sample response

{
  "tunnels": [
    {
      "uid": "TUNNEL_UID",
      "hostname": "8080-brave-otter.tunnel.pravda.education",
      "label": "web",
      "container_port": 8080,
      "status": "active",
      "cert_status": "valid",
      "request_count": 12,
      "bytes_out": 40960
    }
  ]
}

POST /projects/{slug}/workspace/tunnels - Create tunnel

Publish a container port on a public HTTPS hostname. The URL is public and unauthenticated. Refused past the tunnel limit. The certificate is ordered right away, so the hostname answers plain HTTP for a few seconds before it serves HTTPS. Forwarding a port in the editor calls this for you.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "data": {
    "uid": "TUNNEL_UID",
    "hostname": "8080-brave-otter.tunnel.pravda.education",
    "status": "pending"
  }
}

POST /projects/{slug}/workspace/tunnels/{uid}/delete - Delete tunnel

Remove a tunnel. The public URL stops serving immediately.

Minimal role: Member

Parameters

Sample response

{
  "ok": true,
  "redirect": "/projects/my-project/workspace"
}