# Crabbox Remote Proof

Crabbox is the remote execution layer for `teleo-infrastructure`. It is not the production deploy system.

## Goals

- Run Python tests on a disposable or warm remote Linux box.
- Prove the CI/Crabbox contract without network access before remote runs.
- Run the Phase 1B local proof script remotely.
- Retain JUnit and machine-readable proof artifacts.
- Give agents a bounded job list instead of arbitrary cloud shell access.

## Non-Goals

- No production deploys.
- No production secrets.
- No production VPS mutation.
- No production `decision-engine` PR comments from Crabbox jobs.

## Required Local Setup

Crabbox CLI 0.22.1 or newer:

```bash
crabbox --version
```

One of:

```bash
crabbox login --url "$CRABBOX_COORDINATOR"
```

or direct Hetzner operator env:

```bash
export HCLOUD_TOKEN="..."
```

Do not commit either value.

## Jobs

```bash
crabbox job list
crabbox job run --dry-run ci-contract
crabbox job run --dry-run unit
crabbox job run --dry-run phase1b-local-proof
crabbox job run ci-contract
crabbox job run unit
crabbox job run phase1b-local-proof
```

`ci-contract` writes:

- `.crabbox-results/crabbox-ci-contract.json`

`phase1b-local-proof` writes:

- `.crabbox-results/crabbox-ci-contract.json`
- `proof/phase1b-local-e2e-proof.json`
- `.crabbox-results/phase1b-pytest.xml`
- `.crabbox-results/phase1b-proof-summary.json`

The contract proof checks that:

- Crabbox exposes only the named bounded jobs.
- sync excludes secret/runtime files such as `.env`, `secrets`, DBs, logs, caches, and virtualenvs.
- `.crabbox.yaml` contains no token-bearing env names.
- Leo routes are explicit: Leo-owned domains, fallback routes, and top-2 cross-domain routes that include Leo are covered, while Phase 1B does not silently preserve Leo as a universal second reviewer.

## Secret Boundary

Allowed:

- `CI`
- `PYTHONWARNINGS`
- `PHASE1B_AGENT_ROUTING_ENABLED`
- broker token in user config
- direct `HCLOUD_TOKEN` or `HETZNER_TOKEN` in local operator env
- GitHub environment secrets named `HCLOUD_TOKEN` or `HETZNER_TOKEN` for an explicitly dispatched remote proof workflow

Not allowed:

- production GitHub admin token
- production Forgejo token
- production OpenRouter key
- production SSH keys
- Bitwarden exports
- prod `pipeline.db`

Bitwarden may be used as the human/operator source of truth for secret lookup and GitHub secret setup, but no Bitwarden item value, vault export, or copied secret belongs in this repo. The committed config may name required secret slots; it must not contain the values.

## Proof Boundary

Crabbox remote proof proves repo behavior on a remote Linux lease. It does not prove production parity unless the lease recreates the production runtime paths, systemd services, timers, DB path, and deploy script behavior.
