curl --request POST \
--url http://127.0.0.1:{port}/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"folder": "/home/me/repo",
"name": "reviewer",
"command": [
"claude"
]
}
'{
"session": {
"id": "<string>",
"name": "<string>",
"folder": "<string>",
"cwd": "<string>",
"status": "live",
"lifecycle": "working",
"created_by": {
"kind": "user",
"id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"last_active_at": "2023-11-07T05:31:56Z",
"project": "<string>",
"exit_code": 123,
"agent": {
"kind": "claude",
"session_id": "<string>"
},
"reported": {
"at": "2023-11-07T05:31:56Z",
"state": "working",
"text": "<string>",
"summary": "<string>",
"files": [
"<string>"
]
},
"activity": {
"phase": "working",
"active_subagents": 32,
"updated_at": "2023-11-07T05:31:56Z"
},
"parent_id": "<string>",
"depth": 123,
"children": [
"<string>"
],
"command": [
"<string>"
],
"startup_commands": [
"<string>"
],
"resume_command": [
"<string>"
],
"pinned": true,
"git": {
"repo_root": "<string>",
"branch": "<string>",
"detached_at": "<string>",
"worktree": "<string>",
"repo": "<string>"
},
"description": "<string>",
"notes": "<string>",
"labels": {},
"private": true,
"is_self": true,
"auto_named": true,
"terminal": {
"cols": 123,
"rows": 123,
"pid": 123,
"foreground_process": "<string>",
"title": "<string>",
"controlled": true,
"alternate_screen": true
}
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}sessions
Create a session (a terminal in a folder).
POST
/
v1
/
sessions
curl --request POST \
--url http://127.0.0.1:{port}/v1/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"folder": "/home/me/repo",
"name": "reviewer",
"command": [
"claude"
]
}
'{
"session": {
"id": "<string>",
"name": "<string>",
"folder": "<string>",
"cwd": "<string>",
"status": "live",
"lifecycle": "working",
"created_by": {
"kind": "user",
"id": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"last_active_at": "2023-11-07T05:31:56Z",
"project": "<string>",
"exit_code": 123,
"agent": {
"kind": "claude",
"session_id": "<string>"
},
"reported": {
"at": "2023-11-07T05:31:56Z",
"state": "working",
"text": "<string>",
"summary": "<string>",
"files": [
"<string>"
]
},
"activity": {
"phase": "working",
"active_subagents": 32,
"updated_at": "2023-11-07T05:31:56Z"
},
"parent_id": "<string>",
"depth": 123,
"children": [
"<string>"
],
"command": [
"<string>"
],
"startup_commands": [
"<string>"
],
"resume_command": [
"<string>"
],
"pinned": true,
"git": {
"repo_root": "<string>",
"branch": "<string>",
"detached_at": "<string>",
"worktree": "<string>",
"repo": "<string>"
},
"description": "<string>",
"notes": "<string>",
"labels": {},
"private": true,
"is_self": true,
"auto_named": true,
"terminal": {
"cols": 123,
"rows": 123,
"pid": 123,
"foreground_process": "<string>",
"title": "<string>",
"controlled": true,
"alternate_screen": true
}
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}{
"error": {
"code": "not_found",
"message": "<string>",
"details": "<unknown>"
}
}Authorizations
The token from api.json on the loopback listener; the remote token from remote.json (rakumux remote token) on the remote listener.
Headers
Act as this session (with X-Rakumux-Session-Token).
The session's RAKUMUX_SESSION_TOKEN.
Act for the session that bound this agent's conversation (with X-Rakumux-Agent-Conversation), e.g. opencode. Not with the session headers.
Pattern:
^[a-z0-9_-]{1,32}$The agent's conversation id, e.g. OpenCode's ses_….
Body
application/json
Directory (absolute; ~/ expanded) or name of a known folder. Required for user callers; session callers may omit it (their own folder) and may not name another one (403 out_of_scope).
Deprecated alias of folder. With both, they must name the same folder (400 otherwise).
Omitted → generated. Unique within the folder.
Start directory
argv instead of the user's login shell, e.g. ["claude"].
Minimum array length:
1Typed into the shell after it starts.
0 or omitted → default.
Required range:
0 <= x <= 655350 or omitted → default.
Required range:
0 <= x <= 65535Response
Created and running.
Show child attributes
Show child attributes