−
100%
+
fit
scroll
# HexOS Portal Infrastructure **Last
Updated**: Day 00357 (2026-05-31) **Witness**:
Lumen **Purpose**: Orientation for portal
boot, dev/prod topology, and DB model --- ##
Topology ```
+----------------------------------------------------------+
| HEXLET (Mini Temple - macOS aarch64)
PRODUCTION | |
--------------------------------------------------------
| | Domain: portal.hex-os.dev | | Process: pm2
-> hexos-portal --web --port 3333 | | DB:
PostgreSQL localhost:5432 <- canonical | |
Static: Portal-Web-Vessel/static/ | | MCP:
https://portal.hex-os.dev/mcp |
+----------------------------------------------------------+
^ all nodes try to connect here first |
+----------------------------------------------------------+
| hexperiment (DigitalOcean - Linux amd64)
DEVELOPMENT | |
--------------------------------------------------------
| | Domain: portal.hexperiment.dev | |
Process: hexos-portal --web --port 3333 | |
DB: NO local PostgreSQL - connects to HEXLET |
| Falls back to Forest (SQLite) if unreachable
| | Role: dev copy - outer ring |
+----------------------------------------------------------+
``` --- ## DB Model (Day 357) **One canonical
PostgreSQL: HEXLET.** Every node (including
hexperiment) tries to connect to HEXLET's DB
first. If HEXLET is unreachable, it falls back
to Forest (local SQLite snapshot).
**hexperiment must NOT run a local
PostgreSQL.** If its local postgres is
running, the portal connects there instead of
HEXLET and diverges. To verify hexperiment is
using the right DB: ```bash ssh hexperiment
"pgrep postgres && echo 'WARNING: local
postgres running' || echo 'OK: no local
postgres'" # If running, stop it so the portal
connects to HEXLET: ssh hexperiment "sudo
systemctl stop postgresql" ``` --- ##
Development Workflow hexperiment runs newer
code against the same canonical DB as
production. "Slightly ahead of production"
means the binary, not the data. ```
hexperiment (dev) HEXLET (prod)
----------------- ------------- Build + test
code -> mesh repo push cargo build --release
git pull + rebuild pm2 restart hexos-portal
``` --- ## Startup Commands ### HEXLET
(production) ```bash cd
~/HEXCRAFT/Sacred-Lab/HexOS/Portal/rust cargo
build --release pm2 restart hexos-portal pm2
logs hexos-portal --lines 10 --nostream ```
### hexperiment (dev) ```bash # Ensure local
postgres is stopped first sudo systemctl stop
postgresql cd
~/HEXCRAFT/Sacred-Lab/HexOS/Portal/rust cargo
build --release pkill -f hexos-portal nohup
./target/release/hexos-portal --web --port
3333 \ --static-dir
~/HEXCRAFT/Sacred-Lab/HexOS/Portal-Web-Vessel/static
\ > /tmp/portal-web.log 2>&1 & ``` --- ##
Token Formats | Format | Type | Created by |
|--------|------|------------| |
`scrd_dmn_<hex>` | Daemon session token |
`api_handlers.rs` (current) | | `scrd_<hex>` |
User session token | `api_handlers.rs` | |
`scrd_trav_<hex>` | Traveler session |
`db/beings.rs` | | `dmn_<hex>` | Daemon
fingerprint stored in Thing | `db/beings.rs` |
MCP Bearer token in `.mcp.json` uses
`scrd_dmn_` format. It is a session stored via
`create_session` and validated by
`validate_session_from_things`. --- ## Boot
Orientation Checklist ```bash # 1. Which DB is
the portal connected to? △ status # shows DB
host + thing count # 2. Is hexperiment's local
postgres stopped? ssh hexperiment "pgrep
postgres || echo clean" # 3. Is HEXLET portal
running? curl -s
https://portal.hex-os.dev/api/health # 4.
Binary version △ status # shows build hash
``` --- ## Port Reference | Port | Service |
|------|---------| | 3333 | Portal web + API +
WebSocket (unified) | | 80/443 | nginx reverse
proxy | --- ## Common Issues ### `Session
invalid` in `△ status` MCP daemon token
(`scrd_dmn_`) was not propagated to the
execution token context. Fixed Day 357 in
`mcp/mod.rs`: `set_execution_token` now called
inside `spawn_blocking`. ### hexperiment
connecting to wrong DB Local postgres is
running. Stop it: `sudo systemctl stop
postgresql` Portal will then connect to HEXLET
(or Forest if offline). ### Blank page /
static files missing Web server started
without `--static-dir`. Always include the
flag. ### pm2 not found on hexperiment pm2 is
only on HEXLET (macOS). hexperiment uses nohup
or systemd. --- *Forged Day 00357 - replaces
INFRASTRUCTURE.md (Day 00193)* *Lumen*
△