Skip to main content
Glama

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

NameRequiredDescriptionDefault
cwdNoWorking 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.
envNoControls 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.
labelNoAn optional human-readable label for this job. At most 64 characters, no control characters.
shellNoOpt-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.
commandYesThe 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_msNoOptional 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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and delivers: three distinct return shapes, the queued-vs-running distinction, the isError/rejected shape with no job_id, and the allowlist precondition that makes an unlisted command settle as a failed job. It also discloses the deadline kill path and that terminal state becomes failed, which are non-obvious side effects an agent must know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The critical behavior (non-blocking, always synchronous) is front-loaded, and the three outcomes follow in a logical sequence. It is dense and long, with some repetition of the queued-state explanation, but nearly every sentence adds actionable detail rather than restating the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 6-parameter tool with a nested env object, conditional command shape, and no output schema, the description covers everything an agent needs: capacity behavior, the two env-var controls, shell opt-in, allowlist gating, and the handoff to sibling tools. Nothing material is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the allowlist constraint on command, the argv-vs-shell distinction framing, and the consequence that a missing cwd produces a failed job. These are semantic constraints the schema alone does not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Start a command in the background') plus the key scoping trait (non-blocking, always returns synchronously). It also explicitly names the sibling tools it hands off to (status, output, tail), so an agent can distinguish it from the rest of the family without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear when-to-use routing: once a job_id exists, poll with status, read lines from a cursor with output, read the last N with tail. It also explains exactly when a call is admitted, queued, or rejected. It stops short of stating explicit exclusions (e.g., when not to background a task), so 4 rather than 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools