Terminal: Command Execution

The terminal command execution API runs shell commands inside local bash or remote SSH sessions, polls for results, sends interactive keyboard input, and aborts running commands. Use these endpoints to build programmatic command-execution flows (CI runners, ops bots, child_process-style integrations) on top of Hoody’s persistent PTY sessions.

POST /api/v1/terminal/execute

Execute a command in the specified terminal session. Supports both local bash and remote SSH sessions. The terminal type is determined by URL parameters on first use. By default, if a DISPLAY is configured on the session, the endpoint waits for the Hoody Display to be ready before executing the command. This can be disabled with skip_display_wait=true. Use ephemeral=true for a guaranteed-unique isolated PTY session with no display/dbus and automatic cleanup — ideal for programmatic command execution (like child_process.exec). Returns immediately with a command_id that can be used to poll for results.

Caution

Do not use ephemeral=true for GUI applications that require a display. Ephemeral sessions strip the DISPLAY environment variable, which means X11/GUI applications will not work. Use a regular terminal session with an explicit terminal_id and display parameter instead for GUI workloads.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	No	Terminal session ID (numeric 1-65535). Use terminal_id=0 as an explicit sentinel meaning “no terminal ID” (treated as absent, useful when a reverse proxy always injects a terminal_id). Required unless ephemeral=true, in which case it is auto-generated if not provided
ephemeral	query	boolean	No	When true, auto-generates a unique terminal_id (if not provided), skips display/dbus initialization, and applies aggressive cleanup. Designed for programmatic CLI command execution like child_process.exec (default: false)
defer_pid	query	integer	No	Defer command injection until this PID exits (TUI-safe). If set, the API returns immediately regardless of wait=true
defer_start_time_ticks	query	string	No	Optional /proc/<pid>/stat field 22 (starttime in clock ticks since boot) to avoid PID reuse bugs. If it mismatches, command executes immediately
defer_timeout_ms	query	integer	No	Max time to wait for defer_pid exit before failing (default: 60000)
defer_poll_ms	query	integer	No	Poll interval while waiting for defer_pid exit (default: 50, minimum: 10)
reset	query	boolean	No	Reset existing session and reconfigure (kills current process, clears state, allows switching from bash to SSH or changing any parameter) — Use 'true', '1', or no value
cwd	query	string	No	Working directory for local bash sessions (ignored for SSH)
cwd_auto_create	query	boolean	No	Auto-create cwd when the requested working directory does not exist yet. Only applies when cwd is explicitly provided for a new or reset local session. Enable with 'true', '1', or no value (default: false)
shell	query	string	No	Shell to use for local sessions: bash (case-insensitive), zsh, fish, sh, etc. (default: server startup command, only applies to new sessions or after reset)
user	query	string	No	System user to spawn shell as (requires su permissions, only applies to new sessions or after reset)
cmd	query	string	No	Base64-encoded command to execute automatically (works with both new and active shells, executes every time URL is visited)
env	query	string	No	Environment variable in KEY=VALUE format (can be repeated for multiple variables, e.g., ?env=DEBUG=1&env=API_KEY=abc)
skip_display_wait	query	boolean	No	Skip waiting for Hoody Display readiness before executing command. By default, if a DISPLAY is configured, the endpoint blocks until the display server on port 4000+display_num is ready (default: false)
display_wait_timeout	query	integer	No	Timeout in seconds for display readiness wait (default: 10, capped at 10 seconds to prevent event-loop pin; values ≤0 or malformed also map to the 10-second cap). Ignored if skip_display_wait=true
display	query	string	No	DISPLAY environment variable for X11 applications (auto-formats :display if number provided, e.g., ?display=1 becomes DISPLAY=:1)
ssh_host	query	string	No	SSH server hostname or IP address (creates SSH session if provided with ssh_user)
ssh_user	query	string	No	SSH username (required if ssh_host is provided)
ssh_port	query	string	No	SSH port number (default: 22)
ssh_password	query	string	No	SSH password for authentication (use with caution, prefer key-based auth)
socks5_host	query	string	No	SOCKS5 proxy hostname for SSH connection
socks5_port	query	string	No	SOCKS5 proxy port (default: 1080)
socks5_user	query	string	No	SOCKS5 proxy username for authentication
ssh_key	query	string	No	Base64-encoded SSH private key for key-based authentication (prefer over password-based auth)
socks5_pass	query	string	No	SOCKS5 proxy password for authentication

Request Body

Name	Type	Required	Description
command	string	Yes	The command to execute
id	string	No	Custom command ID (numeric 1-65535, auto-generated if not provided)
timeout	integer	No	Timeout in seconds (0 = no timeout, default: 0)
wait	boolean	No	Whether to wait for completion (default: true; forced false when defer_pid is set)
cwd	string	No	Working directory for command execution (for local bash only)
env	object	No	Environment variables as key-value pairs

{
  "command": "ls -la",
  "timeout": 30,
  "wait": true
}

Responses

200

Command started successfully.

{
  "command_id": 42,
  "status": "running",
  "terminal_id": 1,
  "started_at": "2025-01-15T10:30:45Z"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid or missing parameters",
  "code": "VALIDATION_ERROR"
}

Error Code	Title	Description	Resolution
VALIDATION_ERROR	Invalid or missing parameters	Check parameter format and retry	Check parameter format and retry
INVALID_TERMINAL_ID	Terminal ID must be numeric (1-65535)	Provide valid terminal_id	Provide valid terminal_id

403

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Requested working directory could not be created",
  "code": "CWD_PERMISSION_DENIED"
}

Error Code	Title	Description	Resolution
CWD_PERMISSION_DENIED	Requested working directory could not be created	Choose a writable path or disable cwd_auto_create	Choose a writable path or disable cwd_auto_create

405

{
  "statusCode": 405,
  "error": "Method Not Allowed",
  "message": "POST method required"
}

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Command execution failed",
  "code": "EXECUTION_FAILED"
}

Error Code	Title	Description	Resolution
EXECUTION_FAILED	Command execution failed	Check terminal session status	Check terminal session status

SDK usage

const result = await client.terminal.execution.execute({
  terminal_id: "1",
  data: {
    command: "ls -la",
    timeout: 30,
    wait: true
  }
});

GET /api/v1/terminal/result/{command_id}

Retrieve the current or final results of a command execution. Can be called while command is running or after completion.

Parameters

Name	In	Type	Required	Description
command_id	path	string	Yes	Command ID returned from /api/v1/terminal/execute (numeric 1-65535)

This endpoint takes no request body.

Responses

200

Command results (running or completed).

{
  "command_id": 42,
  "status": "completed",
  "exit_code": 0,
  "stdout": "total 48\ndrwxr-xr-x 6 user user 4096 Jan 15 10:30 .\n",
  "stderr": "",
  "duration_ms": 234
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Command 42 not found",
  "code": "COMMAND_NOT_FOUND"
}

Error Code	Title	Description	Resolution
COMMAND_NOT_FOUND	Command ID does not exist	Verify command_id from execute response	Verify command_id from execute response

SDK usage

const result = await client.terminal.execution.getResult({ command_id: "42" });

POST /api/v1/terminal/write

Send keyboard input to a terminal session’s PTY. The input is written directly to the PTY master fd, exactly as if typed on a physical keyboard. By default, Enter (newline) is automatically appended after the input. Set enter=false for raw input without Enter. Supports interactive prompts (y/n), sudo passwords, and any other stdin input. Use empty input "" to just press Enter.

Parameters

Name	In	Type	Required	Description
terminal_id	query	string	Yes	Terminal session ID to write to

Request Body

Name	Type	Required	Description
input	string	Yes	The text to type into the terminal
enter	boolean	No	Auto-append Enter (newline) after input. Default: true. Set to false for raw keystroke input

{
  "input": "yes",
  "enter": true
}

Responses

200

Input written successfully.

{
  "success": true,
  "terminal_id": 1,
  "bytes_written": 4
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "terminal_id query parameter is required",
  "code": "MISSING_TERMINAL_ID"
}

Error Code	Title	Description	Resolution
MISSING_TERMINAL_ID	terminal_id query parameter is required	terminal_id query parameter is required	Contact support
MISSING_INPUT	input field is required in request body	input field is required in request body	Contact support

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "No terminal session with the given ID",
  "code": "SESSION_NOT_FOUND"
}

Error Code	Title	Description	Resolution
SESSION_NOT_FOUND	No terminal session with the given ID	No terminal session with the given ID	Contact support

405

{
  "statusCode": 405,
  "error": "Method Not Allowed",
  "message": "POST method required"
}

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Terminal session has no running process to write to",
  "code": "NO_PROCESS"
}

Error Code	Title	Description	Resolution
NO_PROCESS	Terminal session has no running process to write to	Terminal session has no running process to write to	Contact support

500

{
  "statusCode": 500,
  "error": "Internal Server Error",
  "message": "Failed to write input to PTY",
  "code": "WRITE_FAILED"
}

Error Code	Title	Description	Resolution
WRITE_FAILED	Failed to write input to PTY	Failed to write input to PTY	Contact support

SDK usage

const result = await client.terminal.terminal.write({
  terminal_id: "1",
  data: {
    input: "yes",
    enter: true
  }
});

POST /api/v1/terminal/execute/{command_id}/abort

Cancel a command that was started via the execute endpoint. Graceful mode (default) sends SIGINT via the PTY (equivalent to Ctrl+C). Force mode sends SIGKILL to the process group. Partial output captured before abort is preserved in the response. Idempotent: aborting an already-completed command returns 409 with the existing result. Known limitation: graceful abort may not stop processes that trap SIGINT — use force=true for those.

Note

Graceful abort is the default and is equivalent to pressing Ctrl+C in an interactive terminal. Set force=true to send SIGKILL to the entire process group when a command is trapping SIGINT.

Parameters

Name	In	Type	Required	Description
command_id	path	string	Yes	The command ID returned by the execute endpoint

Request Body

Name	Type	Required	Description
force	boolean	No	Send SIGKILL to process group instead of SIGINT (default: false)

{
  "force": false
}

Responses

200

Command aborted successfully.

{
  "command_id": 42,
  "status": "aborted",
  "partial_output": "downloading... 45%"
}

SDK usage

const result = await client.terminal.terminal.abort({
  command_id: "42",
  data: {
    force: false
  }
});