Skip to Content

Sessions

Commands and terminals on the host, their output and input.

OperationKindHTTP
sessions.startcallPOST /v1/sessions
sessions.listcallGET /v1/sessions
sessions.getcallGET /v1/sessions/{id}
sessions.attachstreamGET /v1/sessions/{id}
sessions.deletecallDELETE /v1/sessions/{id}
sessions.outputcallGET /v1/sessions/{id}/output
sessions.screencallGET /v1/sessions/{id}/screen
sessions.inputcallPOST /v1/sessions/{id}/input
sessions.resizecallPOST /v1/sessions/{id}/resize
sessions.signalcallPOST /v1/sessions/{id}/signal

sessions.start

Start a session.

Host level only. Through rookery serve it needs the role operate.

Arguments

NameWhereRequiredDescription
waitquerynoA duration such as 30s, at most 10m: answer when the command has ended, with what it wrote.

Input

FieldTypeDescription
cols (optional)integer | null
commandCommandLineA list of arguments, or one string for sh -c.
cwd (optional)string | null
env (optional)map of string
input (optional)string | nullText for standard input; a process then sees the end of its input.
input_b64 (optional)string | null
kindSessionKind
rows (optional)integer | null
timeout (optional)integer | nullSeconds after which the command is ended.
title (optional)string | null
user (optional)stringagent, operator (the SSH user) or root.

Result

Started

The answer to a start with wait=: the session and, when it has ended in time, what it wrote.

Request
{
  "id": 1,
  "op": "sessions.start",
  "args": {
    "wait": "30s"
  },
  "data": {
    "command": [
      "uname -a"
    ],
    "kind": "process"
  }
}
Reply
{
  "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[]

Request
{
  "id": 1,
  "op": "sessions.list"
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.

Result

FieldTypeDescription
action (optional)string | nullThe action it was started for, if any.
cols (optional)integer | null
commandstring[]
ended (optional)string | null
exit_code (optional)integer | null
idstring
kindSessionKind
last_output (optional)string | null
lost (optional)booleanIt ended with rookeryd or the host, not by itself.
output_size (optional)integer
rows (optional)integer | null
startedstring
started_byFromWho did something, as rookeryd saw it.
steps (optional)Step[]
titlestring
userstring
viewers (optional)integer
Request
{
  "id": 1,
  "op": "sessions.get",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.
sincequerynoByte offset to start from. Without it a terminal replays its current screen and a process starts at the beginning.

Frames from the server

FrameKindDescription
outputbinaryTerminal: the terminal's bytes. Process: the first byte is the stream (1 stdout, 2 stderr), the rest its bytes.
exitedJSONThe command ended. The last frame. Example: {"exited":{"exit_code":0}}
droppedJSONThis viewer was too slow and missed output; read it back with the output call. Example: {"dropped":{"bytes":65536}}

Frames to the server

FrameKindDescription
inputbinaryTerminal: bytes typed. Process: first byte 0, the rest goes to standard input.
resizeJSONA terminal's new size. Example: {"resize":{"cols":120,"rows":40}}
signalJSONINT, TERM, HUP or KILL to the session's process group. Example: {"signal":"INT"}
eofJSONClose a process's standard input. Example: {"eof":true}
Request
{
  "id": 1,
  "op": "sessions.attach",
  "args": {
    "id": "k3v9qz2m8w1x",
    "since": "VALUE"
  }
}
Reply
{
  "id": 1,
  "result": {
    "open": true
  }
}

{
  "sub": 1,
  "data": {
    "exited": {
      "exit_code": 0
    }
  }
}

// binary: 00 00 00 01, then the bytes

End 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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.

Result

FieldTypeDescription
okboolean
Request
{
  "id": 1,
  "op": "sessions.delete",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.
streamquerynostdout, stderr or merged (default), for a process.
sincequerynoByte offset to read from.
limitquerynoMost bytes to return; default 1 MB.
linequerynoRead lines from this line number (a process only).
countquerynoHow many lines; default 100.
tailquerynoThe last so many lines.

Result

FieldTypeDescription
data_b64string
endedbooleanNothing more will come.
first_offset (optional)integer | nullWhere what is still kept begins, when the start was dropped.
lines (optional)string[] | nullThe same as text, when read by lines.
next_lineinteger
next_offsetinteger
offsetintegerThe offset this answer starts at.
Request
{
  "id": 1,
  "op": "sessions.output",
  "args": {
    "id": "k3v9qz2m8w1x",
    "since": "VALUE"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.
formatquerynotext (default) or ansi, which keeps colours.
tailquerynoThat many lines of screen and scrollback instead.

Result

FieldTypeDescription
colsinteger
cursor_colinteger
cursor_rowinteger
rowsinteger
textstring
Request
{
  "id": 1,
  "op": "sessions.screen",
  "args": {
    "id": "k3v9qz2m8w1x"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.

Input

FieldTypeDescription
data_b64 (optional)string | null
eof (optional)booleanClose a process's standard input.
text (optional)string | null

Result

FieldTypeDescription
okboolean
Request
{
  "id": 1,
  "op": "sessions.input",
  "args": {
    "id": "k3v9qz2m8w1x"
  },
  "data": {
    "data_b64": "aGVsbG8K",
    "eof": true,
    "text": "hello"
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.

Input

FieldTypeDescription
colsinteger
rowsinteger

Result

FieldTypeDescription
okboolean
Request
{
  "id": 1,
  "op": "sessions.resize",
  "args": {
    "id": "k3v9qz2m8w1x"
  },
  "data": {
    "cols": 120,
    "rows": 40
  }
}
Reply
{
  "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

NameWhereRequiredDescription
idpathyesA session's id, as starting it or the list gives it.

Input

FieldTypeDescription
signalstringINT, TERM, HUP or KILL.

Result

FieldTypeDescription
okboolean
Request
{
  "id": 1,
  "op": "sessions.signal",
  "args": {
    "id": "k3v9qz2m8w1x"
  },
  "data": {
    "signal": "TERM"
  }
}
Reply
{
  "id": 1,
  "result": {
    "ok": true
  }
}

Types

The named types used on this page.

CommandLine

A list of arguments, or one string for sh -c.

CommandLine

A list of arguments, or one string for sh -c.

SessionKind

SessionKind

Started

The answer to a start with wait=: the session and, when it has ended in time, what it wrote.

Started

The answer to a start with wait=: the session and, when it has ended in time, what it wrote.

Session

FieldTypeDescription
action (optional)string | nullThe action it was started for, if any.
cols (optional)integer | null
commandstring[]
ended (optional)string | null
exit_code (optional)integer | null
idstring
kindSessionKind
last_output (optional)string | null
lost (optional)booleanIt ended with rookeryd or the host, not by itself.
output_size (optional)integer
rows (optional)integer | null
startedstring
started_byFromWho did something, as rookeryd saw it.
steps (optional)Step[]
titlestring
userstring
viewers (optional)integer

From

Who did something, as rookeryd saw it.

FieldTypeDescription
levelLevel
session (optional)string | null
uidinteger

Step

FieldTypeDescription
exit_code (optional)integer | null
namestring
userstring

Level

Level

On this page