# Deployment walkthrough

## 0. Prereqs

- A Hugging Face account + a **write-access token** from <https://huggingface.co/settings/tokens>.
- `git` and `git-lfs` locally (`brew install git-lfs` / `apt install git-lfs`, then `git lfs install`).
- A target you own (e.g. a DVWA / Juice Shop / HTB machine) — **do not point it at random IPs.**

## 1. Create the Space

1. Go to <https://huggingface.co/new-space>.
2. **Name:** anything (e.g. `hexstrike-lab`).
3. **License:** MIT.
4. **SDK:** **Docker** → blank template.
5. **Hardware:** CPU Basic (free).
6. **Visibility:** **Private** (recommended — this is offensive tooling).
7. Click **Create Space**.

## 2. Add secrets

In the Space's **Settings → Variables and secrets** panel, add **secrets** (not vars):

| Name | Value |
|---|---|
| `HEXSTRIKE_TOKEN` | `openssl rand -hex 32`  (save this, you'll need it on the client side) |

## 3. Push the code

```bash
# from this folder
git init
git lfs install
git remote add origin https://huggingface.co/spaces/<your-username>/<space-name>
git add .
git commit -m "Initial deploy: HexStrike MCP bridge"
git branch -M main
git push -u origin main
# auth: username = your HF username, password = your HF write token
```

The Space will build (~5–8 min the first time — Docker pulls a lot of apt packages).

## 4. Verify

- Open `https://<user>-<space>.hf.space/` → you should see the status page.
- `curl https://<user>-<space>.hf.space/healthz` → `{"ok": true, "upstream": {...}, "tools": [...]}`.

## 5. Connect an AI to it

### Option A — Hugging Face-hosted LLM (recommended for you)

```bash
cd agent
pip install -r requirements.txt
export HF_TOKEN=hf_xxx
export HEXSTRIKE_MCP_URL=https://<user>-<space>.hf.space/mcp
export HEXSTRIKE_TOKEN=<same token you put in the Space secret>
python hf_agent.py "Do light recon on my lab box 10.0.0.5 — I own it."
```

The default model is `Qwen/Qwen2.5-72B-Instruct` (free-tier-friendly, solid tool calling).
You can swap via `export HF_MODEL=meta-llama/Llama-3.3-70B-Instruct` or any other
HF Inference API model that supports `tools=` in chat completions.

### Option B — Claude Desktop / Cursor / VS Code

```json
{
  "mcpServers": {
    "hexstrike-remote": {
      "url": "https://<user>-<space>.hf.space/mcp",
      "headers": { "Authorization": "Bearer <HEXSTRIKE_TOKEN>" }
    }
  }
}
```

## 6. Things you'll probably hit

| Symptom | Fix |
|---|---|
| Space build fails on `apt-get install` | Sometimes a mirror flaps — just **Restart Space**. |
| `401` on `/mcp` | The `Authorization: Bearer …` header is missing/wrong. |
| `503` on `/mcp` | You forgot to set the `HEXSTRIKE_TOKEN` Space secret. |
| HexStrike says a tool is "not available" | That binary isn't in the Dockerfile yet — add it to the `apt-get install` line and redeploy. |
| Space sleeps and first request is slow | Free CPU Basic sleeps after ~48h idle. First request wakes it (cold start ~30s). |
| Scans get killed | Free tier has 2 vCPU / 16 GB RAM — keep scans light, narrow port ranges, avoid `-T5` floods. |

## 7. Keeping it legal & on-ToS

- Keep the Space **private** unless you've reviewed HF's [Content Policy](https://huggingface.co/content-guidelines).
- The bridge **only exposes recon/web tools** — do not bolt on Metasploit / Responder / C2 frameworks on a hosted Space.
- Rotate `HEXSTRIKE_TOKEN` if you ever leak it.