Devices
A device is any runtime MIOSA can run a command on. <device> is an id, not a name, and the device surface does not care which kind of runtime answers.
Use it when a script has to work across runtime kinds, or when you have an id and do not know what it is.
List and inspect
A device record carries id, name, slug, template, kind, state, ip_address, node_id, running, terminal, and its capabilities.
Check capabilities before you act
Capabilities are the difference between a script that works everywhere and one that fails on half your devices.
| Capability | Sandbox worker | Computer |
|---|---|---|
exec | yes | yes |
files | yes | yes |
browser | no | yes |
artifacts | yes | no |
live_server | yes | yes |
connectors | yes | yes |
pause, resume | yes | yes |
snapshots | yes | no |
Read the capability rather than assuming it from the device’s name.
Run a command
Exec on a device resolves a running target.
A device that is not running returns DEVICE_NOT_RUNNING with the current state rather than starting it for you.
Files
miosa device read returns the file contents base64-encoded, and miosa device write takes the contents from --content or a JSON body with --file.
Expose a port
miosa device expose <device> 3000
curl --fail-with-body -sS
-X POST "https://api.miosa.ai/api/v1/devices/$DEVICE_ID/expose"
-H "Authorization: Bearer $MIOSA_API_KEY"
-H "Content-Type: application/json"
-d '{"port":3000}'On a host, the typed tunnel commands give you the fuller surface: access mode, slug control, and list and delete.
Browser URL
miosa device browser <device>GET /api/v1/devices/{id}/browser returns the streamed desktop for a computer, with desktop_url, ws_url, token, expires_at, computer_id, and slug, and a one-hour token TTL.
A sandbox returns BROWSER_UNSUPPORTED_FOR_SANDBOX; use a Computer when you need a desktop.
Lifecycle
miosa device extend <device> --timeout 2h
miosa device pause <device>
miosa device resume <device>
miosa device stop <device>
miosa device rm <device> --yes| Action | REST | Notes |
|---|---|---|
| Extend | POST /devices/{id}/extend with timeout_sec | Replaces the time to live |
| Pause | POST /devices/{id}/pause | Keeps the disk |
| Resume | POST /devices/{id}/resume | |
| Stop | POST /devices/{id}/stop | Keeps the disk |
| Destroy | DELETE /devices/{id} | Permanent; returns state destroyed |
Each lifecycle call returns the device’s new state.
Error codes
| Code | Status | Meaning |
|---|---|---|
MISSING_PARAM | 400 | A required field is absent; the response names it |
INVALID_PARAM | 400 | A field is present but not usable |
INVALID_BASE64 | 400 | File content was not valid base64 |
NOT_FOUND | 404 | The device does not exist, or is not yours |
DEVICE_NOT_RUNNING | 409 | The device is not running; the response carries its state |
UNSUPPORTED_FOR_COMPUTER | 422 | The operation does not apply to a computer |
BROWSER_UNSUPPORTED_FOR_SANDBOX | 422 | Browsing requires a computer |
DEVICE_OPERATION_FAILED | 422 | The runtime rejected the operation |