Skip to main content

​
GET /api/machines

List all online machines in the authenticated user’s namespace. Authentication: Required

​
Response

​
machines
array
Array of machine objects

​
Example

curl -H "Authorization: Bearer <token>" \
  http://127.0.0.1:3006/api/machines

{
  "machines": [
    {
      "id": "machine_abc123",
      "namespace": "default",
      "metadata": {
        "hostname": "laptop",
        "platform": "darwin",
        "version": "1.0.0"
      },
      "lastSeen": 1709856000000
    }
  ]
}

​
Errors

  • 503 - Hub not connected

​
POST /api/machines/:id/spawn

Spawn a new session on a specific machine. Authentication: Required

​
Path Parameters

​
id
string
required
Machine ID

​
Request Body

​
directory
string
required
Working directory path for the new session
​
agent
string
Agent type: claude, codex, cursor, gemini, or opencode (default: claude)
​
model
string
Model identifier (agent-specific)
​
yolo
boolean
Start in YOLO mode (bypass permissions)
​
sessionType
string
Session type: simple or worktree
​
worktreeName
string
Worktree name (required if sessionType is worktree)

​
Response

​
success
boolean
Whether spawn succeeded
​
sessionId
string
ID of the newly spawned session
​
error
string
Error message if spawn failed

​
Example: Spawn Claude Session

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "/home/user/myproject",
    "agent": "claude"
  }' \
  http://127.0.0.1:3006/api/machines/machine_abc123/spawn

{
  "success": true,
  "sessionId": "session_xyz789"
}

​
Example: Spawn with YOLO Mode

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "/home/user/myproject",
    "agent": "codex",
    "yolo": true
  }' \
  http://127.0.0.1:3006/api/machines/machine_abc123/spawn

​
Example: Spawn Worktree Session

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "directory": "/home/user/myproject",
    "sessionType": "worktree",
    "worktreeName": "feature-auth"
  }' \
  http://127.0.0.1:3006/api/machines/machine_abc123/spawn

​
Errors

  • 400 - Invalid body
  • 403 - Access denied (machine belongs to different namespace)
  • 404 - Machine not found
  • 503 - Hub not connected

​
POST /api/machines/:id/paths/exists

Check if multiple paths exist on a machine. Authentication: Required

​
Path Parameters

​
id
string
required
Machine ID

​
Request Body

​
paths
array
required
Array of paths to check (max 1000)

​
Response

​
exists
object
Object mapping each path to a boolean indicating existence

​
Example

curl -X POST -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "paths": [
      "/home/user/project1",
      "/home/user/project2",
      "/home/user/project3"
    ]
  }' \
  http://127.0.0.1:3006/api/machines/machine_abc123/paths/exists

{
  "exists": {
    "/home/user/project1": true,
    "/home/user/project2": false,
    "/home/user/project3": true
  }
}

​
Errors

  • 400 - Invalid body (empty or too many paths)
  • 403 - Access denied
  • 404 - Machine not found
  • 500 - Failed to check paths
  • 503 - Hub not connected

​
Use Cases

  • Validate directory before spawning a session
  • Check multiple projects to show which are available
  • Detect moved/deleted directories

Build docs developers (and LLMs) love

Get started for freeTalk to us