Dev workspaces
A dev workspace is a private Linux VM for one person. It has root and sudo, a persistent disk and a private network. Rust, C and C++, ESP-IDF, Arduino, MicroPython, Claude Code and Codex are installed. The Sidra iPad app uses workspaces to edit and build code.
Workspace runtime
- Each workspace is one Kata VM with 4 vCPUs and 16 GB of memory, on a host in the
workspacepool. A workspace host serves only workspaces. - The disk is a block device with 50 GB. It holds everything the workspace writes, so installed packages and files survive a stop. The image stays read-only below it.
- A stop is a shutdown, and a start is a new boot of about 10 seconds. Files stay. Running processes and
tmuxsessions end. - The VM reaches the public internet only. It cannot reach its host, the host’s network or another workspace.
- A workspace stops after 30 minutes without use. Use means terminal input in the last 5 minutes, a compiler or build tool that runs, or CPU work. An open terminal with no input does not count.
Private network
Each organization has one dev tailnet with its own Headscale coordinator. It is separate from the tailnets of environments, so a device never becomes a peer of an environment gateway.
- The VM is a tailnet node, with SSH on port 2222 for the user
sidra. Projects are in/home/sidra/projects. - A device can reach only the VMs of its owner, and only on port 2222. A VM cannot reach another VM or a device.
- Tags are generated per person from the organization’s members. When you remove a member, their devices leave the tailnet and their VMs stop, within one minute.
- A join key works once and expires after ten minutes. The key is encrypted for the request that waits for it, so the database never holds it in clear text.
- Coordinators and the relay use the platform wildcard certificate on port 443, so a device trusts them with no extra root certificate.
API
Sign in as described in authentication. Every route needs at least the member role and a credential that belongs to a person.
| Route | Result |
|---|---|
POST /v1/dev/devices {"name","ssh_public_key"} | {"device_id","control_url","auth_key"}. Call it again for the same SSH key to get a fresh key. The SSH key must be ed25519 or P-256 |
GET /v1/dev/devices | Your devices |
DELETE /v1/dev/devices/{id} | Revokes the device, for its owner or an admin. Access ends within one minute |
GET /v1/dev/workspaces | Your workspaces |
POST /v1/dev/workspaces {"name"} | Creates a workspace and starts it |
POST /v1/dev/workspaces/{id}/start | Starts it. This also retries a workspace in failed |
POST /v1/dev/workspaces/{id}/stop | Stops it and keeps the disk |
DELETE /v1/dev/workspaces/{id} | Removes the VM and the disk |
A workspace is {"id","name","state","error","tailnet_host","ssh_port","ssh_user","ssh_host_key"}. state is provisioning, starting, running, stopping, stopped or failed. An error is a non-2xx response with {"error":{"code","message"}}.
Cost and limits
| Plan | VM | Disk |
|---|---|---|
| Cloud, your own servers | Free | Free |
| Cloud | EUR 0.25 per hour | EUR 0.10 per GB per month |
Each organization has a monthly cap of EUR 50 that counts only workspace VM hours and disk. When the cap is spent, workspaces stop and their disks stay. Other work, such as deployments and mail, continues. The organization budget also stops workspaces when it is a hard stop. Spend comes from finished hours, so a stop can be up to about 65 minutes late.
Use your own server
A workspace host needs KVM. Without /dev/kvm, enrollment for the workspace pool stops and says so. Add such a server in Sidra as a plain SSH host instead.
-
Enroll the server with the pool
workspace(your own servers). Workspace disks are kept in the data store, so size it for them: 50 GB per workspace, with--data-sizeor--data-device. -
Install Kata Containers 3.x and add the runtime to Docker, as for a build host.
-
Set these values in
/etc/pushleft/agent.env, and restart the agent:Setting Value PUSHLEFT_WORKSPACE_RUNTIMEkataPUSHLEFT_WORKSPACE_IMAGEThe workspace image of deploy/images.lock.envPUSHLEFT_HEADSCALE_IMAGEThe Headscale image of deploy/images.lock.env
The node offers workspaces (workspace_vm) only when KVM, the Kata runtime and these settings are all present.