Terminal API

Source: daemon/proto/hostcraft/v1/terminal.proto

TerminalService

TerminalService opens interactive shells as an account's Unix user, the gRPC counterpart of the panel's web terminal (GET /ws/terminal).

Method	REST route	Permission	Streaming
GetTerminalStatus	GET /api/v1/terminal/status	TerminalAccess	unary
Attach	native	TerminalAccess	bidirectional

GetTerminalStatus

/hostcraft.v1.TerminalService/GetTerminalStatus

• Request: GetTerminalStatusRequest
• Response: TerminalStatus

Attach

Attach is a bidirectional shell. The first client message must be open; then data (stdin bytes) and resize. The server replies ready, then data (terminal output) and finally exit. Sessions are subject to the same idle timeout, lifetime and per-account limits as the web terminal, and are audited (terminal.session.open/close).

/hostcraft.v1.TerminalService/Attach

• Request: TerminalInput
• Response: TerminalOutput

Messages

GetTerminalStatusRequest

Field	Type	Number	Description
account_id	string	1	-

TerminalExit

Field	Type	Number	Description
code	int64	1	-
reason	string	2	shell_exited | client_closed | idle_timeout | max_duration | ...

TerminalInput

Field	Type	Number	Description
open	TerminalOpen	1	-
data	bytes	2	-
resize	TerminalResize	3	-

TerminalOpen

Field	Type	Number	Description
account_id	string	1	defaults to the caller's account
cols	uint32	2	-
rows	uint32	3	-

TerminalOutput

Field	Type	Number	Description
ready	TerminalReady	1	-
data	bytes	2	-
exit	TerminalExit	3	-

TerminalReady

Field	Type	Number	Description
session_id	string	1	-
username	string	2	-
idle_timeout_seconds	int64	3	-
max_duration_seconds	int64	4	-

TerminalResize

Field	Type	Number	Description
cols	uint32	1	-
rows	uint32	2	-

TerminalStatus

Field	Type	Number	Description
available	bool	1	-
reason	string	2	-
idle_timeout_seconds	int64	3	-
max_duration_seconds	int64	4	-
max_per_account	int64	5	-
active	int64	6	-