API: Terminal

Halo HTTP API for terminal sessions: create a session, send input, resize it, read back its output and close it again.

These are the terminal sessions shown in Halo, which a user can watch and type into: create one, send input, resize it, read back its output and close it. Live output streams over the WebSocket. The terminal is available on macOS and Windows only; on Linux every terminal operation answers 403.

Paths are relative to your Halo base URL, and every request carries the access password. Set $HALO_URL and $HALO_TOKEN as in the quickstart; base URL, authentication and error conventions are in the HTTP API overview.

Operation	Endpoint
Open a terminal session	POST /api/terminal/create
Send keystrokes to a terminal session	POST /api/terminal/input
Close a terminal session	POST /api/terminal/kill
List open terminal sessions	GET /api/terminal/list
Read back a terminal session buffer	POST /api/terminal/replay
Resize a terminal session	POST /api/terminal/resize

Open a terminal session

POST /api/terminal/create

• Opens a session with the platform's default shell in the workspace's working folder. Optional body fields: cwd (start folder) and title. The shell itself cannot be chosen.
• Live output arrives over the WebSocket as terminal:data events.

Request body

{
  "spaceId": "<spaceId>"
}

Response

{success:true,data:{id,title,shell,cwd,cols,rows,owner:"user",state:"running",…}} | {success:false,error}

Example

curl -sX POST "$HALO_URL/api/terminal/create" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>"}'

Send keystrokes to a terminal session

POST /api/terminal/input

• Writes raw keystrokes to the session; \r is Enter. Returns as soon as the input is written, before the command has produced output. Read the output from terminal:data events or POST /api/terminal/replay.
• The WebSocket message terminal-input does the same without an HTTP round trip per keystroke.

Request body

{
  "sessionId": "<sessionId>",
  "data": "ls\r"
}

Response

{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}

Example

curl -sX POST "$HALO_URL/api/terminal/input" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","data":"ls\r"}'

Close a terminal session

POST /api/terminal/kill

• Ends the shell process; anything still running in it stops. TERMINAL_NOT_FOUND means the session is already gone.

Request body

{
  "sessionId": "<sessionId>"
}

Response

{success:true} | {success:false,error:"No such terminal session",code:"TERMINAL_NOT_FOUND"}

Example

curl -sX POST "$HALO_URL/api/terminal/kill" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'

List open terminal sessions

GET /api/terminal/list

• Lists the terminal sessions on this computer, including the ones Halo's assistant opened (owner: "ai"). aiTouched turns true once the assistant has used a session.

Response

{success:true,data:[{id,title,shell,cwd,cols,rows,owner:"ai"|"user",aiTouched,state:"running"|"exited",exitCode,lastActivityAt,createdAt,spaceId?}]}

Example

curl -s "$HALO_URL/api/terminal/list" \
  -H "Authorization: Bearer $HALO_TOKEN"

Read back a terminal session buffer

POST /api/terminal/replay

• Returns the session's info and its buffered output as raw terminal data, ANSI escape codes included, so a terminal view can redraw itself after connecting.

Request body

{
  "sessionId": "<sessionId>"
}

Response

{success:true,data:{info:{id,title,…},data:"<buffered output>"}} | {success:false,error,code:"TERMINAL_NOT_FOUND"}

Example

curl -sX POST "$HALO_URL/api/terminal/replay" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>"}'

Resize a terminal session

POST /api/terminal/resize

• cols and rows must be positive integers.

Request body

{
  "sessionId": "<sessionId>",
  "cols": 120,
  "rows": 32
}

Response

{success:true} | {success:false,error,code?:"TERMINAL_NOT_FOUND"}

Example

curl -sX POST "$HALO_URL/api/terminal/resize" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"<sessionId>","cols":120,"rows":32}'