`maqpna session start`

Start a session of an agent, optionally waiting for it or attaching to it

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]

Description#

From the help of maqpna session:

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.

Flags#

Flag	Type	Description	Default
`--agent`	string	Agent name (required)	none
`--attach`	switch	wait until Running, then follow the agent's logs	none
`--dry-run`	switch	print the AgentSession without creating it	none
`--env`	string	extra agent environment KEY=VALUE (repeatable)	none
`--group`	string	on-behalf-of user group (repeatable; spec.userGroups)	none
`-n`, `--namespace`	string	namespace	`default`
`--name`	string	session name (default: <agent>-<random>)	none
`--scope`	string	requested scope (repeatable; default: all agent scopes)	none
`--task`	string	task / prompt handed to the agent	none
`--task-file`	string	read the task from FILE (- for stdin)	none
`--timeout`	duration	how long `--wait`/--attach waits	`5m0s`
`--ttl`	duration	session lifetime (clamped by the tier and agent)	none
`--user`	string	on-behalf-of user (default: your Kubernetes user name)	none
`--user-assertion-ref`	string	SECRET/KEY holding an OIDC ID token of the user	none
`--wait`	switch	wait until the session is Running	none

The global flags (--context, -o, --no-color, ...) work with every command.

Examples#

$ maqpna session start --agent coder -n team-a --task "fix the failing test" --wait

What happens when you run it#

--dry-run: print the AgentSession without creating it.
--wait: wait until the session is Running.
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 start --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 start