Ghostlab MCP server
Commit Nov 7, 2026Provides a headless runner and Python SDK to execute, compose, and evaluate coding agents in checkpointed, resumable pipelines.
Also known as sajjadGG/Ghostlab
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 7, 2026
- License
- MIT
What is Ghostlab MCP?
Ghostlab provides a headless runner and Python SDK to execute, compose, and evaluate coding agents in checkpointed, resumable pipelines.
Summary generated from the project's README
About Ghostlab MCP server
Executing and evaluating coding agents through checkpointed, resumable pipelines is what Ghostlab enables for developers. It provides a headless runner and a Python SDK to manage complex workflows involving agents configured with specific models, instructions, skills, and MCP servers. Users can run these agents locally or within an NVIDIA OpenShell sandbox using harnesses like Claude Code, Codex, GitHub Copilot CLI, or OpenCode.
The infrastructure handles batch jobs such as labeling datasets or performing evaluations by saving the outcome of every item and agent call. This checkpointing ensures that if a process is interrupted, it can resume exactly where it stopped without repeating completed work. The system also distinguishes between different types of failures, such as sandbox errors or model unavailability, to help developers identify if an issue stems from the agent logic or the underlying infrastructure.
Developers interact with the system via a command line interface or by writing Python code to compose stages. You can define stages with specific behaviors like fan-out for lists, concurrency for parallel execution, or gathering results for final reporting. The tool allows for swapping agent configurations or parameters easily during a run.
What you can do with it
- 1Parallel dataset labelingYou can use multiple agents running in parallel to label a dataset while validating every response.
- 2Resumable batch processingIf a large batch job fails, you can restart it to skip completed items and only retry the ones that failed.
- 3Agentic testing and reportingCreate a workflow that writes test goals for a target and then executes them to produce a final report.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesajjadgg/ghostlab is public and reachablegithub.com/sajjadgg/ghostlab ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-07github.com/sajjadgg/ghostlab ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGhostlab
A headless runner for coding agents, and a Python SDK for composing them into checkpointed, resumable jobs.
Define an agent once — harness, model, instructions, skills, MCP servers, workspace — and run it in Claude Code, Codex, GitHub Copilot CLI, or OpenCode, on your machine or inside an NVIDIA OpenShell sandbox. Then chain agent calls into pipelines for evaluations, labeling, testing, or any batch job: every item and every agent call is checkpointed, so an interrupted run picks up where it stopped.
Ghostlab is infrastructure. It has no opinion about what your job does — an MCP evaluation is just one example pipeline.
pip install ghostlab
Run an agent
# agent.yaml
name: reviewer
harness: claude # claude | codex | copilot | opencode | command
model: sonnet
instructions: Be concise.
skills: [skills/review]
mcps:
docs: {command: node, args: [docs-mcp.js]}
workspace: repo # the agent works on a private copy
sandbox: {backend: openshell, providers: [anthropic]}
ghostlab exec --agent agent.yaml "Review src/app.py" --collect REVIEW.md
from ghostlab import Agent
agent = Agent.load("agent.yaml")
result = agent.run("Review src/app.py and reply with JSON")
result.status, result.answer, result.tool_calls, result.json()
with agent.session() as chat: # multi-turn: the harness session resumes
chat.send("Find the bug")
chat.send("Now fix it")
Compose a pipeline
from ghostlab import Agent, Pipeline, stage
@stage # one output per item
def describe(ctx, target):
explorer = ctx.agent("assistant").with_mcp(target["id"], target["mcp"])
return {**target, "capabilities": ctx.run(explorer, "What can this MCP do? JSON.").json()}
@stage(fan_out=True) # a list: each element becomes an item
def scenarios(ctx, target):
return ctx.run(ctx.agent("planner"), f"Write test goals for {target}. JSON list.").json()
@stage(concurrency=4, retries=1) # parallel, retried on failure
def evaluate(ctx, scenario):
...
@stage(gather=True) # every surviving item at once
def report(ctx, results):
...
pipeline = Pipeline("mcp-eval", [describe, scenarios, evaluate, report],
params={"assistant": Agent.load("agents/assistant.yaml"),
"planner": Agent.load("agents/planner.yaml")})
ghostlab run pipeline.py --input targets.jsonl # run
ghostlab run pipeline.py # resume
ghostlab run pipeline.py --param assistant=agents/codex.yaml # swap an agent
ghostlab status runs/mcp-eval
- Checkpointed: each item's outcome is saved as it finishes. So is each agent call inside an item, so an item that failed halfway reuses the calls that completed.
- Resumable: re-running skips done items and retries failed ones. A changed
input, parameter, or stage
versionrecomputes only what it affects. - Classified failures:
timed_out,model_unavailable,sandbox_error,harness_error, andagent_errorare kept apart, so "the agent got it wrong" never looks like "the infrastructure broke".
Examples
| Example | What it shows |
|---|---|
examples/mcp-eval |
describe an MCP → generate scenarios → emulated-user conversations judged by an agent → report |
examples/batch-label |
label a dataset with eight agents in parallel, validating every answer |
examples/release-notes |
one configured agent with instructions, a skill, and a workspace |
examples/agents |
a starting config for each harness |
Documentation
https://sajjadgg.github.io/Ghostlab/ — getting started, agents, pipelines, CLI.
License
MIT
Ghostlab MCP questions
How can I run an agent with Ghostlab?
You can run an agent via the CLI using the ghostlab exec command with a YAML configuration file, or use the Python SDK by loading an agent and calling .run().
Does Ghostlab support multi-turn conversations?
Yes, you can use the agent's session context to maintain a multi-turn chat where the harness session resumes.
What happens if a job is interrupted?
Ghostlab is checkpointed and resumable; every item and agent call is saved so that interrupted runs can pick up where they stopped.