Skip to main content
POST
/
api
/
profile
/
{profile_id}
/
room
/
{room_id}
/
command
Execute command in VM instance
curl --request POST \
  --url https://api.gentility.ai/api/profile/{profile_id}/room/{room_id}/command \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "command": "python -c 'print(\"Hello World\")'"
}
EOF
{
  "instance_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "command": "<string>",
  "result": {
    "output": "<string>",
    "exit_code": 123,
    "files_changed": [
      {
        "path": "<string>",
        "status": "created",
        "size": 123,
        "mime_type": "<string>",
        "public_url": "<string>"
      }
    ]
  },
  "status": "success"
}
Executes shell commands within VM instances and returns output with comprehensive file change tracking. This is the core endpoint for running code, scripts, and system commands in your development environments.

​
Request Body

{
  "command": "python -c 'print(\"Hello, World!\")'"
}
The command field accepts any valid shell command that can be executed within the VM environment.

​
Use Cases

  • Code Execution: Run Python scripts, Node.js applications, shell scripts
  • Package Installation: Install dependencies with npm, pip, apt, etc.
  • File Manipulation: Create, edit, and organize files and directories
  • Data Processing: Execute data analysis, transformations, and exports
  • Development Tasks: Build projects, run tests, compile code

​
Response Structure

The response includes detailed information about command execution and any files that were changed:

​
Successful Command Execution

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "command": "python -c 'import matplotlib.pyplot as plt; plt.plot([1,2,3,4]); plt.savefig(\"/tmp/chart.png\")'",
  "result": {
    "output": "",
    "exit_code": 0,
    "files_changed": [
      {
        "path": "/tmp/chart.png",
        "status": "created",
        "size": 12485,
        "mime_type": "image/png",
        "public_url": "/vm/550e8400-e29b-41d4-a716-446655440000/file/tmp/chart.png"
      }
    ]
  },
  "status": "success"
}

​
Command with Output

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000", 
  "command": "ls -la /home/user",
  "result": {
    "output": "total 28\ndrwxr-xr-x 5 user user 4096 Jan  7 10:30 .\ndrwxr-xr-x 3 root root 4096 Jan  7 10:25 ..\n-rw-r--r-- 1 user user  220 Jan  7 10:25 .bash_logout\n-rw-r--r-- 1 user user 3771 Jan  7 10:25 .bashrc\ndrwxr-xr-x 2 user user 4096 Jan  7 10:30 .cache\n-rw-r--r-- 1 user user  807 Jan  7 10:25 .profile",
    "exit_code": 0,
    "files_changed": []
  },
  "status": "success"
}

​
Command Failure

{
  "instance_id": "550e8400-e29b-41d4-a716-446655440000",
  "command": "python nonexistent_script.py", 
  "result": {
    "output": "python: can't open file 'nonexistent_script.py': [Errno 2] No such file or directory",
    "exit_code": 2,
    "files_changed": []
  },
  "status": "error"
}

​
File Change Tracking

The API automatically tracks file changes during command execution:

​
File Change Types

  • created - New files that were created
  • modified - Existing files that were changed
  • deleted - Files that were removed

​
File Metadata

  • path: Full path to the changed file
  • size: File size in bytes
  • mime_type: Detected MIME type (e.g., image/png, text/plain)
  • public_url: Direct URL to access the file without authentication

​
Long-running Commands

Commands have reasonable timeout limits, but for very long-running processes:
  • Use background processes with nohup or screen
  • Break large tasks into smaller steps
  • Consider using interim file outputs to track progress

​
Example Commands

​
Python Data Analysis

python -c "
import pandas as pd
import matplotlib.pyplot as plt

# Create sample data  
data = {'x': [1,2,3,4,5], 'y': [2,4,6,8,10]}
df = pd.DataFrame(data)

# Create visualization
plt.figure(figsize=(8,6))
plt.plot(df['x'], df['y'], 'o-')
plt.title('Sample Data')
plt.savefig('/tmp/analysis.png')
print('Analysis complete!')
"

​
Node.js Package Installation

npm init -y && npm install express

​
Git Operations

git clone https://github.com/user/repo.git && cd repo && npm install

​
File Processing

echo "Processing data..." && cat data.csv | tail -n +2 | cut -d',' -f1,3 > processed.csv

​
Error Handling

Always check the exit_code and status fields:
  • exit_code: 0 and status: "success" - Command executed successfully
  • exit_code: non-zero and status: "error" - Command failed
  • Check the output field for error messages and debugging information

​
Best Practices

  • Command Composition: Chain multiple commands with && for conditional execution
  • Output Redirection: Use > and >> to capture output to files
  • Error Handling: Check exit codes before proceeding with dependent operations
  • Resource Management: Be mindful of CPU and memory usage for intensive operations
  • File Organization: Use descriptive paths and organize outputs in logical directories

Authorizations

​
Authorization
string
header
required

API key authentication using Bearer token format: 'Bearer rk_live_'

Path Parameters

​
profile_id
string<uuid>
required

UUID of the profile

​
room_id
string
required

Room identifier

Body

application/json
​
command
string
required

Shell command to execute

Example:

"python -c 'print(\"Hello World\")'"

Response

Command executed successfully

​
instance_id
string<uuid>
required

Instance where command was executed

​
command
string
required

The command that was executed

​
result
object
required
​
status
enum<string>
required

Command execution status

Available options:
success,
error