ghostlab 0.3.0__tar.gz → 0.5.0__tar.gz

ghostlab-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing to Ghostlab
+
+Thanks for helping improve Ghostlab! This guide is written for both humans and
+coding agents. For a machine-readable map of the project, see
+[`llms.txt`](llms.txt).
+
+## Project shape
+
+- Package and CLI: `ghostlab`. Its only runtime dependency is PyYAML.
+- Layers, bottom up: `sandbox` (local / OpenShell boxes) → `harnesses` +
+  `parsers` (one class per agent CLI) → `session` (a run, single or
+  multi-turn) → `pipeline` (stages, checkpoints, resume) → `cli`.
+- Ghostlab is infrastructure. Job-specific logic belongs in pipelines under
+  `examples/`, not in the package.
+
+## Setup
+
+```bash
+python3 -m venv .venv                   # Python 3.10+
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+```
+
+Sandboxed runs need [NVIDIA OpenShell](https://docs.nvidia.com/openshell/latest/)
+(`openshell status`). The test suite does not: `tests/fakes/` provides a fake
+agent CLI and a fake `openshell` CLI.
+
+## Making a change
+
+1. Branch off `main` (`feat/…`, `fix/…`, `docs/…`).
+2. Make the change with tests.
+3. Open a PR against `main` that says what changed and why.
+
+To add a harness, subclass `Harness` in `ghostlab/harnesses.py`, add its parser
+to `ghostlab/parsers.py`, register both, and document its options in
+`docs/agents.md`.
+
+When you add or change a CLI command, update `ghostlab/cli.py`, `tests/`,
+`README.md`, and `docs/cli.md`.
+
+## Pull request checklist
+
+```bash
+.venv/bin/pytest                        # always
+.venv/bin/mkdocs build --strict         # if you touched docs/ or mkdocs.yml
+.venv/bin/python -m build               # if you touched packaging
+.venv/bin/twine check dist/*            # "
+```
+
+## Releases
+
+Publishing to PyPI is automated by `.github/workflows/publish.yml` via PyPI
+Trusted Publishing. It runs when a GitHub Release is published.
+
+1. Bump `__version__` in `ghostlab/__init__.py`.
+2. Validate: `.venv/bin/pytest && .venv/bin/python -m build && .venv/bin/twine check dist/*`.
+3. `gh release create v<x.y.z> --generate-notes`.

ghostlab-0.5.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: ghostlab
+Version: 0.5.0
+Summary: A headless runner for coding agents (Claude Code, Codex, Copilot, OpenCode), sandboxed in NVIDIA OpenShell, with a Python SDK for checkpointed, resumable agent pipelines: evals, labeling, and batch jobs.
+Project-URL: Documentation, https://sajjadgg.github.io/Ghostlab/
+Project-URL: Homepage, https://github.com/sajjadGG/Ghostlab
+Project-URL: Repository, https://github.com/sajjadGG/Ghostlab
+Project-URL: Issues, https://github.com/sajjadGG/Ghostlab/issues
+Project-URL: Changelog, https://github.com/sajjadGG/Ghostlab/releases
+Author: SajjadGG
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai-agents,batch,claude-code,codex,evaluation,github-copilot,headless,labeling,llm-evaluation,mcp,opencode,openshell,pipeline,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mkdocs>=1.6; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="static/ghostlablogo.png" alt="Ghostlab" width="160"></p>
+
+# Ghostlab
+
+**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](examples/mcp-eval/pipeline.py).
+
+```bash
+pip install ghostlab
+```
+
+## Run an agent
+
+```yaml
+# 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]}
+```
+
+```bash
+ghostlab exec --agent agent.yaml "Review src/app.py" --collect REVIEW.md
+```
+
+```python
+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
+
+```python
+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")})
+```
+
+```bash
+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 `version` recomputes only what it affects.
+- **Classified failures:** `timed_out`, `model_unavailable`, `sandbox_error`,
+  `harness_error`, and `agent_error` are kept apart, so "the agent got it wrong"
+  never looks like "the infrastructure broke".
+
+## Examples
+
+| Example | What it shows |
+| --- | --- |
+| [`examples/mcp-eval`](examples/mcp-eval/pipeline.py) | describe an MCP → generate scenarios → emulated-user conversations judged by an agent → report |
+| [`examples/batch-label`](examples/batch-label/pipeline.py) | label a dataset with eight agents in parallel, validating every answer |
+| [`examples/release-notes`](examples/release-notes/agent.yaml) | one configured agent with instructions, a skill, and a workspace |
+| [`examples/agents`](examples/agents) | a starting config for each harness |
+
+## Documentation
+
+<https://sajjadgg.github.io/Ghostlab/> — [getting started](docs/getting-started.md),
+[agents](docs/agents.md), [pipelines](docs/pipelines.md), [CLI](docs/cli.md).
+
+## License
+
+MIT

ghostlab-0.5.0/README.md

@@ -0,0 +1,112 @@
+<p align="center"><img src="static/ghostlablogo.png" alt="Ghostlab" width="160"></p>
+
+# Ghostlab
+
+**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](examples/mcp-eval/pipeline.py).
+
+```bash
+pip install ghostlab
+```
+
+## Run an agent
+
+```yaml
+# 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]}
+```
+
+```bash
+ghostlab exec --agent agent.yaml "Review src/app.py" --collect REVIEW.md
+```
+
+```python
+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
+
+```python
+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")})
+```
+
+```bash
+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 `version` recomputes only what it affects.
+- **Classified failures:** `timed_out`, `model_unavailable`, `sandbox_error`,
+  `harness_error`, and `agent_error` are kept apart, so "the agent got it wrong"
+  never looks like "the infrastructure broke".
+
+## Examples
+
+| Example | What it shows |
+| --- | --- |
+| [`examples/mcp-eval`](examples/mcp-eval/pipeline.py) | describe an MCP → generate scenarios → emulated-user conversations judged by an agent → report |
+| [`examples/batch-label`](examples/batch-label/pipeline.py) | label a dataset with eight agents in parallel, validating every answer |
+| [`examples/release-notes`](examples/release-notes/agent.yaml) | one configured agent with instructions, a skill, and a workspace |
+| [`examples/agents`](examples/agents) | a starting config for each harness |
+
+## Documentation
+
+<https://sajjadgg.github.io/Ghostlab/> — [getting started](docs/getting-started.md),
+[agents](docs/agents.md), [pipelines](docs/pipelines.md), [CLI](docs/cli.md).
+
+## License
+
+MIT

ghostlab-0.5.0/docker/agent-sandbox.Dockerfile

@@ -0,0 +1,38 @@
+# Sandbox image for running a configured agent under test.
+#
+# The agent CLI must run *inside* the sandbox, not on the host: an agent
+# configured with bash/edit permissions is exactly the configuration worth
+# testing and the least safe to run on a developer's machine. The host's own
+# Agent binaries cannot be uploaded — they are platform-specific executables —
+# so the Linux builds are installed here instead.
+#
+# Build is handled by OpenShell:
+#   sandbox:
+#     image: docker/agent-sandbox.Dockerfile
+# which resolves to `openshell sandbox create --from <this file>`.
+FROM ghcr.io/nvidia/openshell-community/sandboxes/base@sha256:aeef1c63f00e2913ea002ccb3aaf925f338b5c5d70e63576f0d95c16a138044e
+
+USER root
+
+# Pinned so a sandbox rebuild cannot silently change the agent runtime under an
+# evaluation. Bump deliberately, and re-record the version in run artifacts.
+ARG OPENCODE_VERSION=1.4.3
+ARG COPILOT_VERSION=1.0.80
+RUN npm install -g \
+        "opencode-ai@${OPENCODE_VERSION}" \
+        "@github/copilot@${COPILOT_VERSION}" \
+    && opencode --version \
+    && copilot --version
+
+# OpenCode keeps credentials and session state under XDG paths. Fixing them
+# outside $HOME keeps them off the uploaded workspace, so an agent with `edit`
+# permission cannot read or rewrite its own auth file.
+ENV XDG_DATA_HOME=/opt/agent/share \
+    XDG_CONFIG_HOME=/opt/agent/config \
+    XDG_CACHE_HOME=/opt/agent/cache
+RUN mkdir -p /opt/agent/share/opencode /opt/agent/config /opt/agent/cache \
+    && chown -R 998:998 /opt/agent \
+    && chmod 700 /opt/agent/share/opencode
+
+USER 998
+WORKDIR /sandbox

ghostlab-0.5.0/docs/agents.md

@@ -0,0 +1,123 @@
+# Agents
+
+An agent is a harness plus what it is given to work with. Load one from YAML
+or JSON with `Agent.load(path)`, or build it in Python with `Agent(...)`.
+Relative paths in a config file resolve against that file.
+
+```yaml
+name: reviewer                       # default: the file name
+harness: claude                      # claude | codex | copilot | opencode | command
+model: sonnet                        # passed to the harness as-is
+instructions: Be concise.            # free text
+instruction_files: [AGENTS.md]       # files whose contents are instructions
+skills: [skills/review]              # SKILL.md files or their folders
+mcps:                                # the `mcpServers` shape every client uses
+  docs: {command: node, args: [docs-mcp.js], env: {LEVEL: "1"}}
+  hub:  {url: "https://hub.example/mcp", headers: {Authorization: "Bearer ${HUB_TOKEN}"}}
+mcp_config: .mcp.json                # or load servers from an existing config file
+workspace: repo                      # a directory the agent works on (always a copy)
+env: {API_BASE: "${API_BASE}"}       # extra environment; ${VAR} expands on the host
+timeout: 900                         # seconds per turn
+options: {}                          # harness-specific settings, below
+sandbox: {backend: openshell}        # where it runs, below
+```
+
+Agents are immutable. Derive variants with `with_` and `with_mcp`:
+
+```python
+judge = helper.with_(model="opus", instructions="You are a strict grader.")
+tester = assistant.with_mcp("tiny", {"command": "node", "args": ["tiny-mcp.js"]})
+```
+
+## Running
+
+| Call | Does |
+| --- | --- |
+| `agent.run(prompt, run_dir=None, collect=())` | one task; returns a `Result` |
+| `agent.session(run_dir=None)` | a multi-turn `Session`; `session.send(prompt)` per turn |
+
+A session keeps one sandbox and one harness conversation alive. Later turns
+resume it with `--resume` (Claude Code), `exec resume` (Codex),
+`--session-id`/`--continue` (Copilot), or `--session` (OpenCode). Instructions
+and skills are sent on the first turn only.
+
+`collect` copies workspace paths into the turn directory before the sandbox is
+torn down; they are listed in `result.files`.
+
+### Result
+
+| Field | Meaning |
+| --- | --- |
+| `status` | `completed`, `agent_error`, `timed_out`, `model_unavailable`, `sandbox_error`, `harness_error` |
+| `ok` | `status == "completed"` |
+| `answer` | the agent's final message |
+| `json()` | the JSON value in the answer (tolerates prose and code fences) |
+| `check()` | returns the result, or raises `AgentError` if it did not complete |
+| `tool_calls` / `builtin_calls` | MCP calls and built-in tool calls: server, tool, status, arguments, result, error |
+| `session_id`, `turn`, `duration`, `exit_code`, `error`, `files`, `dir` | the rest of the trace |
+
+Each turn writes `prompt.txt`, `stdout.txt`, `stderr.txt`, `answer.md`,
+`result.json`, and `files/` under `<run_dir>/turn-N/`.
+
+## Harnesses
+
+Instruction files and skills are rendered into a preamble ahead of the task
+for every harness except OpenCode, which loads them natively. Every harness
+accepts `options.bin` (host binary) and `options.extra_args` (appended
+verbatim).
+
+| Harness | Command | MCPs via | Options |
+| --- | --- | --- | --- |
+| `claude` | `claude -p --output-format stream-json` | `--mcp-config` (pre-approved) | `permission_mode`, `max_turns`, `allow_tools`, `deny_tools` |
+| `codex` | `codex exec --json` | `-c mcp_servers.<name>.*` | `sandbox_mode`, `approval`, `reasoning_effort` |
+| `copilot` | `copilot --output-format json --prompt` | `--additional-mcp-config` | `agent`, `reasoning_effort`, `mode`, `allow_all`, `allow_all_tools`, `allow_tools`, `deny_tools`, `add_dirs`, `allow_urls`, `deny_urls`, `plugin_dirs`, ... |
+| `opencode` | `opencode run --format json` | its own config (`OPENCODE_CONFIG_CONTENT`) | `default_agent`, `config` (merged into `opencode.json`) |
+| `command` | `options.command` | — | `command` (argv), `prompt` (`stdin` or `arg`), `output` (`text`, or a harness name to parse its stream) |
+
+Codex reads `Bearer ${VAR}` and `${VAR}` headers from the environment itself,
+so those secrets never appear in its argv. OpenCode denies `bash`, `edit`, and
+`webfetch` unless `options.config.permission` allows them.
+
+Coding-agent sessions are tagged as synthetic: Codex gets
+`originator: ghostlab`, and Copilot session ids start with Ghostlab's reserved
+UUID prefix, so rollout collectors can exclude them.
+
+## Sandbox
+
+```yaml
+sandbox:
+  backend: openshell                 # or local
+  image: base                        # an OpenShell image or Dockerfile
+  providers: [anthropic]             # OpenShell providers holding credentials
+  policy: egress.yaml                # an OpenShell policy file
+  env_allowlist: [GH_TOKEN]          # host variables forwarded into the sandbox
+  uploads: [{source: data, target: /sandbox/data}]
+  files: {/opt/agent/share/opencode/auth.json: ~/.local/share/opencode/auth.json}
+  cpu: "2"
+  memory: 4Gi
+  keep: false                        # leave the sandbox running for debugging
+```
+
+`sandbox: local` is shorthand for `{backend: local}`.
+
+**OpenShell** (the default) creates one sandbox per session. It uploads the
+workspace to `/sandbox/<name>`, every stdio MCP's program to `/sandbox/mcp`,
+and any files the harness reads by path to `/sandbox/agent`. Paths in the
+command are rewritten to those locations. `files` are copied in after creation
+with mode 600, so credentials can live outside the workspace. With no
+providers the sandbox is created with `--no-auto-providers`. For OpenCode,
+when no `policy` is given, Ghostlab generates a least-privilege egress policy
+for the model's provider. The sandbox log is saved as `openshell.log`, and the
+sandbox is deleted unless `keep` is set. OpenShell failures are reported as
+`sandbox_error` and never fall back to local execution.
+
+**Local** runs the harness on the host, in a private copy of the workspace,
+with the full host environment. The copy sits in a neutral temporary directory
+while the agent runs — harnesses tell the model their working directory, and a
+run directory's path names the job and item — and is moved to
+`<run_dir>/workspace` afterwards. `uploads`, `files`,
+and the other OpenShell settings do not apply. Use it only for agents and MCPs
+you trust.
+
+The image in [`docker/agent-sandbox.Dockerfile`](https://github.com/sajjadGG/Ghostlab/blob/main/docker/agent-sandbox.Dockerfile)
+pins OpenCode and Copilot CLI builds and keeps their state outside the workspace.

ghostlab-0.5.0/docs/cli.md

@@ -0,0 +1,58 @@
+# CLI
+
+```text
+ghostlab exec    run one agent on one task
+ghostlab run     run or resume a pipeline
+ghostlab status  summarize a pipeline run
+```
+
+Exit codes: `0` success, `1` the task or some items failed, `2` invalid
+configuration.
+
+## `ghostlab exec`
+
+```bash
+ghostlab exec --agent agent.yaml "Draft release notes into RELEASE.md" --collect RELEASE.md
+echo "Summarize this" | ghostlab exec --agent agent.yaml -
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--agent PATH` | agent config (required) |
+| `TASK` / `-` / `--prompt-file PATH` | the task, inline, from stdin, or from a file |
+| `--harness`, `--model`, `--timeout`, `--workspace` | override the config |
+| `--sandbox openshell\|local` | override the execution boundary |
+| `--provider NAME` | attach an OpenShell provider (repeatable) |
+| `--collect PATH` | copy a workspace path into the run dir (repeatable) |
+| `--run-dir DIR` | where to keep the trace (default `runs/<timestamp>-<agent>`) |
+| `--json` | print the full result instead of the answer |
+
+The answer goes to stdout, and the status line and run directory go to stderr.
+
+## `ghostlab run`
+
+```bash
+ghostlab run examples/mcp-eval/pipeline.py --input examples/mcp-eval/targets.jsonl
+ghostlab run examples/mcp-eval/pipeline.py                   # resume
+ghostlab run pipeline.py:nightly --params params.yaml --param max_turns=6
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `FILE.py[:NAME]` | the module holding the `Pipeline` (`NAME` when it defines several) |
+| `--input PATH` | items as `.jsonl`, JSON, or YAML (repeatable); omit to reuse the recorded inputs |
+| `--param KEY=VALUE` | a parameter; `VALUE` is parsed as JSON when it can be, otherwise kept as a string |
+| `--params PATH` | parameters from a YAML/JSON mapping |
+| `--run-dir DIR` | run directory (default `runs/<pipeline name>`, so re-running resumes) |
+
+An agent parameter can be a config path (`--param judge=agents/judge.yaml`) or
+inline JSON (`--param 'judge={"harness": "claude", "model": "opus"}'`).
+
+## `ghostlab status`
+
+```bash
+ghostlab status runs/mcp-eval
+```
+
+Prints done, cached, and failed counts per stage and lists the failed items.
+Exits `1` when the run is incomplete or has failures.

ghostlab-0.5.0/docs/getting-started.md

@@ -0,0 +1,62 @@
+# Getting started
+
+## Install
+
+```bash
+pip install ghostlab          # Python 3.10+
+```
+
+You also need the CLI of at least one harness (`claude`, `codex`, `copilot`,
+or `opencode`). For sandboxed runs, install
+[NVIDIA OpenShell](https://docs.nvidia.com/openshell/latest/) and check it
+with `openshell status`.
+
+## Run one agent
+
+```yaml
+# helper.yaml
+harness: claude
+model: sonnet
+instructions: Be concise.
+sandbox: local                 # or {backend: openshell, providers: [anthropic]}
+```
+
+```bash
+ghostlab exec --agent helper.yaml "What is 17 * 23? Reply with the number only."
+```
+
+The answer goes to stdout. The full trace (prompt, raw stream, stderr,
+`result.json`) is kept in `runs/<timestamp>-helper/turn-1/`.
+
+The same from Python:
+
+```python
+from ghostlab import Agent
+
+helper = Agent.load("helper.yaml")
+result = helper.run("What is 17 * 23?")
+print(result.status, result.answer)
+```
+
+## Run one pipeline
+
+```python
+# label.py
+from ghostlab import Agent, Pipeline, stage
+
+@stage(concurrency=8, retries=2)
+def label(ctx, ticket):
+    reply = ctx.run(ctx.agent("labeler"),
+                    f"Label as bug, billing, or other. JSON {{\"label\": ...}}.\n\n{ticket['text']}")
+    return {**ticket, **reply.json()}
+
+pipeline = Pipeline("label", [label], params={"labeler": Agent.load("helper.yaml")})
+```
+
+```bash
+ghostlab run label.py --input tickets.jsonl     # writes runs/label/results.jsonl
+ghostlab run label.py                           # resume: done items are skipped
+ghostlab status runs/label
+```
+
+Next: the [agent reference](agents.md) and the [pipeline guide](pipelines.md).

ghostlab-0.5.0/docs/index.md

@@ -0,0 +1,26 @@
+# Ghostlab
+
+Ghostlab runs coding agents headlessly and composes them into checkpointed,
+resumable jobs.
+
+- **One agent definition, any harness.** Claude Code, Codex, GitHub Copilot
+  CLI, OpenCode, or any CLI you point it at. Instructions, skills, MCP servers,
+  and a workspace mean the same thing in each.
+- **Sandboxed by default.** The agent CLI, its stdio MCPs, and a copy of its
+  workspace run inside an NVIDIA OpenShell sandbox that is deleted afterwards.
+  Running on the host (`sandbox: local`) must be asked for.
+- **Pipelines in plain Python.** Stages map, fan out, or gather items; each
+  stage calls agents through a context that caches every call. Re-running a
+  pipeline resumes it.
+
+Ghostlab is the infrastructure layer. Evaluations, labeling runs, test
+generation, and migrations are pipelines you write on top of it. See
+[the MCP evaluation example](https://github.com/sajjadGG/Ghostlab/blob/main/examples/mcp-eval/pipeline.py).
+
+| Page | Read it for |
+| --- | --- |
+| [Getting started](getting-started.md) | install, run one agent, run one pipeline |
+| [Agents](agents.md) | the agent config, every harness's options, the sandbox |
+| [Pipelines](pipelines.md) | stages, the context, checkpointing and resume |
+| [CLI](cli.md) | `ghostlab exec`, `run`, `status` |
+| [Publishing](publishing.md) | releasing the package and this wiki |