ThreeGate/docs/quickstart.md

Quick Start (Safe Skeleton)

This quickstart brings up the ThreeGate skeleton stack and runs the tool-exec example locally.

This is a non-destructive smoke test:

• no real LLM integration
• no real fetching
• no real ERA I/O mounting
• validates that directory layout + policies + validators are coherent

---

⚠️ Important: Execution Backends

ThreeGate supports two execution backends:

• monty (default): pure compute, safest
• ERA: microVM, higher risk, explicit approval required

If you are unsure, use Monty.

---

Prerequisites

• Docker + Docker Compose v2
• Python 3 (stdlib only; no pip deps)
• (Optional for tool-exec example 'hello') ERA agent CLI installed and available in PATH
• (Optional for tool-exec example 'json sum') Monty 'agent' CLI installed and available in PATH
• Either a local LLM hosted via an OpenAI-compatible endpoint or OpenAI API key

---

1) Prepare volumes

From repo root:

mkdir -p infra/volumes/{core-workspace,fetch-workspace,proxy-cache}
mkdir -p infra/volumes/handoff/{inbound-to-core,inbound-to-fetch,quarantine}
mkdir -p infra/volumes/dropbox/pdfs_in
mkdir -p infra/volumes/tool-exec/{requests_in,results_out}

(These directories may already exist if you committed .gitkeep files.)

---

2) Make scripts executable

make perms

---

3) Start the skeleton stack

make compose-up
docker ps --format "table {{.Names}}\t{{.Status}}"

Expected:

• threegate-core
• threegate-fetch
• threegate-tool-exec
• threegate-proxy
• threegate-rolemesh

These are placeholders and will simply idle.

---

4) Run validator smoke tests

No packets exist yet, but these commands should run without error:

make validate-packets
make validate-tool-requests
make validate-tool-results

---

5) Run TOOL-EXEC example (optional)

This runs a simple Python print command via the ERA wrapper.

make tool-exec-example

Result artifacts should appear in:

• infra/volumes/tool-exec/results_out/

Then validate tool results and promote them to CORE inbound:

make validate-tool-results
ls -1 infra/volumes/handoff/inbound-to-core

---

6) Stop the stack

make compose-down

---

Next Steps (when moving beyond skeleton)

1. Implement FETCH packetizer (allowlisted domains + Research Packet creation)
2. Implement TOOL-EXEC safe data transfer (stdin/stdout protocol or guest volumes with strict allowlists)
3. Integrate RoleMesh-Gateway and a local/proxied LLM endpoint
4. Add systemd units for boot-time firewall enforcement + periodic validation

---

Safety Notes

• Do not enable /dev/kvm passthrough into TOOL-EXEC until you decide whether TOOL-EXEC should run as host service vs container.
• Keep proxy allowlist narrow and auditable.
• Treat any schema relaxation as a security change.