# Ghostlab

> A headless runner for coding agents (Claude Code, Codex, GitHub Copilot CLI, OpenCode, or any CLI), sandboxed in NVIDIA OpenShell, plus a Python SDK for composing agent calls into checkpointed, resumable pipelines — evaluations, labeling, testing, and other batch jobs.

The package and CLI are both `ghostlab`. Its only dependency is PyYAML. Ghostlab is infrastructure: job-specific logic (such as an MCP evaluation) lives in user pipelines, like the ones in `examples/`.

## Architecture (modules under `ghostlab/`)

- [agent.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/agent.py): `Agent` and `MCP` — the immutable agent definition, YAML/JSON loading, `with_`/`with_mcp` variants, `run`/`session`.
- [harnesses.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/harnesses.py): one `Harness` per CLI — command line, MCP config, resume, parser, sandbox needs.
- [parsers.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/parsers.py): each harness's JSONL stream → message, MCP/built-in tool calls, errors, session id.
- [sandbox.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/sandbox.py): `Sandbox` config and the two boxes — `LocalBox` and `OpenShellBox` (create, upload, exec, fetch, delete).
- [session.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/session.py): `Session` (multi-turn, resumes the harness session) and `Result` with classified statuses.
- [pipeline.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/pipeline.py): `stage`, `Pipeline`, `Context` — map / fan-out / gather stages, item checkpoints, per-call caching, resume.
- [cli.py](https://github.com/sajjadGG/Ghostlab/blob/main/ghostlab/cli.py): `ghostlab exec`, `run`, `status`.

## Docs

- [Getting started](https://sajjadgg.github.io/Ghostlab/getting-started/)
- [Agents](https://sajjadgg.github.io/Ghostlab/agents/): config reference, harness options, sandbox.
- [Pipelines](https://sajjadgg.github.io/Ghostlab/pipelines/): stages, context, checkpointing and resume rules.
- [CLI](https://sajjadgg.github.io/Ghostlab/cli/)

## Examples

- [examples/mcp-eval/pipeline.py](https://github.com/sajjadGG/Ghostlab/blob/main/examples/mcp-eval/pipeline.py): describe → scenarios (fan-out) → emulated-user conversations + judge → report (gather).
- [examples/batch-label/pipeline.py](https://github.com/sajjadGG/Ghostlab/blob/main/examples/batch-label/pipeline.py): concurrent labeling with answer validation and retries.
- [examples/agents/](https://github.com/sajjadGG/Ghostlab/tree/main/examples/agents): one agent config per harness.

## Development

- Tests: `.venv/bin/python -m pytest` — fake agent and fake `openshell` CLIs in `tests/fakes/` exercise the real command building, sandbox lifecycle, and parsing.
- Docs: `.venv/bin/python -m mkdocs build --strict`.
