The Terminal: Command Execution API lets you run shell commands inside an existing terminal session, poll for their results, abort in-flight executions, and send raw keystroke input to a session’s PTY. Use these endpoints to automate CLI workflows, drive interactive prompts, or orchestrate remote SSH commands from a backend or agent.

Execute a command

Note

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.

POST /api/v1/terminal/execute

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. WARNING: 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.
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

Field	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
}

Response

200

{
  "command_id": "42",
  "status": "running"
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Invalid parameter"
}

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": "Cannot create requested working directory"
}

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": "Request method is not POST"
}

500

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

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

SDK Example

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

Get command result

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

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

Parameters

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

Response

200

{
  "command_id": "42",
  "status": "completed",
  "output": "total 12\ndrwxr-xr-x 3 user user 4096 Jan 15 10:30 .\ndrwxr-xr-x 5 user user 4096 Jan 15 10:29 ..",
  "exit_code": 0
}

404

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "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 Example

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

Abort a running command

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.

Caution

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.

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

Parameters

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

Request Body

Field	Type	Required	Description
force	boolean	No	Send SIGKILL to process group instead of SIGINT. Default: false.

{
  "force": false
}

Response

{
  "command_id": "42",
  "status": "aborted",
  "output": "partial output captured before abort",
  "exit_code": null
}

SDK Example

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

Write input to terminal

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.

POST /api/v1/terminal/write

Parameters

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

Request Body

Field	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": "y",
  "enter": true
}

Response

200

{
  "status": "ok",
  "bytes_written": 2
}

400

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Missing required field"
}

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": "Terminal 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": "Request method is not POST"
}

409

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "No running process in session"
}

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"
}

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

SDK Example

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