Sessions
Commands and terminals on the host, their output and input.
| Operation | Kind | HTTP |
|---|---|---|
sessions.start | call | POST /v1/sessions |
sessions.list | call | GET /v1/sessions |
sessions.get | call | GET /v1/sessions/{id} |
sessions.attach | stream | GET /v1/sessions/{id} |
sessions.delete | call | DELETE /v1/sessions/{id} |
sessions.output | call | GET /v1/sessions/{id}/output |
sessions.screen | call | GET /v1/sessions/{id}/screen |
sessions.input | call | POST /v1/sessions/{id}/input |
sessions.resize | call | POST /v1/sessions/{id}/resize |
sessions.signal | call | POST /v1/sessions/{id}/signal |
sessions.start
Start a session.
Host level only. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
wait | query | no | A duration such as 30s, at most 10m: answer when the command has ended, with what it wrote. |
Input
| Field | Type | Description |
|---|---|---|
cols (optional) | integer | null | |
command | CommandLine | A list of arguments, or one string for sh -c. |
cwd (optional) | string | null | |
env (optional) | map of string | |
input (optional) | string | null | Text for standard input; a process then sees the end of its input. |
input_b64 (optional) | string | null | |
kind | SessionKind | |
rows (optional) | integer | null | |
timeout (optional) | integer | null | Seconds after which the command is ended. |
title (optional) | string | null | |
user (optional) | string | agent, operator (the SSH user) or root. |
Result
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
{
"id": 1,
"op": "sessions.start",
"args": {
"wait": "30s"
},
"data": {
"command": [
"uname -a"
],
"kind": "process"
}
}{
"id": 1,
"result": {
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent",
"output_b64": "aGVsbG8K",
"stderr_b64": "aGVsbG8K",
"stdout_b64": "aGVsbG8K",
"truncated": true
}
}sessions.list
All sessions, running and ended.
Host level only. Through rookery serve it needs the role view.
Result
Session[]
{
"id": 1,
"op": "sessions.list"
}{
"id": 1,
"result": [
{
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent"
}
]
}sessions.get
One session's state. The agent sees those it started through an action.
Host and agent level. Through rookery serve it needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
Result
| Field | Type | Description |
|---|---|---|
action (optional) | string | null | The action it was started for, if any. |
cols (optional) | integer | null | |
command | string[] | |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
id | string | |
kind | SessionKind | |
last_output (optional) | string | null | |
lost (optional) | boolean | It ended with rookeryd or the host, not by itself. |
output_size (optional) | integer | |
rows (optional) | integer | null | |
started | string | |
started_by | From | Who did something, as rookeryd saw it. |
steps (optional) | Step[] | |
title | string | |
user | string | |
viewers (optional) | integer |
{
"id": 1,
"op": "sessions.get",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"command": [
"uname -a"
],
"id": "k3v9qz2m8w1x",
"kind": "process",
"started": "2026-11-12T09:30:00Z",
"started_by": {
"level": "host",
"session": "k3v9qz2m8w1x",
"uid": 1001
},
"title": "uname -a",
"user": "agent"
}
}sessions.attach
A session, live: its output as it is produced, and input to it.
Host and agent level. A stream, as a subscription on the portal or a WebSocket of its own. It resumes from since. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
since | query | no | Byte offset to start from. Without it a terminal replays its current screen and a process starts at the beginning. |
Frames from the server
| Frame | Kind | Description |
|---|---|---|
output | binary | Terminal: the terminal's bytes. Process: the first byte is the stream (1 stdout, 2 stderr), the rest its bytes. |
exited | JSON | The command ended. The last frame. Example: {"exited":{"exit_code":0}} |
dropped | JSON | This viewer was too slow and missed output; read it back with the output call. Example: {"dropped":{"bytes":65536}} |
Frames to the server
| Frame | Kind | Description |
|---|---|---|
input | binary | Terminal: bytes typed. Process: first byte 0, the rest goes to standard input. |
resize | JSON | A terminal's new size. Example: {"resize":{"cols":120,"rows":40}} |
signal | JSON | INT, TERM, HUP or KILL to the session's process group. Example: {"signal":"INT"} |
eof | JSON | Close a process's standard input. Example: {"eof":true} |
{
"id": 1,
"op": "sessions.attach",
"args": {
"id": "k3v9qz2m8w1x",
"since": "VALUE"
}
}{
"id": 1,
"result": {
"open": true
}
}
{
"sub": 1,
"data": {
"exited": {
"exit_code": 0
}
}
}
// binary: 00 00 00 01, then the bytesEnd the subscription with {"sub": 1, "end": true}.
sessions.delete
End it if it runs (HUP, after five seconds KILL) and forget it with its transcript.
Host level only. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
{
"id": 1,
"op": "sessions.delete",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"ok": true
}
}sessions.output
The transcript, by bytes or by lines.
Host and agent level. Through rookery serve it needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
stream | query | no | stdout, stderr or merged (default), for a process. |
since | query | no | Byte offset to read from. |
limit | query | no | Most bytes to return; default 1 MB. |
line | query | no | Read lines from this line number (a process only). |
count | query | no | How many lines; default 100. |
tail | query | no | The last so many lines. |
Result
| Field | Type | Description |
|---|---|---|
data_b64 | string | |
ended | boolean | Nothing more will come. |
first_offset (optional) | integer | null | Where what is still kept begins, when the start was dropped. |
lines (optional) | string[] | null | The same as text, when read by lines. |
next_line | integer | |
next_offset | integer | |
offset | integer | The offset this answer starts at. |
{
"id": 1,
"op": "sessions.output",
"args": {
"id": "k3v9qz2m8w1x",
"since": "VALUE"
}
}{
"id": 1,
"result": {
"data_b64": "aGVsbG8K",
"ended": true,
"first_offset": 0,
"lines": [
"text"
],
"next_line": 0,
"next_offset": 0,
"offset": 0
}
}sessions.screen
A terminal as it looks now, as text.
Host and agent level. Through rookery serve it needs the role view.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
format | query | no | text (default) or ansi, which keeps colours. |
tail | query | no | That many lines of screen and scrollback instead. |
Result
| Field | Type | Description |
|---|---|---|
cols | integer | |
cursor_col | integer | |
cursor_row | integer | |
rows | integer | |
text | string |
{
"id": 1,
"op": "sessions.screen",
"args": {
"id": "k3v9qz2m8w1x"
}
}{
"id": 1,
"result": {
"cols": 120,
"cursor_col": 0,
"cursor_row": 0,
"rows": 40,
"text": "hello"
}
}sessions.input
Write to standard input or type into the terminal. Never recorded.
Host level only. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
Input
| Field | Type | Description |
|---|---|---|
data_b64 (optional) | string | null | |
eof (optional) | boolean | Close a process's standard input. |
text (optional) | string | null |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
{
"id": 1,
"op": "sessions.input",
"args": {
"id": "k3v9qz2m8w1x"
},
"data": {
"data_b64": "aGVsbG8K",
"eof": true,
"text": "hello"
}
}{
"id": 1,
"result": {
"ok": true
}
}sessions.resize
Give a terminal a new size.
Host level only. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
Input
| Field | Type | Description |
|---|---|---|
cols | integer | |
rows | integer |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
{
"id": 1,
"op": "sessions.resize",
"args": {
"id": "k3v9qz2m8w1x"
},
"data": {
"cols": 120,
"rows": 40
}
}{
"id": 1,
"result": {
"ok": true
}
}sessions.signal
Send INT, TERM, HUP or KILL to the session's process group.
Host level only. Through rookery serve it needs the role operate.
Arguments
| Name | Where | Required | Description |
|---|---|---|---|
id | path | yes | A session's id, as starting it or the list gives it. |
Input
| Field | Type | Description |
|---|---|---|
signal | string | INT, TERM, HUP or KILL. |
Result
| Field | Type | Description |
|---|---|---|
ok | boolean |
{
"id": 1,
"op": "sessions.signal",
"args": {
"id": "k3v9qz2m8w1x"
},
"data": {
"signal": "TERM"
}
}{
"id": 1,
"result": {
"ok": true
}
}Types
The named types used on this page.
CommandLine
A list of arguments, or one string for sh -c.
A list of arguments, or one string for sh -c.
SessionKind
Started
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
The answer to a start with wait=: the session and, when it has ended in
time, what it wrote.
Session
| Field | Type | Description |
|---|---|---|
action (optional) | string | null | The action it was started for, if any. |
cols (optional) | integer | null | |
command | string[] | |
ended (optional) | string | null | |
exit_code (optional) | integer | null | |
id | string | |
kind | SessionKind | |
last_output (optional) | string | null | |
lost (optional) | boolean | It ended with rookeryd or the host, not by itself. |
output_size (optional) | integer | |
rows (optional) | integer | null | |
started | string | |
started_by | From | Who did something, as rookeryd saw it. |
steps (optional) | Step[] | |
title | string | |
user | string | |
viewers (optional) | integer |
From
Who did something, as rookeryd saw it.
| Field | Type | Description |
|---|---|---|
level | Level | |
session (optional) | string | null | |
uid | integer |
Step
| Field | Type | Description |
|---|---|---|
exit_code (optional) | integer | null | |
name | string | |
user | string |