132 lines
2.8 KiB
Markdown
132 lines
2.8 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
make perms
|
|
```
|
|
|
|
---
|
|
|
|
## 3) Start the skeleton stack
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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.
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
make validate-tool-results
|
|
ls -1 infra/volumes/handoff/inbound-to-core
|
|
```
|
|
|
|
---
|
|
|
|
## 6) Stop the stack
|
|
|
|
```sh
|
|
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.
|
|
|