Jailbroken Studio · HA VS Server

1. Overview

Jailbroken Studio (product name on the landing: HA VS Server) gives each operator a private cloud IDE instance:

• Full VS Code Server in the browser
• Isolated shell on a private /workspace volume
• HARD ALLOW agent terminals (Grok / multi-LLM) for implementation without soft refusal monologues on authorized software work
• Optional context-nodes graph (per-tenant memory isolation)
• Optional own VPS sync + remote control via SSH helpers

2. Quick start (tenant user)

1. Open your tenant URL (example: https://matt.jailbroken.tech).
2. Log in with the code-server password provided by the operator.
3. You land in VS Code. Open the integrated terminal or fullscreen terminals:
   • /term/shell/ — normal bash (tenant user)
   • /term/ha/ — HARD ALLOW agent terminal
4. Work under /workspace (especially /workspace/projects).
5. Use agents:

   grok --hard-allow
   claude --hard-allow
   kimi --hard-allow
   # also: --hard-allow=reuse

6. (Optional) Connect your VPS — see Own VPS.
7. (Optional) Open memory graph: /nodes/ and list UI /nodes/list.

3. URL map

Inside VS Code: Terminal → Shell and Terminal → HARD ALLOW profiles mirror the fullscreen term routes.

4. Architecture

Key components

5. Tenants & isolation

Each customer or operator seat is a tenant slug (e.g. admin, matt, grunt, demo2…).

• Container: jb-tenant-{slug}
• Volume: jb_{slug}_ws → /workspace (exclusive)
• Password: unique code-server password (often same for term basic-auth user tenant)
• Docker labels: com.jailbroken.tenant={slug}, com.jailbroken.product=studio
• No docker.sock, no host home mounts into commercial tenants
• Default resource caps: ~2 CPU / 4G RAM / pids 2048 (tenantctl)

Registry of live tenants (operator host): ~/.local/share/jailbroken-studio/tenants/registry.json.

6. Workspace layout

Everything durable for a tenant lives under /workspace:

Home for tools: /home/tenant (.claude, .kimi, .grok configs when installed).

7. VS Code Server (editor)

• Product: code-server behind tenant Caddy
• Auth: password (CODE_PASSWORD / PASSWORD)
• Extensions: image may preinstall common VS extensions
• Settings under tenant home / code-server config
• WebSocket-friendly reverse proxy (Apache + Caddy flush_interval, Upgrade rules)

Primary workflow: open files under /workspace/projects, use multi-file edit, integrated terminal, agent CLIs.

8. Terminals

Shell startup scripts export HA env when secrets are present so grok --hard-allow works. Paid/manual tenants often use TTYD_NO_AUTH=1 (VS password already gates entry); demos may use tighter session gates.

9. /studio landing

Lightweight HTML chrome with deep links to editor, shell, HA terminal, and docs pointers. Not the marketing site — per-tenant convenience page.

10. HARD ALLOW (HA)

HARD ALLOW is the operator authorization mode that elevates agent sessions: nuclear grants / commercial preamble (mode-dependent), always-approve tooling posture, and soft-refuse override for authorized work.

• Host ceremony produces live token under ~/.grok/hard-allow/
• Secrets prepared into Docker-readable files under ~/.local/share/grunt-ha/docker/secrets
• Tenant wrappers inject env: GROK_HARD_ALLOW_ACTIVE, SECOPS_HARD_ALLOW_* when provisioned
• CLI flags: --hard-allow, --hard-allow=reuse (stripped by wrappers before real binary)

11. Multi-LLM CLIs

# Examples inside tenant shell
grok --hard-allow
claude --hard-allow
kimi --hard-allow
claude --hard-allow=reuse -p "summarize /workspace/README.md"

If a tenant is missing binaries (older image), operator can sync from admin:

~/.local/share/jailbroken-studio/control/sync-cli-to-tenant.sh <slug>

12. MCP servers (in-tenant)

Kimi/Claude may load MCP configs from home (e.g. ~/.kimi/mcp.json).

• ha-god-dream → node /opt/jb/mcp-offense-cp.mjs (control-plane tools; needs file present + reachable CP_URL)
• mcp-nodes-http.mjs → context-nodes via HTTP

Missing MCP module paths produce MODULE_NOT_FOUND at spawn — fix by installing the module under /opt/jb/ on that tenant container.

13. Context nodes & memory (isolated)

Context-nodes is the platform knowledge graph + live write-back runtime on the Mac host.

Each tenant Caddy proxies /nodes-api/* with a fixed header so admin and customer never share state.

# Examples (host)
curl -sH 'X-Context-Tenant: matt' http://127.0.0.1:9090/health
curl -sH 'X-Context-Tenant: admin' http://127.0.0.1:9090/stats
curl -s http://127.0.0.1:9090/tenants

Local exclusive memory (optional, volume-only): memory-write / memory-read → /workspace/.nodes/memory/.

CLI helpers (customer e.g. matt): nodes-matt health|profile|list-mine|commit|…

14. Nodes UI

• /nodes/ — D3 force/graph visualizer; loads /nodes-api/proxy/state.json + graph.jsonl
• /nodes/list — list/search UI; commits/queries with tenant token
• Assets under /opt/jb/web/viz + nodes.html

Requires tenant Caddy routes for /nodes* and /nodes-api* (admin-class Caddyfile). Base tenant images without routes return code-server 401 on /nodes/.

15. Own VPS connect (customer)

Some tenants (e.g. matt) include a dedicated SSH keypair and helpers so the customer can store projects on their VPS.

One-time setup

1. Install Studio public key on the VPS authorized_keys (see tenant /workspace/VPS.md).
2. Edit /workspace/.vps/config.env:

   VPS_HOST=your.ip.or.domain
   VPS_USER=root          # or deploy
   VPS_PORT=22
   VPS_REMOTE_DIR=/var/www/matt
   # optional:
   # VPS_POST_CMD=systemctl reload nginx
   VPS_IDENTITY=/workspace/.vps/id_ed25519
   

3. vps-status until SSH works.

Commands

Default sync root: /workspace/projects. Excludes: .git/, node_modules/, .vps/, .ssh/.

16. LLMs working on the VPS

Recommended model: LLMs run in Studio; they control the VPS over SSH.

# After editing in /workspace/projects/my-app
vps-deploy /workspace/projects/my-app
vps-ssh 'cd /var/www/matt/my-app && ./scripts/remote-deploy.sh'
vps-ssh 'systemctl reload nginx'
vps-ssh 'curl -fsS http://127.0.0.1:8080/health'

Agent prompt pattern: write under projects/ → deploy → remote verify → show evidence. Use HA CLIs so agents can execute shell freely within policy.

Optional later: install agents on the VPS itself (24/7 on-box). Heavier; not required for deploy/DNS control.

17. Deploy, DNS, and broader control

Safer defaults: dedicated deploy user, limited sudo, zone-scoped DNS tokens, secrets in env files mode 600, runbooks under the project.

18. tenantctl (operator CLI)

Host path: ~/.local/share/jailbroken-studio/control/tenantctl (often linked as ~/.local/bin/tenantctl).

tenantctl build                 # build tenant image
tenantctl fleet-up              # edge + portainer etc.
tenantctl provision <slug> [pass]
tenantctl list | status | password <slug>
tenantctl destroy <slug> [--purge-volume|--keep-volume]
tenantctl tunnel 18880 18880    # reverse tunnel helper

Admin-class image: provision with JB_IMAGE=jailbroken-studio:latest when full HA IDE image is required (vs lighter jailbroken-studio-tenant).

Related scripts:

• jb-studio-vhost on AMS — add Apache reverse proxy for a slug
• dns-add-tenant.mjs — DNS helper when wildcard not enough
• sync-cli-to-tenant.sh — copy claude/kimi HA tooling from admin
• Watchdog LaunchAgent for tunnel health

19. Fleet / edge / tunnel

• Compose under ~/.local/share/jailbroken-studio/fleet/
• Caddy snippets: fleet/caddy/tenants/{slug}.caddy
• Shared tunnel: AMS 127.0.0.1:18880 → Mac edge :18880 for all tenants
• Portainer: host http://127.0.0.1:19000

20. DNS & TLS (platform)

1. Wildcard DNS *.jailbroken.tech → AMS public IP
2. LE multi-SAN cert jailbroken.tech expanded per hostname when needed: certbot certonly --apache --cert-name jailbroken.tech --expand -d … -d docs.jailbroken.tech
3. Apache: HTTP→HTTPS redirect + SSL vhost ProxyPass to tunnel for studio tenants; static DocumentRoot for landing/docs
4. WebSocket: Upgrade rewrite rules for code-server/ttyd

21. Landing & billing

• Public site DocumentRoot on AMS: /var/www/jailbroken-landing
• Pay API proxied e.g. /api/pay → Mac tunnel port (e.g. 18992)
• Billing artifacts under ~/.local/share/jailbroken-studio/billing/ (orders, manual tenants)
• Funnel: demo capacity → USDT pay → provision private tenant

22. Demo pool

Demo tenants (demo2–demo5 pattern): timed sessions, gates, optional wipe on end, stricter ttyd client limits. Control scripts under control/demo-* and playbooks. Not for permanent customer data.

23. Admin vs customer tenants

24. HTTP API reference (selected)

Tenant

GET /api/health
→ {"ok":true,"tenant":"<slug>","inbox":"/workspace/inbox","ha":"1",…}

Context-nodes (host :9090 or via /nodes-api)

GET  /health?tenant=
GET  /tenants
GET  /query?node=&token=
GET  /list?prefix=
GET  /search?q=
GET  /stats
GET  /related?node=
GET  /ledger
POST /upsert   {token,id,patch,source,host}
POST /commit-turn {token,source,host,sessionId,summary,facts,tags}
GET  /proxy/state.json
GET  /proxy/graph.jsonl
POST /reload

Always scope with X-Context-Tenant when calling shared :9090 from tooling.

25. Security model

• Per-tenant container + volume isolation
• TLS at AMS; passwords per tenant
• No cross-tenant mounts; no docker.sock in tenants
• HA secrets: prefer vault/hagrok separation in hardened images
• Customer VPS key is tenant-specific; private key stays in .vps
• Nodes multi-tenant disk isolation
• Resource limits and pids cgroup
• Residual risks: container escape (kernel), social engineering of agents, shared host for all tenants

26. Troubleshooting

27. Glossary

28. Operator checklists

New public tenant

1. tenantctl provision <slug> [password] (choose image if admin-class)
2. ssh ams jb-studio-vhost add <slug>
3. Expand LE cert with new SAN if required
4. Ensure tunnel/watchdog up
5. Smoke: curl -fsS https://<slug>.jailbroken.tech/api/health
6. Optional: nodes UI, claude/kimi sync, VPS key seed, isolated nodes store
7. Deliver URL + password to customer (out of band)

Customer VPS enablement

1. Generate ed25519 under tenant secrets / /workspace/.vps
2. Document pubkey in VPS.md
3. Install vps-* scripts in /workspace/bin
4. Customer sets VPS_HOST and authorized_keys