Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault

No arguments

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

This server publishes no instructions, or was last inspected before Glama recorded them.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{}
extensions
{
  "io.modelcontextprotocol/tasks": {}
}

Tools

Functions exposed to the LLM to take actions

NameDescription
runA

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.

statusA

Get the current lifecycle status of a background job started by run: state (starting/running/exited/killed/failed), timestamps, exit_code/signal/diagnostic as applicable. For a job that got a real OS process, also reports its pid together with birth_identity, the SAME identity this server's own kill checks before ever signaling - never the pid alone, since a pid is reusable the instant its process exits. birth_identity.state is one of pending (capture still in flight), captured (a real identity is present, under identity), or unavailable (capture failed, or none was ever attempted). identity itself is platform-tagged: linux-starttime-ticks is an exact kernel start-time counter with no tolerance concept; posix-elapsed (macOS and every other non-Linux POSIX platform) is a real but PROBABILISTIC ps-observed elapsed-time correlation, never a certainty. Either way this only proves which process THIS SERVER launched for the job - it does not prove a process you separately observe by other means is that one; confirming that remains your own job. Never blocks on the job's own execution.

listA

List every background job the server currently knows about - queued, running, or finished - most-recently-started first. A queued job (admitted into the concurrency queue but not yet spawned - see run's own description) carries its queue_position; the current concurrency cap is included too. Never blocks on any job's own execution.

outputA

Get a background job's accumulated stdout/stderr output, paginated by a monotonic cursor. Pass after_cursor (from a PRIOR CALL WITH THE SAME stream SELECTION's own next_cursor) to fetch only new events since your last read of that same selection - a cursor is scoped to the exact stream value that produced it, and reusing it with a DIFFERENT stream value can skip an already-retained event on the other stream (start from 0/omit after_cursor instead when switching selections). stream selects stdout, stderr, or both (merged in real line-materialization order, default). Once a selected stream has lost some of its own history - either under its own byte/line cap while the job is still running, or because the job finished and its output later became eligible for job-output retention (see GHANTIKA_JOB_RETENTION_MS/GHANTIKA_MAX_RETAINED_JOBS) - the response discloses a bounded "dropped" count for that stream plus "droppedBeforeCursor" (the lowest seq still retained, or the stream's highest-ever-assigned seq - possibly 0 if no line was ever materialized - when nothing survives) - never which specific lines were lost, and never which of the two causes applied. "dropped" is ordinarily a count of complete lines, but it also counts two narrower events the same way: a not-yet-newline-terminated fragment discarded on reclaim, and a chunk arriving for a stream after its job is already reclaimed - neither is a materialized line, but each is real, permanent loss, so both count too rather than leaving the stream falsely indistinguishable from one that never received anything. For stream:"stdout"/"stderr" this is a scalar pair at the top level; for stream:"both" it is a nested object keyed by stream ({stdout?:{...}, stderr?:{...}}), since each stream's own loss is independent. Three distinct signals, never conflate them: "dropped" means this stream lost something forever; "truncated" means this specific call's own response window (from limit, or from that same loss) does not contain everything currently available; "next_cursor" is simply where to resume paging with the SAME stream selection - it carries no information about loss on its own.

tailA

Get the most recent output a background job has produced, for polling without re-reading everything already seen. Returns the last N real events of stdout, stderr, or both (merged in real line-materialization order, default). Once a selected stream has lost some of its own history - either under its own byte/line window cap while the job is still running, or because the job finished and its output later became eligible for job-output retention (see GHANTIKA_JOB_RETENTION_MS/GHANTIKA_MAX_RETAINED_JOBS) - the response discloses a bounded "dropped" count for that stream plus "droppedBeforeCursor" (the lowest seq still retained, or the stream's highest-ever-assigned seq - possibly 0 if no line was ever materialized - when nothing survives) - never which specific lines were lost, and never which of the two causes applied. "dropped" is ordinarily a count of complete lines, but it also counts two narrower events the same way: a not-yet-newline-terminated fragment discarded on reclaim, and a chunk arriving for a stream after its job is already reclaimed - neither is a materialized line, but each is real, permanent loss, so both count too rather than leaving the stream falsely indistinguishable from one that never received anything. For stream:"stdout"/"stderr" this is a scalar pair at the top level; for stream:"both" it is a nested object keyed by stream ({stdout?:{...}, stderr?:{...}}), since each stream's own loss is independent. Three distinct signals, never conflate them: "dropped" means this stream lost something forever; "truncated" means this specific call's own response window (from lines being smaller than what is available, or from that same loss) does not contain everything currently available; "next_cursor" is simply where to resume paging - it carries no information about loss on its own.

killA

Terminate a running background job by signaling its whole POSIX process group. Default: SIGTERM, a 5-second grace period, then SIGKILL if still alive - this is also what an explicit "SIGTERM" does, since that IS the default. Pass a different "signal" (including "SIGKILL") to skip the grace period and send exactly that one signal once. An unconfirmed kill can leave the real process group still alive even though the job now shows a terminal state; when that happens, calling "kill" again with the SAME "job_id" re-checks whether that group has since become empty and completes the recovery if so, but it never sends another signal - by then this server can no longer confirm the tracked numeric id still names the same group it originally spawned rather than an unrelated one that has since reused it, so a group that still reads alive at that point stays a disclosed, unconfirmed residual instead of being signaled again. The grace period carries a disclosed residual: the group can fully empty during that wait - its ordinary, intended outcome - and have its numeric id recycled by an unrelated later group before the pre-SIGKILL existence check that follows the wait actually runs; that check narrows the window between "still alive" and "about to send SIGKILL" as far as an existence check can, but cannot close it, since existence alone cannot tell a survived original group apart from a coincidentally-reused one. This is distinct from the eager-reap gap described below, which is a single scheduling tick rather than up to a whole grace period, and is not addressed by the once-per-job reap guard, which only ever prevents a later kill call from re-signaling, not a reused id encountered within this same escalation. A further identity gate applies specifically to that SIGKILL escalation: right before the SIGTERM above is sent, this server snapshots the group's original membership - the leader plus every currently-live descendant, each one's pid and real OS-read start time - then, once the grace period has elapsed and the group is still alive, boundedly re-reads only those same recorded members. If any one of them still reports an exactly matching start time, the group is still the one this server spawned and the SIGKILL proceeds; if none matches, escalation is refused and no SIGKILL is ever sent, disclosed via an "escalation_refused_reason" field once the job reaches a terminal state. This narrows the residual described above materially, not completely: the check and the signal remain two separate syscalls, so a member proven alive an instant before the SIGKILL runs can still exit, and an unrelated group receiving the exact same recycled id within the same whole second could still read as a match. Any failure while making this observation - a timeout, an unreadable start time, malformed output, or capturing zero usable members at all - refuses escalation rather than defaulting to it. When identity could not be confirmed at either this layer or the pre-signal check below, the earlier SIGTERM is honestly disclosed as an unconfirmed best-effort send, never as confirmed or guarded. Before signaling on POSIX, a real external check confirms the tracked leader is still genuinely the process this server spawned, against the birth identity captured at spawn time - platform-specific: on Linux it compares a raw kernel start-time counter for EXACT equality (immune to the virtualized-guest boot-time/uptime-conversion bug class an elapsed-time reading can hit), on macOS it compares real vs. expected elapsed lifetime within a several-second tolerance instead. Either way this is best-effort, not a cryptographic guarantee; a clear mismatch refuses to signal at all. That birth identity is captured asynchronously right after the job started; a kill sent moments later may briefly await that in-flight capture rather than giving up on it. When identity can't be verified at all, the group is still signaled, honestly disclosed via "identity_confirmed": false once the job reaches a terminal state. A job whose leader already exited on its own gets a real external reap for any process-group members it left behind - attempted automatically the instant that exit is observed. At most one signal-capable attempt is made per job; if that attempt does not confirm the group is empty, a later "kill" call against the same "job_id" can still re-check existence without sending any further signal, exactly like the unconfirmed-kill recovery described above. That reap only ever sets "kill_confirmed", never "identity_confirmed", since the leader is already gone and its identity is never re-checked there. While the group still holds a member the OS cannot recycle its id, so continuity proves ownership up to the moment the last member leaves - but where the leader has no surviving descendants, it IS the last member, and the group empties at exactly that exit, so no continuity reaches this server's own callback. The residual this leaves is the gap between the group emptying and that callback's existence check actually running: normally very short, but with no fixed upper bound, since it is event-loop scheduling latency a busy event loop can stretch well past - unlike the birth-identity comparison above (a stated several-second tolerance on macOS, or an exact kernel-counter match with no tolerance concept at all on Linux), this is deliberately never stated as a wall-clock bound. "kill_confirmed" true means EITHER an external process-table check found no processes still assigned to the job's ORIGINAL PROCESS GROUP - never a whole-tree or zero-surviving-descendants guarantee - OR the job never actually spawned a process group at all (an invalid cwd, an unresolvable executable, a policy denial, a genuine async spawn failure, being cancelled while still queued, or still being queued when the server shuts down), settled true as part of the job's own creation or terminal transition since there is nothing to check; false only ever means an external check was needed and could not be confirmed within the bound - a never-spawned job never reads false. On the DEFAULT path (no "signal", or explicit "SIGTERM") for a job that actually spawned a process group, both fields settle once the corresponding signal attempt has run its course - typically the same moment the job's "killed" state is reported synchronously, since a real signal getting through claims that state right then, but not always: when the group is already gone by the time this server reaches it, no signal is ever sent, and the job's own natural-exit terminal transition races independently against each field's own write rather than sharing that same synchronous step. Either way both fields settle to a real, already-known result - "identity_confirmed" from the pre-signal identity check's own completed outcome, "kill_confirmed" from the same already-gone confirmation - regardless of which of the two lands first; a default-path job cancelled while still queued is the one exception - see below - and settles only "kill_confirmed", since no process ever existed for "identity_confirmed" to describe. A caller-supplied signal OTHER than "SIGTERM" is different: for a non-terminating one (SIGSTOP), confirmation is what makes the job terminal at all, so both fields stay simply absent while it remains non-terminal. For a terminating one, including an explicit "SIGKILL", the state can independently reach "killed" via the process's own real exit, while both fields still stay simply absent - never false - until confirmation actually lands. Windows: an immediate, forceful whole-tree kill via taskkill /t /f, with no graceful phase - real and recursive, but not atomic; no identity check or process-group confirmation is performed on Windows today. A descendant that calls setsid() or otherwise moves itself into a different process group is neither signaled by this containment nor observed by its confirmation check; reparenting alone is not such an escape, since reparenting changes a process's parent, never its process group. If your command spawns a process that detaches into its own group or session, you are responsible for tracking and terminating it yourself - this tool will not, and does not claim to. Idempotent: killing an already-terminal job is a no-op with respect to the job's own recorded state, though it may still attempt a real cleanup reap. A job still waiting in the concurrency queue (it has not spawned yet) is removed from the queue and settles to "killed" immediately with "kill_confirmed": true - there is no process group to signal or check, so it is settled on the same basis as the other never-spawned cases above; the identity check specifically does not apply, since there was never a process to compare against a birth identity.

followA

Wait, bounded, for a background job started by run to have something new to report: new output on the selected stream(s), the job reaching a terminal state (exited/killed/failed), or this call's own bound elapsing - whichever happens first. A timeout is a normal, non-error result, never a hang: it means nothing happened within the bound, nothing more. status, output, and tail remain the complete way to check a job's state and output, whether or not follow is ever called - before this call, after it, or instead of it. cursor, if given, only counts output strictly newer than that seq; omit it to wait for output past whatever already exists on the selected stream(s) at the moment of this call - never for output that already existed before this call started, so a bare call never trivially returns on old backlog. stream picks which stream(s) count toward a return: "stdout", "stderr", or "both" (the default) - this selection scopes the underlying subscription itself, not just what the response later shows, so an arrival on a stream you did not select can never end this call early. Output arrival means a newly materialized line on the selected stream; a buffered fragment without a terminator does not wake the call on its own, but becomes a partial event when the selected stream finalizes; terminal state can still settle the call. timeout_ms bounds how long this one call may wait before returning on its own: omitted, it defaults to 45000ms, a value safe to rely on for any caller; an explicit value above the hard ceiling of 3600000ms (one hour) is silently clamped down to it rather than rejected, since that ceiling only bounds this one call's own subscription lifetime and has no other significance. Asking for longer than the default only pays off with a caller whose own setup actually lets one tool call stay outstanding that long - this tool has no way to see that, and claims nothing about it either way. A caller whose own execution context cannot leave a tool call outstanding for the requested duration - a subagent or background-task turn reclaimed or torn down before this call would return - never gets this tool's benefit, the same as any other call that context cannot hold open that long; that is simply how a tool call behaves there, not something this tool detects or works around. If the calling request is cancelled before this call would otherwise settle, everything it holds open (its subscriptions and its timer) is torn down immediately rather than left to run to its own natural bound. This server also caps how many follow calls may be outstanding (subscribed and waiting) at once, across every connection it serves, at 128; a call made once that cap is already reached is REJECTED outright with a tool error - never queued, never silently delayed - so a caller hitting it should back off and retry shortly, or use status/output/tail instead. That cap is enforced process-wide, not per connection or per client, since this server tracks no connection/client identity today - one connection exhausting it can still deny follow to every other connection, though never silently or without bound.

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4.2/5.0

Scored across 7 tools

Disambiguation4/5

Each tool maps to a distinct job-lifecycle action (start, inspect state, list, read output, read tail, terminate, wait), so misselection is unlikely. The only mild overlap is among output, tail, and follow, which all touch job output, but descriptions clearly separate paged cursor reads, last-N reads, and bounded waiting.

Naming Consistency4/5

All seven names are single lowercase words with no prefixes or mixed casing, giving a predictable surface. There is minor inconsistency in that some are verbs (run, kill, follow) and others nouns (status, list, output, tail), but the style is uniform enough to remain readable.

Tool Count5/5

Seven tools is well-scoped for a background job runner: one per lifecycle step, none redundant. Nothing feels padded or missing at the count level.

Completeness4/5

The lifecycle is fully covered: spawn, queue-aware status, listing, output retrieval (paged and tail), blocking follow, and termination with confirmation semantics. Minor gaps remain — no stdin/interactive input tool and no explicit cleanup/purge or bulk-kill operation, leaving retention/env vars as the only reclamation path.

Maintenance

ActivityInactive
ResponsivenessLimited data