run
Start a command in the background without blocking the calling agent, returning a job_id for immediate admission or queueing and a rejection when capacity is full.
Instructions
Start a command in the background without blocking the calling agent - never blocks on capacity either: this call always returns synchronously, in one of three shapes. If a concurrency slot is free, the command starts immediately and a job_id comes back for a job that is already running. If the concurrency cap is full but the queue has room, no process starts yet: a job_id still comes back, but the job sits in the existing "starting" state with a queue_position field showing its place in line, and the real spawn happens automatically once an earlier job frees a slot - poll status on that id to see it transition once it actually starts. If both the cap and the queue are full, the call returns isError: true with a rejected: true structured result and no job_id at all - nothing was created to track. Concurrency is configured via the GHANTIKA_MAX_CONCURRENT_JOBS (default 8) and GHANTIKA_MAX_QUEUE_DEPTH (default 32) environment variables; setting either to 0 disables that capacity outright (a cap of 0 rejects every command immediately, a queue depth of 0 means nothing is ever queued - only admitted or rejected). Once a job_id comes back in any of the first two shapes, use that id with status to check whether the job is still queued, running, or finished, output to read its lines from a cursor, and tail to read just the last N. command is an argv array by default (never shell-interpreted) - pass shell: true to run a real shell command line instead. The resolved command (or, with shell: true, the platform shell itself) must be on the operator's configured allowlist; anything else settles as a failed job rather than running.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | Working directory to run the command in. Must already exist and be a directory - an invalid cwd fails the job (state: failed) rather than silently falling back to the server's own working directory. Defaults to the server's own working directory when omitted. | |
| env | No | Controls the child's environment. mode 'merge' (default) layers vars over a minimal base environment (PATH, HOME, and on Windows SystemRoot/USERPROFILE) - never the server's full environment. mode 'replace' uses ONLY vars, with no base at all. | |
| label | No | An optional human-readable label for this job. At most 64 characters, no control characters. | |
| shell | No | Opt-in escape hatch: when true, command is interpreted as a shell command line instead of a literal argv array. Defaults to false - a bare shell string is rejected unless this is explicitly true. | |
| command | Yes | The command to run. By default (shell omitted or false): an argv array, e.g. ["ls", "-la"] - the first element is the program, the rest are its literal arguments, never shell-interpreted. With shell: true: a shell command line, either as a single string or as an array of tokens joined with spaces, interpreted by the platform shell (enabling pipes, redirection, globbing). | |
| deadline_ms | No | Optional deadline in milliseconds, measured from when this job starts. If the job is still running once the deadline elapses, it is terminated through the same process-group kill machinery the kill tool uses, and its state becomes failed (never a new status) - see the diagnostic message for confirmation this is what happened. The deadline transition itself never deletes the record; ordinary task TTL can still purge that terminal record later, on a subsequent read, exactly as it would for any other terminal job. Omitted (the default): no deadline at all, and the job runs to its own natural completion exactly as it always has. Must not exceed 2147483647 (Node's own maximum timer delay) - a larger value is rejected outright rather than silently clamped to a near-immediate deadline. |