pushleft
Deploy your first app
Manual contents
Handbook
HandbookPushleftArchitecture
Operate
Install the control planeYour own serversFleetOperations and alertsAuthenticationDomains and DNSUsage and budgetsScheduled jobsAbuse controlsAI provider proxyCustomer mailErrors and performanceLogs and metricsRetentionObject storageContainer registryGit server
Develop
The .pl.yaml manifestOnboard with an AI agentThe pl up demoBuild executorSource ingestionAgent gatewayManaged databasesSecurity findingsTunnels and shellsDev workspacesPrivate hostnamesMesh coordinatorsDesign baseline
Runbooks
Control-plane host failoverControl-plane PostgreSQL failoverControl-plane PostgreSQL restoreCustom domains and certificatesGateway key compromiseIngress host failureNode busyNode disk fullNode drain and replacementNode lostRegistry outageHetzner Robot hostsSecret rotationSecurity incidentStaging fleet on ProxmoxStaging build cacheStuck deploymentVault/OpenBao backup and recovery
Manual · docs/dev-workspaces.md

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 workspace pool. 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 tmux sessions 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.

RouteResult
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/devicesYour devices
DELETE /v1/dev/devices/{id}Revokes the device, for its owner or an admin. Access ends within one minute
GET /v1/dev/workspacesYour workspaces
POST /v1/dev/workspaces {"name"}Creates a workspace and starts it
POST /v1/dev/workspaces/{id}/startStarts it. This also retries a workspace in failed
POST /v1/dev/workspaces/{id}/stopStops 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

PlanVMDisk
Cloud, your own serversFreeFree
CloudEUR 0.25 per hourEUR 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.

  1. 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-size or --data-device.

  2. Install Kata Containers 3.x and add the runtime to Docker, as for a build host.

  3. Set these values in /etc/pushleft/agent.env, and restart the agent:

    SettingValue
    PUSHLEFT_WORKSPACE_RUNTIMEkata
    PUSHLEFT_WORKSPACE_IMAGEThe workspace image of deploy/images.lock.env
    PUSHLEFT_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.

Rendered from the repository at build time. Edit docs/dev-workspaces.md to change it.