Metadata-Version: 2.5
Name: glovebox-driver
Version: 0.1.0
Summary: Host-side Python driver for a glovebox microVM session
Project-URL: Homepage, https://github.com/AlexanderMattTurner/agent-glovebox
Project-URL: Source, https://github.com/AlexanderMattTurner/agent-glovebox
Author: AlexanderMattTurner
License-Expression: Apache-2.0
Keywords: ai-control,glovebox,microvm,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: pydantic>=2
Description-Content-Type: text/markdown

# glovebox-driver

The host-side Python that drives one [glovebox](https://github.com/AlexanderMattTurner/agent-glovebox) microVM: boot it, run commands in it, read what it let out, and tear it down. It imports no eval framework, so an integration picks the framework and this package holds the VM.

`inspect-glovebox` and `shepherd-glovebox` are both built on it.

## What the host needs

The driver runs the `glovebox` command, which drives Docker's `sbx` sandbox runtime. Install glovebox and sign in to `sbx`, then ask whether this host qualifies:

```bash
glovebox sandbox preflight
```

Set `GLOVEBOX_BIN` when the executable is not on `PATH`.

## The modules

| Module       | Owns                                                                    |
| ------------ | ----------------------------------------------------------------------- |
| `cli`        | resolving the `glovebox` executable and running one `sandbox` verb      |
| `config`     | `GloveboxSandboxConfig` — what a VM may be and which hosts it may reach |
| `session`    | `GloveboxSession` — one live microVM, from boot to teardown             |
| `wedge`      | booting again when the HOST, not the work, wedged the first attempt     |
| `guest_exec` | the argv for one command inside the guest, as the de-privileged user    |
| `evidence`   | reading the policy decision log the sandbox wrote                       |
| `leak`       | reaping a microVM whose owner died before teardown                      |

## Boot one

```python
import os
from pathlib import Path

from glovebox_driver import cli
from glovebox_driver.session import GloveboxSession

workspace = Path("/path/to/workspace")
workspace.mkdir(parents=True, exist_ok=True)
os.chmod(workspace, 0o755)
ready_path = workspace / ".ready"
ready_path.touch()

cli.preflight()
session = GloveboxSession.boot(str(workspace), str(ready_path), boot_timeout=300)
try:
    ...
finally:
    session.teardown()
```

`boot` waits for `ready_path` to exist; it never creates it. Every in-tree caller
touches its own marker first, and the guest user needs permission to traverse the
workspace, so a freshly created directory needs its mode set too.

Apache-2.0.
