Run commands and scripts directly on a computer without desktop interaction. Both endpoints block until the command exits and return combined stdout+stderr.

Base path: /api/v1/computers/{id}/exec

Execute Bash Command

POST /api/v1/computers/{id}/exec

Runs a shell command on the computer.

Request Body

Response - 200 OK

{
  "output": "total 24\ndrwxr-xr-x 6 user user 4096 Apr 11 10:00 .\n",
  "exit_code": 0
}

The output field contains combined stdout and stderr.

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"command": "ls -la /workspace", "timeout": 30}'

Examples

# Install a package
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"command": "sudo apt-get install -y jq", "timeout": 120}'

# Check disk space
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"command": "df -h"}'

# Multi-line script
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"command": "cd /workspace && mkdir -p project && echo done"}'

Execute Python Code

POST /api/v1/computers/{id}/exec/python

Runs Python code on the computer. The code is written to a temporary file and executed with python3.

Request Body

Response - 200 OK

{
  "output": "42\n",
  "exit_code": 0
}

How It Works

1. Code is written to /tmp/miosa_exec_<random>.py
2. Executed via timeout <N> python3 /tmp/miosa_exec_<random>.py 2>&1
3. Temporary file is deleted after execution
4. stdout and stderr are captured in output

Errors

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "code": "import sys\nprint(f"Python {sys.version}")\nprint(2 + 2)",
    "timeout": 30
  }'

Examples

# JSON processing
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "code": "import json\ndata = {"hello": "world"}\nprint(json.dumps(data, indent=2))",
    "timeout": 10
  }'

# File processing
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "code": "import os\nfor f in os.listdir("/workspace"):\n    print(f)",
    "timeout": 10
  }'

# Long-running computation
curl -X POST https://api.miosa.ai/api/v1/computers/{id}/exec/python 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "code": "total = sum(range(10_000_000))\nprint(f"Sum: {total}")",
    "timeout": 60
  }'

Terminal

Create Terminal Session

POST /api/v1/computers/{id}/terminal

Creates a WebSocket-based terminal session on the computer.

Request Body

Response - 201 Created

{
  "data": {
    "session_id": "default",
    "ws_url": "wss://my-computer.sandbox.miosa.ai/ws/terminal/550e8400-.../default?auth=stream_token",
    "stream_auth": "stream_token",
    "expires_at": 1712700060,
    "computer_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/terminal 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"cols": 80, "rows": 24, "shell": "/bin/bash"}'

Resize Terminal

POST /api/v1/computers/{id}/pty/{session_id}/resize

Resizes an active terminal session.

Request Body

Response - 200 OK

{
  "status": "ok"
}

curl -X POST https://api.miosa.ai/api/v1/computers/{id}/pty/{session_id}/resize 
  -H "Authorization: Bearer $MIOSA_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"cols": 120, "rows": 40}'

Timeout Behavior

• Commands exceeding the timeout are killed with SIGTERM
• The maximum timeout is 300 seconds (5 minutes)
• If no timeout is specified, the default is 30 seconds
• The timeout value is clamped: min(requested, 300)

Pre-installed Software

The default template includes:

• Python 3 with pip
• Node.js (if installed via selected_apps)
• Common CLI tools: curl, wget, git, vim, jq
• System utilities: htop, tree, zip/unzip

Install additional packages via the bash exec endpoint:

# Python packages
{"command": "pip install requests pandas numpy"}

# System packages
{"command": "sudo apt-get install -y postgresql-client"}

See also

• Streaming Exec - SSE stream for long-running commands
• Computers API - computer CRUD and lifecycle
• Files API - read and write files without exec
• Error Codes - COMPUTER_NOT_RUNNING, AGENT_UNAVAILABLE