Manage PTY Sessions

List sessions

GET /v1/agents/runtime/{runtime_id}/pty Returns every PTY session belonging to the runtime, including sessions that have exited but not yet been reaped.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"

for session in sandbox.pty.list():
    print(session.session_id, session.status, session.pid, session.shell)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"

for (const session of await sandbox.pty.list()) {
  console.log(session.sessionId, session.status, session.pid, session.shell);
}

await sandbox.kill();

gravixlayer runtime pty ls "$RT"

curl "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Responds with {"sessions": [PtySession, ...]}.

Describe a session

GET /v1/agents/runtime/{runtime_id}/pty/{session_id}

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
session = sandbox.pty.create()

info = sandbox.pty.get(session.session_id)
print(info.status, info.exit_code, info.cols, info.rows)

sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
const session = await sandbox.pty.create();

const info = await sandbox.pty.get(session.sessionId);
console.log(info.status, info.exitCode, info.cols, info.rows);

await sandbox.kill();

gravixlayer runtime pty get "$RT" "$SID"

curl "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Returns a PtySession. Poll this when you want to know whether a session has exited without holding a stream open.

Resize

POST /v1/agents/runtime/{runtime_id}/pty/{session_id}/resize Changes the terminal geometry and delivers SIGWINCH to the foreground job, so full screen programs redraw at the new size.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
session = sandbox.pty.create()

sandbox.pty.resize(session.session_id, cols=200, rows=50)
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
const session = await sandbox.pty.create();

await sandbox.pty.resize(session.sessionId, 200, 50);
await sandbox.kill();

gravixlayer runtime pty resize "$RT" "$SID" --cols 200 --rows 50

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID/resize" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cols": 200, "rows": 50}'

Parameter	Type	Required	Description
`cols`	integer	Yes	Terminal width in columns; must be positive
`rows`	integer	Yes	Terminal height in rows; must be positive

Send a signal

POST /v1/agents/runtime/{runtime_id}/pty/{session_id}/signal Signals the session’s process directly.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
session = sandbox.pty.create()

sandbox.pty.send_signal(session.session_id, "INT")
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
const session = await sandbox.pty.create();

await sandbox.pty.sendSignal(session.sessionId, 'INT');
await sandbox.kill();

gravixlayer runtime pty signal "$RT" "$SID" INT

curl -X POST "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID/signal" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"signal": "INT"}'

Signal	Effect
`INT`	Interrupt, as Ctrl-C would
`TERM`	Polite termination request
`KILL`	Immediate, uncatchable termination
`HUP`	Hangup, as a disconnected terminal would deliver

Names are accepted with or without the SIG prefix. Only these four signals are permitted.

Writing \x03 with send input goes through the terminal’s line discipline and interrupts the foreground job, leaving the shell running. This endpoint signals the session process itself. Use input for Ctrl-C semantics and this endpoint when you want to act on the session regardless of what is running in it.

Kill a session

DELETE /v1/agents/runtime/{runtime_id}/pty/{session_id} Terminates the session and releases its terminal, scrollback buffer and slot in the per-runtime session limit.

from gravixlayer import GravixLayer

client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"
sandbox = client.runtime.create()  # defaults to template="base-small"
session = sandbox.pty.create()

sandbox.pty.kill(session.session_id)
sandbox.kill()

import { GravixLayer } from 'gravixlayer';

const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"
const sandbox = await client.runtime.create(); // defaults to template="base-small"
const session = await sandbox.pty.create();

await sandbox.pty.kill(session.sessionId);
await sandbox.kill();

gravixlayer runtime pty kill "$RT" "$SID"

curl -X DELETE "https://api.gravixlayer.ai/v1/agents/runtime/$RT/pty/$SID" \
  -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"

Sessions are also killed automatically when the runtime is stopped or deleted, so you do not need to clean up before tearing a runtime down. Kill sessions explicitly when a runtime is long lived and you are creating a session per task.

Getting Started

Runtime

Support

List sessions

Describe a session

Resize

Send a signal

Kill a session

​List sessions

​Describe a session

​Resize

​Send a signal

​Kill a session

List sessions

Describe a session

Resize

Send a signal

Kill a session