Skip to content
Sandbox Agent
GitHub Get Started
HTTP API

Start the private desktop runtime.

POST
/v1/desktop/start

Lazily launches the managed Xvfb/openbox stack, validates display health, and returns the resulting desktop status snapshot.

Request Body required

Section titled “Request Body required ”
object
displayNum
integer format: int32
nullable
dpi
integer format: int32
nullable
height
integer format: int32
nullable
recordingFps
integer format: int32
nullable
stateDir
string
nullable
streamAudioCodec
string
nullable
streamFrameRate
integer format: int32
nullable
streamVideoCodec
string
nullable
webrtcPortRange
string
nullable
width
integer format: int32
nullable

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Desktop runtime status after start

object
display
string
nullable
installCommand
string
nullable
lastError
object
code
required
string
message
required
string
missingDependencies
Array<string>
processes
Array<object>
object
logPath
string
nullable
name
required
string
pid
integer format: int32
nullable
running
required
boolean
resolution
object
dpi
integer format: int32
nullable
height
required
integer format: int32
width
required
integer format: int32
runtimeLogPath
string
nullable
startedAt
string
nullable
state
required
string
Allowed values: inactive install_required starting active stopping failed
windows

Current visible windows (included when the desktop is active).

Array<object>
object
height
required
integer format: int32
id
required
string
isActive
required
boolean
title
required
string
width
required
integer format: int32
x
required
integer format: int32
y
required
integer format: int32

400

Section titled “400 ”

Invalid desktop start request

object
detail
string
nullable
instance
string
nullable
status
required
integer format: int32
title
required
string
type
required
string
key
additional properties

409

Section titled “409 ”

Desktop runtime is already transitioning

object
detail
string
nullable
instance
string
nullable
status
required
integer format: int32
title
required
string
type
required
string
key
additional properties

501

Section titled “501 ”

Desktop API unsupported on this platform

object
detail
string
nullable
instance
string
nullable
status
required
integer format: int32
title
required
string
type
required
string
key
additional properties

503

Section titled “503 ”

Desktop runtime could not be started

object
detail
string
nullable
instance
string
nullable
status
required
integer format: int32
title
required
string
type
required
string
key
additional properties