`maqpna session`

Start, inspect, control and observe sessions

Run agents-o json | yamlalias: sessions

Synopsis#

maqpna session start --agent A [-n NS] [--user U] [--task TEXT | --task-file F] [--scope S]... [--ttl 1h] [--name N] [--env K=V]... [--wait | --attach] [--timeout 5m] [--dry-run]
maqpna session list [-n NS | -A] [--agent A] [--phase P] [--user U]
maqpna session get S [-n NS]
maqpna session describe S [-n NS] [--gateway URL]
maqpna session wait S [-n NS] [--for phase=Running|condition=Ready|terminal|delete] [--timeout 5m]
maqpna session suspend|resume S [-n NS] [--wait]
maqpna session fork S [-n NS] [--name N] [--count N] [--from-snapshot SNAP] [--wait]
maqpna session snapshot S [-n NS] [--name N] [--strategy Auto|SandboxSnapshot|VolumeSnapshot] [--wait]
maqpna session delete S... [-n NS] [--terminate-now --reason TEXT] [--wait] [--yes]
maqpna session cost S [--gateway URL]
maqpna session exec S [-n NS] [--language sh] [--timeout 60s] [--workdir DIR] -- COMMAND...
maqpna session files S [PATH] [-n NS] [--out FILE]
maqpna session liveview S [-n NS] [--open]

Description#

Sessions are AgentSession objects: start creates one, the operator provisions its sandbox and token. describe merges the object, its sandbox and pods with the gateway's view (cost, taint, pending approvals). exec, files and liveview go through the gateway session API and are governed and audited like any tool call (scope tools:maqpna-exec, admin role).

exec exits with the remote command's exit code. wait exits 1 on timeout or when the session fails.

Subcommands#

maqpna session startStart a session of an agent, optionally waiting for it or attaching to it maqpna session listList sessions, filtered by namespace, agent, phase or user maqpna session getShow one session object maqpna session describeDescribe a session: its sandbox and pods, cost, taint and pending approvals maqpna session waitWait until a session reaches a phase or condition, ends, or is deleted maqpna session suspendSuspend a running session maqpna session resumeResume a suspended session maqpna session forkFork a session, or start sessions from one of its snapshots maqpna session snapshotTake a snapshot of a session's sandbox maqpna session deleteDelete sessions, optionally terminating them at once with a revocation maqpna session costShow what a session has spent, from the gateway maqpna session execRun a command in a session's sandbox through the gateway (governed and audited) maqpna session filesList a session's files, or download one, through the gateway maqpna session liveviewGet a short-lived live-view link to a session's sandbox, or open it with --open

Examples#

$ maqpna session start --agent coder -n team-a --task "fix the failing test" --wait
$ maqpna session list -n team-a
$ maqpna session describe fix-test-7k2 -n team-a
$ maqpna session exec fix-test-7k2 -n team-a -- ls /workspace
$ maqpna session delete fix-test-7k2 -n team-a --yes

What happens when you run it#

Prints a table by default; -o json or -o yaml print the data, and --jq EXPR filters the JSON.

Exit codes#

Code	Meaning
`0`	success
`1`	error (the message says what failed, with a hint when there is one)
`2`	usage error: unknown flag, missing argument or bad value; the synopsis is printed
`3`	a check failed, a change is blocked, or a result did not match (tamper, policy mismatch) (not used by this command)

Terminal demo#

maqpna session --help.cast

This command needs a Kubernetes cluster with MAQPNA installed, so the recording shows its help. Try it against a cluster from Install.

maqpna session