FrameBridge 0.3.1 community source release
This commit is contained in:
FrameBridge Development committed
commit
b23819fff1
1354 files changed
+343716
No files matched your search
@@ -0,0 +1,571 @@
|
||||
{
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topics": {
|
||||
"start": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "start",
|
||||
"title": "Start with FrameBridge",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "One interface for people and agents",
|
||||
"body": "FrameBridge provides tools and a shared command-line interface for human operators and authorized agents. fb is the short name for framebridge; both run the same program. The tools run on your Linux computers. The ChatGPT model remains hosted. Read this guide for the installed version before operating; confirm the receiver, target and available capabilities. Use the installed CLI and tools for normal work. Edit software only when the owner explicitly requests development, using a separate source clone and reviewable changes rather than rewriting the installed program.",
|
||||
"commands": [
|
||||
"fb help",
|
||||
"fb status",
|
||||
"fb --json status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Install and connect",
|
||||
"body": "On a supported Debian system, install the downloaded package with the package manager. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal. Advanced setup is optional for selecting central/node roles and public settings.",
|
||||
"commands": [
|
||||
"sudo apt install ./FrameBridge-0.3.1.deb",
|
||||
"fb connect"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Updating and removal",
|
||||
"body": "Install an official update through the normal package manager. Normal package removal stops package-owned managed processes and retains the profile and saved encrypted connection material for deliberate reuse; it is not a credential-forgetting operation. Use the separately documented explicit forget action first if that is your intended outcome. Do not assume purge erases user-profile data.",
|
||||
"commands": [
|
||||
"sudo dpkg --remove framebridge-original-expanded"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Human authentication",
|
||||
"body": "The normal connection asks for an optional account label, a hidden tunnel ID and a hidden MCP server access key. The label is metadata, not proof of ChatGPT login. Browser login/consent and normal operating-system authentication remain human actions in the normal interface. Never put credentials in chat, command arguments, documentation or example files. A successful managed connection returns to the prompt and can run independently of that terminal. Reboot only when an actual system change requires it.",
|
||||
"commands": []
|
||||
},
|
||||
{
|
||||
"heading": "Choose the right guide",
|
||||
"body": "Use commands for the reference, connection and lifecycle for state changes, nodes for central/node work, terminals for persistent Bash, and screens for authentic CUA evidence. Query success alone does not mean the connection is ready. The guide describes registered operations; use status/doctor to investigate current state.",
|
||||
"commands": [
|
||||
"fb help commands",
|
||||
"fb help connection",
|
||||
"fb help lifecycle"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "ac55eed900b5d1687b784299c5dfa238c7502c8472b1135dfa2d7231352f9daa"
|
||||
},
|
||||
"commands": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "commands",
|
||||
"title": "Command reference",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Everyday commands",
|
||||
"body": "connect establishes or resumes the managed ChatGPT connection. disconnect pauses that connection until an explicit connect, including across recovery and reboot. status reports runtime, connection, intended connection state and boot policy. doctor diagnoses prerequisites/problems. setup edits advanced stopped-profile settings. console opens the text work view. help reads this versioned reference.",
|
||||
"commands": [
|
||||
"fb connect",
|
||||
"fb disconnect",
|
||||
"fb status",
|
||||
"fb status connection",
|
||||
"fb status runtime",
|
||||
"fb status boot",
|
||||
"fb status console",
|
||||
"fb doctor",
|
||||
"fb setup",
|
||||
"fb console",
|
||||
"fb help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Services and boot",
|
||||
"body": "For an already configured managed profile, service start/stop control the current stack symmetrically. Boot enable/disable changes future startup policy without stopping current work or forgetting the saved credential. First node provisioning is an explicit exception described in lifecycle. Without managed setup, non-node service start starts local tools only; normal first connection should use connect. Read status before and after changes. The separate credentials forget action is destructive and requires explicit confirmation.",
|
||||
"commands": [
|
||||
"fb service start",
|
||||
"fb service stop",
|
||||
"fb service boot enable",
|
||||
"fb service boot disable"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Console and specialized operations",
|
||||
"body": "console login manages optional work-view opening after an authenticated tty1 login; it does not enable automatic login. tty service manages the terminal daemon; tty list lists sessions. nodes, certificates and screen-access retain their domain-specific subcommands. Use --help at the relevant command for its exact arguments. Avoid compatibility aliases in new automation.",
|
||||
"commands": [
|
||||
"fb console login status",
|
||||
"fb tty service status",
|
||||
"fb tty list",
|
||||
"fb nodes --help",
|
||||
"fb certificates --help",
|
||||
"fb screen-access --help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Human and structured output",
|
||||
"body": "Use explicit commands in automation rather than the interactive no-argument menu. --json selects structured output for an agent; examine operation success, readiness and state separately. Read errors and the exit status. If human interaction is required, complete it in the normal terminal/interface rather than attempting to supply a secret through the agent. CLI JSON uses an envelope with schema_version, product, version, command, ok and result. Read runtime, connection and boot truth inside result; envelope ok denotes request success. Exit 0 means successful query/operation, not necessarily a connected transport; exit 1 reports operation/diagnostic failure, exit 2 invalid arguments or required human interaction/confirmation, and exit 130 cancellation.",
|
||||
"commands": [
|
||||
"framebridge --json status",
|
||||
"fb --json status connection"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "9bc22a59b75eba4a6a0734320f76b5216001bbe527b2575f9f5dcee2a6abfc99"
|
||||
},
|
||||
"connection": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "connection",
|
||||
"title": "Connect and disconnect ChatGPT",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Normal managed connection",
|
||||
"body": "connect creates the default standalone profile when absent and establishes managed startup. It asks for initial human input in the terminal, checks progress, reports readiness or an actionable failure, and returns to the prompt. Valid saved setup can be resumed without repeating the initial fields. The MCP access key is not an OpenAI API key. Keep the browser's ChatGPT account login and consent separate from the optional local account label.",
|
||||
"commands": [
|
||||
"fb connect",
|
||||
"fb status connection"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Saved credentials and next boot",
|
||||
"body": "Managed startup uses protected, host-bound encrypted connection material. The normal terminal does not have to remain open. This is a persistence feature, not a promise that an account, network or tunnel service can never fail. Connection intent and boot policy are separate: enabled startup runs the stack at boot, while an intentional disconnected state remains disconnected until connect.",
|
||||
"commands": [
|
||||
"fb status boot",
|
||||
"fb status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Intentional disconnect",
|
||||
"body": "disconnect keeps local tools and saved material, but records the intention to stay disconnected across worker recovery and reboot. Explicit connect clears that pause. Check the returned state rather than interpreting a successful query as an active transport.",
|
||||
"commands": [
|
||||
"fb disconnect",
|
||||
"fb status connection"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Replacement and temporary foreground mode",
|
||||
"body": "Use connect --replace only when deliberately replacing the account label/tunnel/access configuration. The advanced --foreground mode is temporary, needs a ready local runtime and occupies its terminal until interrupted; it is not the normal managed workflow. Do not use advanced mode merely to recover a normal saved connection.",
|
||||
"commands": []
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "601d608bf403f0cf3cd531dc42013c1d53cddaf622dd73b8ec2a13aeb9c98fb8"
|
||||
},
|
||||
"lifecycle": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "lifecycle",
|
||||
"title": "Services, connection intent and boot policy",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Separate states",
|
||||
"body": "FrameBridge distinguishes actual local runtime, desired connection, verified transport, boot enablement and saved credential presence. A healthy runtime can be intentionally disconnected; a service can be active while disabled for the next boot. Read the labelled status fields together.",
|
||||
"commands": [
|
||||
"fb status",
|
||||
"fb --json status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Current managed stack",
|
||||
"body": "For an already configured managed profile, service start and service stop use the same current-stack boundary without changing boot enablement. Stop ends current managed work and transport but keeps profile, boot policy and saved material. Startup on the next boot follows the retained policy and intended connection state. A non-node profile without managed setup starts only local tools. Stopping a terminal service or session can interrupt its running work.",
|
||||
"commands": [
|
||||
"fb service start",
|
||||
"fb service stop"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Future boot policy",
|
||||
"body": "Once managed setup exists, service boot enable/disable changes unit enablement only. It does not immediately stop or start current work and does not delete saved connection material. Initial node provisioning is described separately below. Explicitly forgetting saved material is a separate destructive operation. Legacy autostart disable has its old broader destructive behavior; use the canonical service boot commands for new workflows.",
|
||||
"commands": [
|
||||
"fb service boot enable",
|
||||
"fb service boot disable",
|
||||
"fb status boot"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "First managed startup for a node",
|
||||
"body": "After advanced node setup and the required enrollment/approval, a node without a managed installation can run service start in a normal terminal. This first call creates managed startup, enables future boot and starts the node now; the result explicitly reports initial_configuration and boot_policy_changed. Alternatively, first service boot enable prepares and enables the node unit without starting current work. Initial preparation can require normal owner authentication and is not silently performed by an unattended JSON request. Once configured, the ordinary start/stop and boot-policy-only contracts apply. A node does not need its own ChatGPT tunnel.",
|
||||
"commands": [
|
||||
"fb service start",
|
||||
"fb service boot enable",
|
||||
"fb status boot"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Console opening",
|
||||
"body": "Opening console is a view operation, separate from Linux service startup. Optional console login enable/disable changes the owned startup hook after an authenticated tty1 Bash login. This hook does not bypass normal login. Review the command's scope before changing it.",
|
||||
"commands": [
|
||||
"fb console login status"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "e6aca4ba3fc004cc2475ea141a1f645070a5bde306387e89ec904daec2b2f317"
|
||||
},
|
||||
"nodes": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "nodes",
|
||||
"title": "Central and node operation",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Roles",
|
||||
"body": "Standalone provides local tools. Central adds the broker for enrolled nodes. A node joins one selected central instance and uses its ChatGPT connection; it does not need another ChatGPT tunnel or phone pairing. Advanced setup selects the role. Preserve explicit authenticated node transport and real identity approval.",
|
||||
"commands": [
|
||||
"fb setup",
|
||||
"fb nodes --help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Enrollment is not availability",
|
||||
"body": "Enrollment submission, central approval, node receipt of authorization and a running node agent are separate stages. status reports what it actually knows; an unchecked agent is not evidence that the node is online. Central list/pending/approve and node enroll/poll/status/run have role-specific purposes. poll can complete saved authorization; it is not a purely observational operation. After enrollment, consult the lifecycle topic for first managed node startup and its explicit initial boot-policy effect.",
|
||||
"commands": [
|
||||
"fb nodes list",
|
||||
"fb nodes pending",
|
||||
"fb nodes status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Targets",
|
||||
"body": "LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.",
|
||||
"commands": []
|
||||
},
|
||||
{
|
||||
"heading": "Transport trust",
|
||||
"body": "certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.",
|
||||
"commands": [
|
||||
"fb certificates --help"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "440ed8b07ab2d7c89d4383d91342801a36f46dba72692482d419f457bb412186"
|
||||
},
|
||||
"terminals": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "terminals",
|
||||
"title": "Persistent Bash terminals",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Service and sessions",
|
||||
"body": "tty service controls the profile's terminal daemon. tty open creates a real Bash session and returns its identifier. Use that identifier for subsequent observations and input. The same Bash preserves directory, variables and work between requests while the session/service remains alive. It does not preserve running processes across an operating-system reboot. Tool jobs use a profile-specific HOME; a job's home directory can therefore differ from the human login home. Commands retain the connecting account's normal operating-system permissions.",
|
||||
"commands": [
|
||||
"fb tty service status",
|
||||
"fb tty list",
|
||||
"fb tty open"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Observe, type and keys",
|
||||
"body": "tty observe returns terminal transcript text, cursor, dimensions and process state; it is not an authentic full-screen image. tty type sends text without automatically adding Enter, though supplied newlines can affect execution. tty key accepts exact uppercase names such as ENTER and CTRL_C. Replace session arguments with an identifier returned by open/list; never guess one.",
|
||||
"commands": [
|
||||
"fb tty key --help",
|
||||
"fb tty type --help",
|
||||
"fb tty observe --help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Lifetime and closing",
|
||||
"body": "Default real idle expiry is disabled, but a profile can configure a timeout. Global status/list does not refresh each session's per-session activity. close destroys a session rather than merely separating a viewer. Graceful service stop attempts to close its sessions; elevated or unverifiable process state can prevent cleanup. Inspect the outcome instead of assuming that all child processes disappeared.",
|
||||
"commands": [
|
||||
"fb tty close --help",
|
||||
"fb tty resize --help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Sudo mode",
|
||||
"body": "A session's sudo on/off controls normal privilege eligibility; it does not log in as root or bypass operating-system authentication. Changing the mode recreates Bash, preserving directory and dimensions but not shell variables or internal state. Authentication stays in the normal human terminal/interface. Never send a password through type or chat.",
|
||||
"commands": [
|
||||
"fb tty sudo --help"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Work console panels",
|
||||
"body": "console combines an ordinary Bash pane with a read-only FBTERM activity dashboard. The dashboard is not a second interactive shell. The tmux prefix is Ctrl+B: release both keys, then press lowercase z to enlarge/restore a pane, or lowercase o to switch panes. The release accepts common zoom-key variants within its dedicated console. Closing a viewer normally leaves its tmux session alive; leaving Bash, killing its server or rebooting is different. In a desktop terminal the shared work view is horizontal with FBTERM on the left and Bash on the right. Explicit TTY mode is vertical with a short FBTERM monitor above Bash. The layout belongs to the shared tmux window and follows the last requested view mode; it is not isolated per viewer.",
|
||||
"commands": [
|
||||
"fb console",
|
||||
"fb status console"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "d58f36e8b96bf4687d99fe009e0061d0e76435ddb30a1601826c9eb941b64e9d"
|
||||
},
|
||||
"screens": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "screens",
|
||||
"title": "Authentic screen observation and input",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Text transcripts and pixels",
|
||||
"body": "A CLI tty transcript describes a terminal and explicitly does not claim authentic pixels. MCP real-screen CUA-TTY and graphical screen tools operate through the real screen client and capture-linked interaction. Use those supported observation tools when authentic complete screen evidence is required. Never present a reconstructed terminal, animation or partial invented view as a real screenshot.",
|
||||
"commands": []
|
||||
},
|
||||
{
|
||||
"heading": "Automatic graphical discovery",
|
||||
"body": "The installer and control console stay text interfaces in both TTY and a desktop terminal. Compatible graphical CUA is discovered automatically; availability depends on the actual display/session and permissions. A loaded module is not proof that real pixel capture or input succeeded. New profiles use adaptive auto mode: without a verified active X11 session the runtime provides FBEXEC, FBTERM and CUA-TTY in text mode, without requiring a graphical login or automatically creating a private desktop. Explicit virtual-desktop settings remain advanced options and are labelled separately from physical-screen evidence.",
|
||||
"commands": [
|
||||
"fb status",
|
||||
"fb doctor"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Frame-buffer read access",
|
||||
"body": "screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication.",
|
||||
"commands": [
|
||||
"fb screen-access status"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Shared desktop",
|
||||
"body": "A graphical desktop shares focus, keyboard and mouse. Use one controlling agent per desktop at a time and avoid overlapping work. This is an operating recommendation, not a claim of certified automatic isolation. Independent non-overlapping execution jobs may be possible; do not infer isolation or physical parallel execution from that alone.",
|
||||
"commands": []
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "b186eb36570b870490eedf424b30eabb4c130ee2e2c72d658fe09b77549bbc59"
|
||||
},
|
||||
"diagnostics": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "diagnostics",
|
||||
"title": "Status and diagnosis",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Inspect before acting",
|
||||
"body": "status summarizes current runtime, connection, desired state and boot policy. A query completing successfully is distinct from the components being ready. Connection verification has a freshness boundary; retrying or unknown must not be treated as connected. Focused status uses the same underlying state model.",
|
||||
"commands": [
|
||||
"fb status",
|
||||
"fb status connection",
|
||||
"fb status runtime",
|
||||
"fb status boot"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Doctor",
|
||||
"body": "doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes.",
|
||||
"commands": [
|
||||
"fb doctor"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Logs and progress",
|
||||
"body": "Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.",
|
||||
"commands": [
|
||||
"fb help connection",
|
||||
"fb help lifecycle"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "0e55b9cda6b528926ca2a297d8464908a300122edbc1550b841ab8c1b7673029"
|
||||
},
|
||||
"security": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "security",
|
||||
"title": "Authorization, distribution and safe operation",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Authorized scope",
|
||||
"body": "An agent can use the documented CLI and MCP tools within the user's authorized scope. Reading this guide does not grant permission. Verify the receiver and selected target. Normal human terminal/browser authentication remains separate; do not request credentials in chat or invent phone/Owner-TTY enrollment requirements. Normal use should operate through the installed CLI and tools, not edit or rebuild installed FrameBridge program files. If the owner explicitly requests development, use a separate source clone, make reviewable changes, and do not present a modified build as an official release. This operating guidance does not restrict GNU GPL freedoms or require private forks to submit changes upstream.",
|
||||
"commands": []
|
||||
},
|
||||
{
|
||||
"heading": "Official releases",
|
||||
"body": "The source is distributed under GNU GPLv3-only terms and the applicable third-party notices. Verify official release checksums and published signatures/repository metadata before installing. Signature verification identifies the publisher and detects alteration; it does not prohibit lawful modified versions. Official releases are reviewed through the project's release process.",
|
||||
"commands": []
|
||||
},
|
||||
{
|
||||
"heading": "Side effects",
|
||||
"body": "Read status before service stop, credential forgetting, node approval, startup-hook changes or administrative screen permission changes. Explain material scope and consequences and follow the user's authorization. A sensitive operation must report the actual result, not just that a query succeeded. Keep real captures complete and distinguish observations from hypotheses.",
|
||||
"commands": []
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "2be17b3d7cb261f6cb5fbb94bfd027ca34147b8a4ead902f6a53b477fb4c201c"
|
||||
},
|
||||
"compatibility": {
|
||||
"ok": true,
|
||||
"product": "FrameBridge",
|
||||
"version": "0.3.1",
|
||||
"guide_schema": 1,
|
||||
"topic": "compatibility",
|
||||
"title": "Compatibility with earlier commands",
|
||||
"sections": [
|
||||
{
|
||||
"heading": "Preferred spelling",
|
||||
"body": "Use the short canonical interface in new documentation and automation. fb and framebridge remain equivalent. Older connect chatgpt, disconnect chatgpt and connection status spellings are compatibility routes. New status scopes replace the need to learn an extra connection noun.",
|
||||
"commands": [
|
||||
"fb connect",
|
||||
"fb disconnect",
|
||||
"fb status connection"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Legacy lifecycle behavior",
|
||||
"body": "Older root start/stop and autostart commands are retained for compatibility where documented, but their historical scopes can differ from the canonical service controls. In particular, legacy autostart disable removes managed setup and saved encrypted material; it is not an alias for boot-policy-only disable. Read the command's help before using a legacy script.",
|
||||
"commands": [
|
||||
"fb help lifecycle"
|
||||
]
|
||||
},
|
||||
{
|
||||
"heading": "Versioned help",
|
||||
"body": "This guide describes the installed product and guide schema. Read the matching release notes for any semantic migration. The CLI help, MCP guide and static web documentation are generated from the same reviewed guide data; a cached manual from an earlier build can describe a different workflow.",
|
||||
"commands": [
|
||||
"fb help compatibility"
|
||||
]
|
||||
}
|
||||
],
|
||||
"topics": [
|
||||
"start",
|
||||
"commands",
|
||||
"connection",
|
||||
"lifecycle",
|
||||
"nodes",
|
||||
"terminals",
|
||||
"screens",
|
||||
"diagnostics",
|
||||
"security",
|
||||
"compatibility"
|
||||
],
|
||||
"read_only": true,
|
||||
"capabilities_verified": false,
|
||||
"guide_sha256": "a6aa6d12e37563866404fa5834bdd7e758f3782a93b59d454316a8c9359b7258"
|
||||
}
|
||||
},
|
||||
"guide_sha256": "504c010697017b50b26de89f793944072ca214ae92d772e8e282ad44a6645634"
|
||||
}
|
||||
@@ -0,0 +1,404 @@
|
||||
# FrameBridge — command guide
|
||||
|
||||
Version: 0.3.1 | Guide schema: 1
|
||||
|
||||
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Start with FrameBridge](#1-start)
|
||||
2. [Command reference](#2-commands)
|
||||
3. [Connect and disconnect ChatGPT](#3-connection)
|
||||
4. [Services, connection intent and boot policy](#4-lifecycle)
|
||||
5. [Central and node operation](#5-nodes)
|
||||
6. [Persistent Bash terminals](#6-terminals)
|
||||
7. [Authentic screen observation and input](#7-screens)
|
||||
8. [Status and diagnosis](#8-diagnostics)
|
||||
9. [Authorization, distribution and safe operation](#9-security)
|
||||
10. [Compatibility with earlier commands](#10-compatibility)
|
||||
|
||||
<a id="1-start"></a>
|
||||
|
||||
## 1. Start with FrameBridge
|
||||
|
||||
### One interface for people and agents
|
||||
|
||||
FrameBridge provides tools and a shared command-line interface for human operators and authorized agents. fb is the short name for framebridge; both run the same program. The tools run on your Linux computers. The ChatGPT model remains hosted. Read this guide for the installed version before operating; confirm the receiver, target and available capabilities. Use the installed CLI and tools for normal work. Edit software only when the owner explicitly requests development, using a separate source clone and reviewable changes rather than rewriting the installed program.
|
||||
|
||||
~~~sh
|
||||
fb help
|
||||
fb status
|
||||
fb --json status
|
||||
~~~
|
||||
|
||||
### Install and connect
|
||||
|
||||
On a supported Debian system, install the downloaded package with the package manager. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal. Advanced setup is optional for selecting central/node roles and public settings.
|
||||
|
||||
~~~sh
|
||||
sudo apt install ./FrameBridge-0.3.1.deb
|
||||
fb connect
|
||||
~~~
|
||||
|
||||
### Updating and removal
|
||||
|
||||
Install an official update through the normal package manager. Normal package removal stops package-owned managed processes and retains the profile and saved encrypted connection material for deliberate reuse; it is not a credential-forgetting operation. Use the separately documented explicit forget action first if that is your intended outcome. Do not assume purge erases user-profile data.
|
||||
|
||||
~~~sh
|
||||
sudo dpkg --remove framebridge-original-expanded
|
||||
~~~
|
||||
|
||||
### Human authentication
|
||||
|
||||
The normal connection asks for an optional account label, a hidden tunnel ID and a hidden MCP server access key. The label is metadata, not proof of ChatGPT login. Browser login/consent and normal operating-system authentication remain human actions in the normal interface. Never put credentials in chat, command arguments, documentation or example files. A successful managed connection returns to the prompt and can run independently of that terminal. Reboot only when an actual system change requires it.
|
||||
|
||||
### Choose the right guide
|
||||
|
||||
Use commands for the reference, connection and lifecycle for state changes, nodes for central/node work, terminals for persistent Bash, and screens for authentic CUA evidence. Query success alone does not mean the connection is ready. The guide describes registered operations; use status/doctor to investigate current state.
|
||||
|
||||
~~~sh
|
||||
fb help commands
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
|
||||
<a id="2-commands"></a>
|
||||
|
||||
## 2. Command reference
|
||||
|
||||
### Everyday commands
|
||||
|
||||
connect establishes or resumes the managed ChatGPT connection. disconnect pauses that connection until an explicit connect, including across recovery and reboot. status reports runtime, connection, intended connection state and boot policy. doctor diagnoses prerequisites/problems. setup edits advanced stopped-profile settings. console opens the text work view. help reads this versioned reference.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
fb status console
|
||||
fb doctor
|
||||
fb setup
|
||||
fb console
|
||||
fb help
|
||||
~~~
|
||||
|
||||
### Services and boot
|
||||
|
||||
For an already configured managed profile, service start/stop control the current stack symmetrically. Boot enable/disable changes future startup policy without stopping current work or forgetting the saved credential. First node provisioning is an explicit exception described in lifecycle. Without managed setup, non-node service start starts local tools only; normal first connection should use connect. Read status before and after changes. The separate credentials forget action is destructive and requires explicit confirmation.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service stop
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
~~~
|
||||
|
||||
### Console and specialized operations
|
||||
|
||||
console login manages optional work-view opening after an authenticated tty1 login; it does not enable automatic login. tty service manages the terminal daemon; tty list lists sessions. nodes, certificates and screen-access retain their domain-specific subcommands. Use --help at the relevant command for its exact arguments. Avoid compatibility aliases in new automation.
|
||||
|
||||
~~~sh
|
||||
fb console login status
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb nodes --help
|
||||
fb certificates --help
|
||||
fb screen-access --help
|
||||
~~~
|
||||
|
||||
### Human and structured output
|
||||
|
||||
Use explicit commands in automation rather than the interactive no-argument menu. --json selects structured output for an agent; examine operation success, readiness and state separately. Read errors and the exit status. If human interaction is required, complete it in the normal terminal/interface rather than attempting to supply a secret through the agent. CLI JSON uses an envelope with schema_version, product, version, command, ok and result. Read runtime, connection and boot truth inside result; envelope ok denotes request success. Exit 0 means successful query/operation, not necessarily a connected transport; exit 1 reports operation/diagnostic failure, exit 2 invalid arguments or required human interaction/confirmation, and exit 130 cancellation.
|
||||
|
||||
~~~sh
|
||||
framebridge --json status
|
||||
fb --json status connection
|
||||
~~~
|
||||
|
||||
|
||||
<a id="3-connection"></a>
|
||||
|
||||
## 3. Connect and disconnect ChatGPT
|
||||
|
||||
### Normal managed connection
|
||||
|
||||
connect creates the default standalone profile when absent and establishes managed startup. It asks for initial human input in the terminal, checks progress, reports readiness or an actionable failure, and returns to the prompt. Valid saved setup can be resumed without repeating the initial fields. The MCP access key is not an OpenAI API key. Keep the browser's ChatGPT account login and consent separate from the optional local account label.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Saved credentials and next boot
|
||||
|
||||
Managed startup uses protected, host-bound encrypted connection material. The normal terminal does not have to remain open. This is a persistence feature, not a promise that an account, network or tunnel service can never fail. Connection intent and boot policy are separate: enabled startup runs the stack at boot, while an intentional disconnected state remains disconnected until connect.
|
||||
|
||||
~~~sh
|
||||
fb status boot
|
||||
fb status
|
||||
~~~
|
||||
|
||||
### Intentional disconnect
|
||||
|
||||
disconnect keeps local tools and saved material, but records the intention to stay disconnected across worker recovery and reboot. Explicit connect clears that pause. Check the returned state rather than interpreting a successful query as an active transport.
|
||||
|
||||
~~~sh
|
||||
fb disconnect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Replacement and temporary foreground mode
|
||||
|
||||
Use connect --replace only when deliberately replacing the account label/tunnel/access configuration. The advanced --foreground mode is temporary, needs a ready local runtime and occupies its terminal until interrupted; it is not the normal managed workflow. Do not use advanced mode merely to recover a normal saved connection.
|
||||
|
||||
|
||||
<a id="4-lifecycle"></a>
|
||||
|
||||
## 4. Services, connection intent and boot policy
|
||||
|
||||
### Separate states
|
||||
|
||||
FrameBridge distinguishes actual local runtime, desired connection, verified transport, boot enablement and saved credential presence. A healthy runtime can be intentionally disconnected; a service can be active while disabled for the next boot. Read the labelled status fields together.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb --json status
|
||||
~~~
|
||||
|
||||
### Current managed stack
|
||||
|
||||
For an already configured managed profile, service start and service stop use the same current-stack boundary without changing boot enablement. Stop ends current managed work and transport but keeps profile, boot policy and saved material. Startup on the next boot follows the retained policy and intended connection state. A non-node profile without managed setup starts only local tools. Stopping a terminal service or session can interrupt its running work.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service stop
|
||||
~~~
|
||||
|
||||
### Future boot policy
|
||||
|
||||
Once managed setup exists, service boot enable/disable changes unit enablement only. It does not immediately stop or start current work and does not delete saved connection material. Initial node provisioning is described separately below. Explicitly forgetting saved material is a separate destructive operation. Legacy autostart disable has its old broader destructive behavior; use the canonical service boot commands for new workflows.
|
||||
|
||||
~~~sh
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### First managed startup for a node
|
||||
|
||||
After advanced node setup and the required enrollment/approval, a node without a managed installation can run service start in a normal terminal. This first call creates managed startup, enables future boot and starts the node now; the result explicitly reports initial_configuration and boot_policy_changed. Alternatively, first service boot enable prepares and enables the node unit without starting current work. Initial preparation can require normal owner authentication and is not silently performed by an unattended JSON request. Once configured, the ordinary start/stop and boot-policy-only contracts apply. A node does not need its own ChatGPT tunnel.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service boot enable
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### Console opening
|
||||
|
||||
Opening console is a view operation, separate from Linux service startup. Optional console login enable/disable changes the owned startup hook after an authenticated tty1 Bash login. This hook does not bypass normal login. Review the command's scope before changing it.
|
||||
|
||||
~~~sh
|
||||
fb console login status
|
||||
~~~
|
||||
|
||||
|
||||
<a id="5-nodes"></a>
|
||||
|
||||
## 5. Central and node operation
|
||||
|
||||
### Roles
|
||||
|
||||
Standalone provides local tools. Central adds the broker for enrolled nodes. A node joins one selected central instance and uses its ChatGPT connection; it does not need another ChatGPT tunnel or phone pairing. Advanced setup selects the role. Preserve explicit authenticated node transport and real identity approval.
|
||||
|
||||
~~~sh
|
||||
fb setup
|
||||
fb nodes --help
|
||||
~~~
|
||||
|
||||
### Enrollment is not availability
|
||||
|
||||
Enrollment submission, central approval, node receipt of authorization and a running node agent are separate stages. status reports what it actually knows; an unchecked agent is not evidence that the node is online. Central list/pending/approve and node enroll/poll/status/run have role-specific purposes. poll can complete saved authorization; it is not a purely observational operation. After enrollment, consult the lifecycle topic for first managed node startup and its explicit initial boot-policy effect.
|
||||
|
||||
~~~sh
|
||||
fb nodes list
|
||||
fb nodes pending
|
||||
fb nodes status
|
||||
~~~
|
||||
|
||||
### Targets
|
||||
|
||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||
|
||||
### Transport trust
|
||||
|
||||
certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.
|
||||
|
||||
~~~sh
|
||||
fb certificates --help
|
||||
~~~
|
||||
|
||||
|
||||
<a id="6-terminals"></a>
|
||||
|
||||
## 6. Persistent Bash terminals
|
||||
|
||||
### Service and sessions
|
||||
|
||||
tty service controls the profile's terminal daemon. tty open creates a real Bash session and returns its identifier. Use that identifier for subsequent observations and input. The same Bash preserves directory, variables and work between requests while the session/service remains alive. It does not preserve running processes across an operating-system reboot. Tool jobs use a profile-specific HOME; a job's home directory can therefore differ from the human login home. Commands retain the connecting account's normal operating-system permissions.
|
||||
|
||||
~~~sh
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb tty open
|
||||
~~~
|
||||
|
||||
### Observe, type and keys
|
||||
|
||||
tty observe returns terminal transcript text, cursor, dimensions and process state; it is not an authentic full-screen image. tty type sends text without automatically adding Enter, though supplied newlines can affect execution. tty key accepts exact uppercase names such as ENTER and CTRL_C. Replace session arguments with an identifier returned by open/list; never guess one.
|
||||
|
||||
~~~sh
|
||||
fb tty key --help
|
||||
fb tty type --help
|
||||
fb tty observe --help
|
||||
~~~
|
||||
|
||||
### Lifetime and closing
|
||||
|
||||
Default real idle expiry is disabled, but a profile can configure a timeout. Global status/list does not refresh each session's per-session activity. close destroys a session rather than merely separating a viewer. Graceful service stop attempts to close its sessions; elevated or unverifiable process state can prevent cleanup. Inspect the outcome instead of assuming that all child processes disappeared.
|
||||
|
||||
~~~sh
|
||||
fb tty close --help
|
||||
fb tty resize --help
|
||||
~~~
|
||||
|
||||
### Sudo mode
|
||||
|
||||
A session's sudo on/off controls normal privilege eligibility; it does not log in as root or bypass operating-system authentication. Changing the mode recreates Bash, preserving directory and dimensions but not shell variables or internal state. Authentication stays in the normal human terminal/interface. Never send a password through type or chat.
|
||||
|
||||
~~~sh
|
||||
fb tty sudo --help
|
||||
~~~
|
||||
|
||||
### Work console panels
|
||||
|
||||
console combines an ordinary Bash pane with a read-only FBTERM activity dashboard. The dashboard is not a second interactive shell. The tmux prefix is Ctrl+B: release both keys, then press lowercase z to enlarge/restore a pane, or lowercase o to switch panes. The release accepts common zoom-key variants within its dedicated console. Closing a viewer normally leaves its tmux session alive; leaving Bash, killing its server or rebooting is different. In a desktop terminal the shared work view is horizontal with FBTERM on the left and Bash on the right. Explicit TTY mode is vertical with a short FBTERM monitor above Bash. The layout belongs to the shared tmux window and follows the last requested view mode; it is not isolated per viewer.
|
||||
|
||||
~~~sh
|
||||
fb console
|
||||
fb status console
|
||||
~~~
|
||||
|
||||
|
||||
<a id="7-screens"></a>
|
||||
|
||||
## 7. Authentic screen observation and input
|
||||
|
||||
### Text transcripts and pixels
|
||||
|
||||
A CLI tty transcript describes a terminal and explicitly does not claim authentic pixels. MCP real-screen CUA-TTY and graphical screen tools operate through the real screen client and capture-linked interaction. Use those supported observation tools when authentic complete screen evidence is required. Never present a reconstructed terminal, animation or partial invented view as a real screenshot.
|
||||
|
||||
### Automatic graphical discovery
|
||||
|
||||
The installer and control console stay text interfaces in both TTY and a desktop terminal. Compatible graphical CUA is discovered automatically; availability depends on the actual display/session and permissions. A loaded module is not proof that real pixel capture or input succeeded. New profiles use adaptive auto mode: without a verified active X11 session the runtime provides FBEXEC, FBTERM and CUA-TTY in text mode, without requiring a graphical login or automatically creating a private desktop. Explicit virtual-desktop settings remain advanced options and are labelled separately from physical-screen evidence.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb doctor
|
||||
~~~
|
||||
|
||||
### Frame-buffer read access
|
||||
|
||||
screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication.
|
||||
|
||||
~~~sh
|
||||
fb screen-access status
|
||||
~~~
|
||||
|
||||
### Shared desktop
|
||||
|
||||
A graphical desktop shares focus, keyboard and mouse. Use one controlling agent per desktop at a time and avoid overlapping work. This is an operating recommendation, not a claim of certified automatic isolation. Independent non-overlapping execution jobs may be possible; do not infer isolation or physical parallel execution from that alone.
|
||||
|
||||
|
||||
<a id="8-diagnostics"></a>
|
||||
|
||||
## 8. Status and diagnosis
|
||||
|
||||
### Inspect before acting
|
||||
|
||||
status summarizes current runtime, connection, desired state and boot policy. A query completing successfully is distinct from the components being ready. Connection verification has a freshness boundary; retrying or unknown must not be treated as connected. Focused status uses the same underlying state model.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### Doctor
|
||||
|
||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes.
|
||||
|
||||
~~~sh
|
||||
fb doctor
|
||||
~~~
|
||||
|
||||
### Logs and progress
|
||||
|
||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||
|
||||
~~~sh
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
|
||||
<a id="9-security"></a>
|
||||
|
||||
## 9. Authorization, distribution and safe operation
|
||||
|
||||
### Authorized scope
|
||||
|
||||
An agent can use the documented CLI and MCP tools within the user's authorized scope. Reading this guide does not grant permission. Verify the receiver and selected target. Normal human terminal/browser authentication remains separate; do not request credentials in chat or invent phone/Owner-TTY enrollment requirements. Normal use should operate through the installed CLI and tools, not edit or rebuild installed FrameBridge program files. If the owner explicitly requests development, use a separate source clone, make reviewable changes, and do not present a modified build as an official release. This operating guidance does not restrict GNU GPL freedoms or require private forks to submit changes upstream.
|
||||
|
||||
### Official releases
|
||||
|
||||
The source is distributed under GNU GPLv3-only terms and the applicable third-party notices. Verify official release checksums and published signatures/repository metadata before installing. Signature verification identifies the publisher and detects alteration; it does not prohibit lawful modified versions. Official releases are reviewed through the project's release process.
|
||||
|
||||
### Side effects
|
||||
|
||||
Read status before service stop, credential forgetting, node approval, startup-hook changes or administrative screen permission changes. Explain material scope and consequences and follow the user's authorization. A sensitive operation must report the actual result, not just that a query succeeded. Keep real captures complete and distinguish observations from hypotheses.
|
||||
|
||||
|
||||
<a id="10-compatibility"></a>
|
||||
|
||||
## 10. Compatibility with earlier commands
|
||||
|
||||
### Preferred spelling
|
||||
|
||||
Use the short canonical interface in new documentation and automation. fb and framebridge remain equivalent. Older connect chatgpt, disconnect chatgpt and connection status spellings are compatibility routes. New status scopes replace the need to learn an extra connection noun.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Legacy lifecycle behavior
|
||||
|
||||
Older root start/stop and autostart commands are retained for compatibility where documented, but their historical scopes can differ from the canonical service controls. In particular, legacy autostart disable removes managed setup and saved encrypted material; it is not an alias for boot-policy-only disable. Read the command's help before using a legacy script.
|
||||
|
||||
~~~sh
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
### Versioned help
|
||||
|
||||
This guide describes the installed product and guide schema. Read the matching release notes for any semantic migration. The CLI help, MCP guide and static web documentation are generated from the same reviewed guide data; a cached manual from an earlier build can describe a different workflow.
|
||||
|
||||
~~~sh
|
||||
fb help compatibility
|
||||
~~~
|
||||
@@ -0,0 +1,404 @@
|
||||
# FrameBridge — Debian installation and first use
|
||||
|
||||
Version: 0.3.1 | Guide schema: 1
|
||||
|
||||
This reference is generated from the shared CLI/MCP guide. Use the matching installed version.
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Start with FrameBridge](#1-start)
|
||||
2. [Command reference](#2-commands)
|
||||
3. [Connect and disconnect ChatGPT](#3-connection)
|
||||
4. [Services, connection intent and boot policy](#4-lifecycle)
|
||||
5. [Central and node operation](#5-nodes)
|
||||
6. [Persistent Bash terminals](#6-terminals)
|
||||
7. [Authentic screen observation and input](#7-screens)
|
||||
8. [Status and diagnosis](#8-diagnostics)
|
||||
9. [Authorization, distribution and safe operation](#9-security)
|
||||
10. [Compatibility with earlier commands](#10-compatibility)
|
||||
|
||||
<a id="1-start"></a>
|
||||
|
||||
## 1. Start with FrameBridge
|
||||
|
||||
### One interface for people and agents
|
||||
|
||||
FrameBridge provides tools and a shared command-line interface for human operators and authorized agents. fb is the short name for framebridge; both run the same program. The tools run on your Linux computers. The ChatGPT model remains hosted. Read this guide for the installed version before operating; confirm the receiver, target and available capabilities. Use the installed CLI and tools for normal work. Edit software only when the owner explicitly requests development, using a separate source clone and reviewable changes rather than rewriting the installed program.
|
||||
|
||||
~~~sh
|
||||
fb help
|
||||
fb status
|
||||
fb --json status
|
||||
~~~
|
||||
|
||||
### Install and connect
|
||||
|
||||
On a supported Debian system, install the downloaded package with the package manager. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal. Advanced setup is optional for selecting central/node roles and public settings.
|
||||
|
||||
~~~sh
|
||||
sudo apt install ./FrameBridge-0.3.1.deb
|
||||
fb connect
|
||||
~~~
|
||||
|
||||
### Updating and removal
|
||||
|
||||
Install an official update through the normal package manager. Normal package removal stops package-owned managed processes and retains the profile and saved encrypted connection material for deliberate reuse; it is not a credential-forgetting operation. Use the separately documented explicit forget action first if that is your intended outcome. Do not assume purge erases user-profile data.
|
||||
|
||||
~~~sh
|
||||
sudo dpkg --remove framebridge-original-expanded
|
||||
~~~
|
||||
|
||||
### Human authentication
|
||||
|
||||
The normal connection asks for an optional account label, a hidden tunnel ID and a hidden MCP server access key. The label is metadata, not proof of ChatGPT login. Browser login/consent and normal operating-system authentication remain human actions in the normal interface. Never put credentials in chat, command arguments, documentation or example files. A successful managed connection returns to the prompt and can run independently of that terminal. Reboot only when an actual system change requires it.
|
||||
|
||||
### Choose the right guide
|
||||
|
||||
Use commands for the reference, connection and lifecycle for state changes, nodes for central/node work, terminals for persistent Bash, and screens for authentic CUA evidence. Query success alone does not mean the connection is ready. The guide describes registered operations; use status/doctor to investigate current state.
|
||||
|
||||
~~~sh
|
||||
fb help commands
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
|
||||
<a id="2-commands"></a>
|
||||
|
||||
## 2. Command reference
|
||||
|
||||
### Everyday commands
|
||||
|
||||
connect establishes or resumes the managed ChatGPT connection. disconnect pauses that connection until an explicit connect, including across recovery and reboot. status reports runtime, connection, intended connection state and boot policy. doctor diagnoses prerequisites/problems. setup edits advanced stopped-profile settings. console opens the text work view. help reads this versioned reference.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
fb status console
|
||||
fb doctor
|
||||
fb setup
|
||||
fb console
|
||||
fb help
|
||||
~~~
|
||||
|
||||
### Services and boot
|
||||
|
||||
For an already configured managed profile, service start/stop control the current stack symmetrically. Boot enable/disable changes future startup policy without stopping current work or forgetting the saved credential. First node provisioning is an explicit exception described in lifecycle. Without managed setup, non-node service start starts local tools only; normal first connection should use connect. Read status before and after changes. The separate credentials forget action is destructive and requires explicit confirmation.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service stop
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
~~~
|
||||
|
||||
### Console and specialized operations
|
||||
|
||||
console login manages optional work-view opening after an authenticated tty1 login; it does not enable automatic login. tty service manages the terminal daemon; tty list lists sessions. nodes, certificates and screen-access retain their domain-specific subcommands. Use --help at the relevant command for its exact arguments. Avoid compatibility aliases in new automation.
|
||||
|
||||
~~~sh
|
||||
fb console login status
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb nodes --help
|
||||
fb certificates --help
|
||||
fb screen-access --help
|
||||
~~~
|
||||
|
||||
### Human and structured output
|
||||
|
||||
Use explicit commands in automation rather than the interactive no-argument menu. --json selects structured output for an agent; examine operation success, readiness and state separately. Read errors and the exit status. If human interaction is required, complete it in the normal terminal/interface rather than attempting to supply a secret through the agent. CLI JSON uses an envelope with schema_version, product, version, command, ok and result. Read runtime, connection and boot truth inside result; envelope ok denotes request success. Exit 0 means successful query/operation, not necessarily a connected transport; exit 1 reports operation/diagnostic failure, exit 2 invalid arguments or required human interaction/confirmation, and exit 130 cancellation.
|
||||
|
||||
~~~sh
|
||||
framebridge --json status
|
||||
fb --json status connection
|
||||
~~~
|
||||
|
||||
|
||||
<a id="3-connection"></a>
|
||||
|
||||
## 3. Connect and disconnect ChatGPT
|
||||
|
||||
### Normal managed connection
|
||||
|
||||
connect creates the default standalone profile when absent and establishes managed startup. It asks for initial human input in the terminal, checks progress, reports readiness or an actionable failure, and returns to the prompt. Valid saved setup can be resumed without repeating the initial fields. The MCP access key is not an OpenAI API key. Keep the browser's ChatGPT account login and consent separate from the optional local account label.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Saved credentials and next boot
|
||||
|
||||
Managed startup uses protected, host-bound encrypted connection material. The normal terminal does not have to remain open. This is a persistence feature, not a promise that an account, network or tunnel service can never fail. Connection intent and boot policy are separate: enabled startup runs the stack at boot, while an intentional disconnected state remains disconnected until connect.
|
||||
|
||||
~~~sh
|
||||
fb status boot
|
||||
fb status
|
||||
~~~
|
||||
|
||||
### Intentional disconnect
|
||||
|
||||
disconnect keeps local tools and saved material, but records the intention to stay disconnected across worker recovery and reboot. Explicit connect clears that pause. Check the returned state rather than interpreting a successful query as an active transport.
|
||||
|
||||
~~~sh
|
||||
fb disconnect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Replacement and temporary foreground mode
|
||||
|
||||
Use connect --replace only when deliberately replacing the account label/tunnel/access configuration. The advanced --foreground mode is temporary, needs a ready local runtime and occupies its terminal until interrupted; it is not the normal managed workflow. Do not use advanced mode merely to recover a normal saved connection.
|
||||
|
||||
|
||||
<a id="4-lifecycle"></a>
|
||||
|
||||
## 4. Services, connection intent and boot policy
|
||||
|
||||
### Separate states
|
||||
|
||||
FrameBridge distinguishes actual local runtime, desired connection, verified transport, boot enablement and saved credential presence. A healthy runtime can be intentionally disconnected; a service can be active while disabled for the next boot. Read the labelled status fields together.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb --json status
|
||||
~~~
|
||||
|
||||
### Current managed stack
|
||||
|
||||
For an already configured managed profile, service start and service stop use the same current-stack boundary without changing boot enablement. Stop ends current managed work and transport but keeps profile, boot policy and saved material. Startup on the next boot follows the retained policy and intended connection state. A non-node profile without managed setup starts only local tools. Stopping a terminal service or session can interrupt its running work.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service stop
|
||||
~~~
|
||||
|
||||
### Future boot policy
|
||||
|
||||
Once managed setup exists, service boot enable/disable changes unit enablement only. It does not immediately stop or start current work and does not delete saved connection material. Initial node provisioning is described separately below. Explicitly forgetting saved material is a separate destructive operation. Legacy autostart disable has its old broader destructive behavior; use the canonical service boot commands for new workflows.
|
||||
|
||||
~~~sh
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### First managed startup for a node
|
||||
|
||||
After advanced node setup and the required enrollment/approval, a node without a managed installation can run service start in a normal terminal. This first call creates managed startup, enables future boot and starts the node now; the result explicitly reports initial_configuration and boot_policy_changed. Alternatively, first service boot enable prepares and enables the node unit without starting current work. Initial preparation can require normal owner authentication and is not silently performed by an unattended JSON request. Once configured, the ordinary start/stop and boot-policy-only contracts apply. A node does not need its own ChatGPT tunnel.
|
||||
|
||||
~~~sh
|
||||
fb service start
|
||||
fb service boot enable
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### Console opening
|
||||
|
||||
Opening console is a view operation, separate from Linux service startup. Optional console login enable/disable changes the owned startup hook after an authenticated tty1 Bash login. This hook does not bypass normal login. Review the command's scope before changing it.
|
||||
|
||||
~~~sh
|
||||
fb console login status
|
||||
~~~
|
||||
|
||||
|
||||
<a id="5-nodes"></a>
|
||||
|
||||
## 5. Central and node operation
|
||||
|
||||
### Roles
|
||||
|
||||
Standalone provides local tools. Central adds the broker for enrolled nodes. A node joins one selected central instance and uses its ChatGPT connection; it does not need another ChatGPT tunnel or phone pairing. Advanced setup selects the role. Preserve explicit authenticated node transport and real identity approval.
|
||||
|
||||
~~~sh
|
||||
fb setup
|
||||
fb nodes --help
|
||||
~~~
|
||||
|
||||
### Enrollment is not availability
|
||||
|
||||
Enrollment submission, central approval, node receipt of authorization and a running node agent are separate stages. status reports what it actually knows; an unchecked agent is not evidence that the node is online. Central list/pending/approve and node enroll/poll/status/run have role-specific purposes. poll can complete saved authorization; it is not a purely observational operation. After enrollment, consult the lifecycle topic for first managed node startup and its explicit initial boot-policy effect.
|
||||
|
||||
~~~sh
|
||||
fb nodes list
|
||||
fb nodes pending
|
||||
fb nodes status
|
||||
~~~
|
||||
|
||||
### Targets
|
||||
|
||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty --node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||
|
||||
### Transport trust
|
||||
|
||||
certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.
|
||||
|
||||
~~~sh
|
||||
fb certificates --help
|
||||
~~~
|
||||
|
||||
|
||||
<a id="6-terminals"></a>
|
||||
|
||||
## 6. Persistent Bash terminals
|
||||
|
||||
### Service and sessions
|
||||
|
||||
tty service controls the profile's terminal daemon. tty open creates a real Bash session and returns its identifier. Use that identifier for subsequent observations and input. The same Bash preserves directory, variables and work between requests while the session/service remains alive. It does not preserve running processes across an operating-system reboot. Tool jobs use a profile-specific HOME; a job's home directory can therefore differ from the human login home. Commands retain the connecting account's normal operating-system permissions.
|
||||
|
||||
~~~sh
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb tty open
|
||||
~~~
|
||||
|
||||
### Observe, type and keys
|
||||
|
||||
tty observe returns terminal transcript text, cursor, dimensions and process state; it is not an authentic full-screen image. tty type sends text without automatically adding Enter, though supplied newlines can affect execution. tty key accepts exact uppercase names such as ENTER and CTRL_C. Replace session arguments with an identifier returned by open/list; never guess one.
|
||||
|
||||
~~~sh
|
||||
fb tty key --help
|
||||
fb tty type --help
|
||||
fb tty observe --help
|
||||
~~~
|
||||
|
||||
### Lifetime and closing
|
||||
|
||||
Default real idle expiry is disabled, but a profile can configure a timeout. Global status/list does not refresh each session's per-session activity. close destroys a session rather than merely separating a viewer. Graceful service stop attempts to close its sessions; elevated or unverifiable process state can prevent cleanup. Inspect the outcome instead of assuming that all child processes disappeared.
|
||||
|
||||
~~~sh
|
||||
fb tty close --help
|
||||
fb tty resize --help
|
||||
~~~
|
||||
|
||||
### Sudo mode
|
||||
|
||||
A session's sudo on/off controls normal privilege eligibility; it does not log in as root or bypass operating-system authentication. Changing the mode recreates Bash, preserving directory and dimensions but not shell variables or internal state. Authentication stays in the normal human terminal/interface. Never send a password through type or chat.
|
||||
|
||||
~~~sh
|
||||
fb tty sudo --help
|
||||
~~~
|
||||
|
||||
### Work console panels
|
||||
|
||||
console combines an ordinary Bash pane with a read-only FBTERM activity dashboard. The dashboard is not a second interactive shell. The tmux prefix is Ctrl+B: release both keys, then press lowercase z to enlarge/restore a pane, or lowercase o to switch panes. The release accepts common zoom-key variants within its dedicated console. Closing a viewer normally leaves its tmux session alive; leaving Bash, killing its server or rebooting is different. In a desktop terminal the shared work view is horizontal with FBTERM on the left and Bash on the right. Explicit TTY mode is vertical with a short FBTERM monitor above Bash. The layout belongs to the shared tmux window and follows the last requested view mode; it is not isolated per viewer.
|
||||
|
||||
~~~sh
|
||||
fb console
|
||||
fb status console
|
||||
~~~
|
||||
|
||||
|
||||
<a id="7-screens"></a>
|
||||
|
||||
## 7. Authentic screen observation and input
|
||||
|
||||
### Text transcripts and pixels
|
||||
|
||||
A CLI tty transcript describes a terminal and explicitly does not claim authentic pixels. MCP real-screen CUA-TTY and graphical screen tools operate through the real screen client and capture-linked interaction. Use those supported observation tools when authentic complete screen evidence is required. Never present a reconstructed terminal, animation or partial invented view as a real screenshot.
|
||||
|
||||
### Automatic graphical discovery
|
||||
|
||||
The installer and control console stay text interfaces in both TTY and a desktop terminal. Compatible graphical CUA is discovered automatically; availability depends on the actual display/session and permissions. A loaded module is not proof that real pixel capture or input succeeded. New profiles use adaptive auto mode: without a verified active X11 session the runtime provides FBEXEC, FBTERM and CUA-TTY in text mode, without requiring a graphical login or automatically creating a private desktop. Explicit virtual-desktop settings remain advanced options and are labelled separately from physical-screen evidence.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb doctor
|
||||
~~~
|
||||
|
||||
### Frame-buffer read access
|
||||
|
||||
screen-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication.
|
||||
|
||||
~~~sh
|
||||
fb screen-access status
|
||||
~~~
|
||||
|
||||
### Shared desktop
|
||||
|
||||
A graphical desktop shares focus, keyboard and mouse. Use one controlling agent per desktop at a time and avoid overlapping work. This is an operating recommendation, not a claim of certified automatic isolation. Independent non-overlapping execution jobs may be possible; do not infer isolation or physical parallel execution from that alone.
|
||||
|
||||
|
||||
<a id="8-diagnostics"></a>
|
||||
|
||||
## 8. Status and diagnosis
|
||||
|
||||
### Inspect before acting
|
||||
|
||||
status summarizes current runtime, connection, desired state and boot policy. A query completing successfully is distinct from the components being ready. Connection verification has a freshness boundary; retrying or unknown must not be treated as connected. Focused status uses the same underlying state model.
|
||||
|
||||
~~~sh
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
~~~
|
||||
|
||||
### Doctor
|
||||
|
||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes.
|
||||
|
||||
~~~sh
|
||||
fb doctor
|
||||
~~~
|
||||
|
||||
### Logs and progress
|
||||
|
||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||
|
||||
~~~sh
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
|
||||
<a id="9-security"></a>
|
||||
|
||||
## 9. Authorization, distribution and safe operation
|
||||
|
||||
### Authorized scope
|
||||
|
||||
An agent can use the documented CLI and MCP tools within the user's authorized scope. Reading this guide does not grant permission. Verify the receiver and selected target. Normal human terminal/browser authentication remains separate; do not request credentials in chat or invent phone/Owner-TTY enrollment requirements. Normal use should operate through the installed CLI and tools, not edit or rebuild installed FrameBridge program files. If the owner explicitly requests development, use a separate source clone, make reviewable changes, and do not present a modified build as an official release. This operating guidance does not restrict GNU GPL freedoms or require private forks to submit changes upstream.
|
||||
|
||||
### Official releases
|
||||
|
||||
The source is distributed under GNU GPLv3-only terms and the applicable third-party notices. Verify official release checksums and published signatures/repository metadata before installing. Signature verification identifies the publisher and detects alteration; it does not prohibit lawful modified versions. Official releases are reviewed through the project's release process.
|
||||
|
||||
### Side effects
|
||||
|
||||
Read status before service stop, credential forgetting, node approval, startup-hook changes or administrative screen permission changes. Explain material scope and consequences and follow the user's authorization. A sensitive operation must report the actual result, not just that a query succeeded. Keep real captures complete and distinguish observations from hypotheses.
|
||||
|
||||
|
||||
<a id="10-compatibility"></a>
|
||||
|
||||
## 10. Compatibility with earlier commands
|
||||
|
||||
### Preferred spelling
|
||||
|
||||
Use the short canonical interface in new documentation and automation. fb and framebridge remain equivalent. Older connect chatgpt, disconnect chatgpt and connection status spellings are compatibility routes. New status scopes replace the need to learn an extra connection noun.
|
||||
|
||||
~~~sh
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status connection
|
||||
~~~
|
||||
|
||||
### Legacy lifecycle behavior
|
||||
|
||||
Older root start/stop and autostart commands are retained for compatibility where documented, but their historical scopes can differ from the canonical service controls. In particular, legacy autostart disable removes managed setup and saved encrypted material; it is not an alias for boot-policy-only disable. Read the command's help before using a legacy script.
|
||||
|
||||
~~~sh
|
||||
fb help lifecycle
|
||||
~~~
|
||||
|
||||
### Versioned help
|
||||
|
||||
This guide describes the installed product and guide schema. Read the matching release notes for any semantic migration. The CLI help, MCP guide and static web documentation are generated from the same reviewed guide data; a cached manual from an earlier build can describe a different workflow.
|
||||
|
||||
~~~sh
|
||||
fb help compatibility
|
||||
~~~
|
||||
@@ -0,0 +1,103 @@
|
||||
# FrameBridge Original Expanded — R2 additions
|
||||
|
||||
Date: 2026-10-23
|
||||
Package series: 0.3.0~expanded.20261023
|
||||
|
||||
> Historical R2 record. Community Preview 4 and later change the default adaptive desktop behavior: auto uses a verified physical X11 session when available and otherwise starts text-mode FBEXEC, FBTERM and CUA-TTY, without automatically creating Xvfb. Graphical CUA requests in adaptive mode re-check a usable physical session when one becomes available without restarting persistent FBTERM. Explicit headless=yes remains the private virtual-desktop option. The R2 fallback description below records its earlier behavior; use the current [Debian tutorial](DEBIAN-TUTORIAL.md) and [connection lifecycle](../../docs/CONNECTION-STATUS.md) for Preview 4.
|
||||
|
||||
This release integrates the accepted Original features in an isolated package tree. It does not install GPU drivers, kernels, a complete Cinnamon desktop, phone pairing, an Owner Device agent, or a custom privileged authentication service. Product commands and documentation are in English.
|
||||
|
||||
## Open the official console
|
||||
|
||||
After setup, run this as the normal logged-in user:
|
||||
|
||||
```sh
|
||||
fb console
|
||||
```
|
||||
|
||||
The menu entry is **FrameBridge Console**. With an active verified local X11 session, it opens the graphical terminal. From an authenticated text login, it attaches in the current terminal. Both access the same profile-scoped Bash and FBTERM console. Bash is on the left on a wide screen and above the monitor on a narrow screen. Closing a graphical client detaches it; it does not intentionally destroy the persistent session.
|
||||
|
||||
```sh
|
||||
fb console --mode tty
|
||||
fb console --status
|
||||
```
|
||||
|
||||
Ctrl+B, then o changes panes. Ctrl+B, then z zooms or restores a pane. A remote interactive attachment requires an explicitly configured SSH destination; the package never guesses an SSH account or installs an SSH server. Broker-routed remote EXEC, CUA and managed terminal operations remain separate supported interfaces.
|
||||
|
||||
## Optional console after text login
|
||||
|
||||
Opt in explicitly, as the normal user:
|
||||
|
||||
```sh
|
||||
fb console --enable-login
|
||||
fb console --login-status
|
||||
```
|
||||
|
||||
The hook runs only after an authenticated local tty1 login, outside SSH and tmux. It never enables automatic login. The selected existing Bash login file is preserved with an exact backup. Graphical logins and other VTs retain their ordinary startup behavior.
|
||||
|
||||
To restore the saved login file:
|
||||
|
||||
```sh
|
||||
fb console --disable-login
|
||||
```
|
||||
|
||||
Restoration refuses unknown later edits rather than overwriting them. Review those edits before attempting manual recovery.
|
||||
|
||||
## Managed CUA-TTY sudo capability
|
||||
|
||||
Start the profile and open a managed Bash console:
|
||||
|
||||
```sh
|
||||
fb start
|
||||
fb tty open --program bash --rows 30 --cols 100
|
||||
```
|
||||
|
||||
Replace SESSION_ID below with the returned managed console ID. Replace worker-1 with the enrolled node alias when controlling a different node:
|
||||
|
||||
```sh
|
||||
fb tty sudo status SESSION_ID --node LOCAL
|
||||
fb tty sudo on SESSION_ID --node LOCAL
|
||||
fb tty sudo off SESSION_ID --node LOCAL
|
||||
fb tty sudo status SESSION_ID --node worker-1
|
||||
```
|
||||
|
||||
The default managed console has NoNewPrivs=1. Enabling the capability creates a controlled replacement Bash with NoNewPrivs=0 through the normal user's systemd manager. The controller verifies the actual process and server flags. It retains the logical console ID, working directory and geometry. Shell-local variables and functions do not survive a Bash replacement. Busy, elevated, stopped or detached jobs prevent an unsafe transition.
|
||||
|
||||
This is permission to attempt ordinary sudo, not root authentication. The system's normal sudo policy and password prompt still apply. No password is embedded or handled by FrameBridge, and no NOPASSWD entry is created. A normal interactive Bash in the official console remains an ordinary user terminal; its Linux sudo behavior is not a managed CUA-TTY ID.
|
||||
|
||||
## Actual screen images and input
|
||||
|
||||
The physical screen interface captures complete real pixels:
|
||||
|
||||
```text
|
||||
framebridge_cua(action="OBSERVE", authorized=true, capture_scope="node:worker-1")
|
||||
framebridge_screen_observe(node="worker-1", authorized=true)
|
||||
```
|
||||
|
||||
It supports the active owned Linux framebuffer TTY and a verified active X11 session. LightDM's empty TTY field and root session leader are handled by checking the active seat, numeric VT, session, user and private user authority context. Unsupported or unreadable screens fail explicitly; terminal text is never substituted for pixels.
|
||||
|
||||
The seven CUA-TTY MCP tools retain terminal-management operations, but observe returns the actual physical screen. TTY key and text actions require the capture_id and visible screen session ID returned by a real observation. A hidden managed terminal ID is not proof that it is visible. Switching VT, changing the visible pane, or reusing an action's capture invalidates the binding. Use the existing verified graphical CUA for X11 clicks and keyboard input.
|
||||
|
||||
The CLI terminal observation is different: `fb tty observe SESSION_ID` returns a **terminal transcript**, including text, cursor and process data. It is explicitly marked terminal_transcript, authentic_pixels=false and full_screen=false. It is not an image of the physical display.
|
||||
|
||||
## Physical and virtual graphical displays
|
||||
|
||||
In auto mode the runtime prefers a verified active physical X11 session. Its graphical adapter is bound to that display/session. The binding is checked before adapter dispatch, immediately before native X11 operations, and after execution. A changed foreground session invalidates the result. If input may already have been sent, the response states input_may_have_been_sent=true and do_not_replay=true; do not repeat that action automatically.
|
||||
|
||||
Historical R2 behavior: a private Xvfb display is labelled virtual-x11, with physical=false. Selecting headless yes requests such a virtual workspace explicitly. In that version, an auto fallback is also labelled virtual; it is never advertised as the active physical screen. Selecting headless no requires the physical session and refuses a virtual fallback even if the display becomes unavailable after initial validation. Community Preview 4 replaces the implicit auto fallback with text mode as described at the start of this document.
|
||||
|
||||
The node:ALIAS screen interface always resolves the actual active physical screen independently; it does not silently capture the private virtual workspace. Keep this distinction when reporting screenshots or test results.
|
||||
|
||||
## Network diagnosis
|
||||
|
||||
```sh
|
||||
fb doctor
|
||||
```
|
||||
|
||||
The report distinguishes kernel link/address/default-route data from the manager that owns the interface. A working ifupdown Ethernet connection can be unmanaged in NetworkManager; a Cinnamon applet based on NetworkManager may then show disconnected. A default route alone is not proof of Internet or DNS access. The diagnostic does not change interfaces, managers, routes, DNS, firewall or SSH.
|
||||
|
||||
## Release acceptance
|
||||
|
||||
Source and component checks do not certify a fresh installation. The release must also pass clean Debian APT/dpkg installation, actual boot, an authenticated console, physical GUI capture and input, ordinary password-authenticated sudo, and a separate central/node VM enrollment and routing check. The manual ChatGPT connection requires the user's own account consent and secret entry in the real terminal, never in chat.
|
||||
|
||||
The release report and external evidence identify which gates were actually completed. Do not describe a private Xvfb fixture or same-host profiles as an installed physical LightDM session or separate machines.
|
||||
@@ -0,0 +1,56 @@
|
||||
# FrameBridge Original Expanded — RC7 image presentation and lifecycle
|
||||
|
||||
Date: 2026-10-24
|
||||
Candidate: 0.3.0~expanded.20261024.7
|
||||
Status: implementation candidate; release acceptance requires the external report.
|
||||
|
||||
## Connect the central first
|
||||
|
||||
It is valid to install and configure a central, start it, complete its manual ChatGPT connection, and install worker nodes later. The central does not require a worker to publish its local tools. A standalone profile can also connect directly. A node profile joins an approved central and does not publish its own ChatGPT MCP endpoint.
|
||||
|
||||
For a fleet, choose central at the initial setup. Start it and run `fb connect chatgpt`. Enter the tunnel information and runtime key at the hidden local prompts, then select the app and complete ChatGPT consent. The connection client remains in the foreground while the tunnel is active; lack of a new prompt is expected. Keep that terminal open. Browser login is separate from the optional account label.
|
||||
|
||||
When adding another machine later, install the same verified package there and choose node. Use the central's verified HTTPS broker URL and public CA certificate. The node submits enrollment, the central operator compares the identity and approves the matching request, and the node polls before starting. Section 8 of DEBIAN-TUTORIAL.md provides the exact commands. The central resolves the current approved node list for each request, so this workflow does not require reinstalling the central or reconnecting ChatGPT.
|
||||
|
||||
Changing a running central profile to another role is a different operation: stop that profile before editing setup. Installing every worker before connecting ChatGPT is an optional test order, not a product requirement.
|
||||
|
||||
## Display and reopen the same actual screen image
|
||||
|
||||
The existing actual-screen tools retain their contracts:
|
||||
|
||||
- `framebridge_screen_observe` captures a new verified active physical screen.
|
||||
- `framebridge_screen_key` and `framebridge_screen_text` require a valid fresh input binding and return the resulting capture.
|
||||
- `framebridge_screen_show(node, capture_id, authorized)` retrieves an existing saved capture and displays its original PNG.
|
||||
|
||||
Use the node and capture_id returned by observation when calling show. It reads the saved capture on that node, verifies the byte count, PNG dimensions and SHA-256, and returns the original ImageContent plus a structured result for the viewer. It does not run a new capture, open an execution console, send input or consume input authorization. An unavailable or corrupt saved capture produces an error rather than a substitute image.
|
||||
|
||||
The offline MCP Apps viewer is registered as `ui://framebridge/screen-v1.html` with MIME type `text/html;profile=mcp-app`. It receives the original PNG through tool-result metadata and validates integrity before showing it. It provides fit, native-size, fullscreen and exact-PNG download controls, and identifies the node, dimensions and capture hash. A reopened image is labelled saved/historical with control_available=false: viewing an old image does not make it a safe basis for input.
|
||||
|
||||
This UI requires a compatible ChatGPT client and refreshed RC7 app tools. Existing clients still receive the original PNG ImageContent. Tool/resource registration, direct SDK tests and capture backend success do not certify that ChatGPT rendered the image; an actual-account visual check is a separate release gate. The legacy graphical CUA JPEG preview remains capped at width 960 while reporting the true source geometry; that preview is separate from the native actual-screen PNG.
|
||||
|
||||
## Explicit read-only text framebuffer access
|
||||
|
||||
The package includes an inactive udev rule and a root helper. Installation does not enable a grant. The administrator can explicitly select an existing non-root user with:
|
||||
|
||||
```sh
|
||||
fb screen-access status
|
||||
sudo fb screen-access enable --user "$(id -un)"
|
||||
fb screen-access status
|
||||
```
|
||||
|
||||
The command must run from the intended normal user's login. Only the selected user receives a named read-only ACL for the actual `/dev/fb0` graphics framebuffer (major 29, minor 0). Other video devices, device ownership and group ownership are outside its scope. The helper preserves the current ACL mask; if read access would require widening that mask, it refuses the change. No broad video-group membership or passwordless sudo rule is installed.
|
||||
|
||||
The enabled policy under `/etc/framebridge-expanded/screen-access.json` contains the public user identity. Protected recovery data under `/var/lib/framebridge-expanded/screen-access` records the original access. The narrow udev rule reapplies the selected grant when fb0 is recreated. Persistent access lets any process of that Unix user read framebuffer pixels across logout and reboot, including another user's screen, so the administrator must assess that tradeoff.
|
||||
|
||||
Revoke on the same machine with:
|
||||
|
||||
```sh
|
||||
sudo fb screen-access disable
|
||||
fb screen-access status
|
||||
```
|
||||
|
||||
Disable prevents regranting and restores only the access this helper owns. A conflicting external ACL change is reported instead of being overwritten; protected recovery data remains available for review. Package removal uses this same revocation and stops on unresolved conflict. Upgrade preserves the explicit policy. Normal per-console sudo enable/disable remains separate from framebuffer read access and still requires normal sudo authentication.
|
||||
|
||||
## Acceptance and scope
|
||||
|
||||
RC6 remains the frozen baseline. RC7 implementation tests, reproducible builds, installed-file verification, fresh installation, reboot, recovery, removal and the central-before-node workflow must be recorded for the exact RC7 artifact. Password-backed sudo must be checked interactively; root execution through a VM guest agent does not prove that the user entered a valid password. Source fixtures are not screenshots of a real screen. See VALIDATION.md and the external evidence for completed checks and remaining gates.
|
||||
@@ -0,0 +1,119 @@
|
||||
# FrameBridge Original Expanded — requirements and acceptance criteria
|
||||
|
||||
PROJECT=FRAMEBRIDGE_ORIGINAL_EXPANDED
|
||||
STATUS=PRODUCT_REQUIREMENTS_AND_ACCEPTANCE_CRITERIA
|
||||
DATE=2026-10-26
|
||||
CANDIDATE=COMMUNITY_PREVIEW7
|
||||
|
||||
This document defines the requested product. An acceptance criterion is a requirement, not evidence that it already passes. Release claims must cite the final artifact and the corresponding test report.
|
||||
|
||||
## Product and supported installation
|
||||
|
||||
| ID | Requirement | Acceptance evidence required |
|
||||
|---|---|---|
|
||||
| PKG-01 | Deliver one amd64 Debian package for Debian 13 with Python 3.13. | Install the actual release package on a fresh Debian 13 amd64 environment and run its installed entry points. |
|
||||
| PKG-02 | Include the original execution, CUA, fleet and terminal components needed by the supported roles. | A manifest maps packaged files to captured original sources or explicitly reviewed adaptations. |
|
||||
| PKG-03 | Declare dependencies used by the actual execution path. | A clean installation resolves dependencies; doctor checks commands, Python imports and graphics requirements. |
|
||||
| PKG-04 | Provide all help, prompts, instructions and release documentation in English. | Review the installed CLI, generated help and shipped documents. |
|
||||
| PKG-05 | Preserve the existing production installations. | Tests use separate state, transport endpoints and terminal sockets; record the scope and cleanup performed. |
|
||||
|
||||
## First use and roles
|
||||
|
||||
| ID | Requirement | Acceptance evidence required |
|
||||
|---|---|---|
|
||||
| CLI-01 | Provide the framebridge command and the fb alias with an understandable first-use entry. | Exercise both installed entry points without arguments and inspect their help. |
|
||||
| CLI-02 | Provide automatic standalone defaults for a normal first connection and separate guided setup for central/node roles and advanced settings. | Test first connection without a saved profile or prior setup/start, plus each advanced role's configuration and runtime behavior. |
|
||||
| CLI-03 | Keep the normal connection wizard concise and expose the configured role, node name, ports and state location through status. | Status agrees with the selected profile and running processes; the first connection keeps the required three-field order. |
|
||||
| CLI-04 | Keep setup, start, stop, status and doctor behavior explicit. | Test lifecycle, repeated invocation, occupied ports and process cleanup without touching production. |
|
||||
| CLI-05 | Identify operations requiring administrator privileges and keep authentication in the normal terminal. | Fresh Debian instructions match package installation and managed-service setup; the connection wizard does not request administrator credentials in chat or conceal privileged setup. |
|
||||
|
||||
Standalone runs the local tools independently. Central manages the fleet-facing entry point and node admission. Node joins an explicitly selected central instance. These descriptions do not authorize a role merely because a host was discovered on the network.
|
||||
|
||||
## ChatGPT connection
|
||||
|
||||
| ID | Requirement | Acceptance evidence required |
|
||||
|---|---|---|
|
||||
| GPT-01 | The user signs in to their own ChatGPT account in the browser and completes the required consent manually. | Record an authorized browser connection and real tool calls; never treat a local label as authenticated identity. |
|
||||
| GPT-02 | Accept only a raw tunnel ID in the normal hidden tunnel field; retain complete supported commands in the advanced hidden foreground workflow. | Test normal ID validation and safe rejection of accidentally pasted commands. Advanced parser tests cover quoting and invalid commands; a command is parsed as data and never run by a shell. |
|
||||
| GPT-03 | Read the MCP server access key at a hidden terminal prompt. The normal connection workflow stores only a host-bound encrypted credential for managed startup; advanced foreground mode remains nonpersistent. | Verify no plaintext key in profile configuration, persistent files, shell history, logs, command arguments or release artifacts. Verify encrypted storage and decryption through protected process-memory pipes. |
|
||||
| GPT-04 | Do not save or repeat the complete pasted tunnel command. | Inspect successful and failing CLI output and resulting state. Only necessary public tunnel metadata may be retained. |
|
||||
| GPT-05 | Run the normal connection through managed services with concise progress, explicit readiness, status and disconnection; retain foreground diagnostics through an explicit option. | Verify prompt return, survival of terminal closure, concurrent invocation, startup failure, interruption, process identity and cleanup. Pending readiness must not be called connected. |
|
||||
| GPT-06 | Report local readiness separately from a real ChatGPT end-to-end success. | Status and documentation identify which account/browser and tool-call checks were actually performed for this release. |
|
||||
| GPT-07 | Configure Linux boot startup and reconnection as part of the normal standalone/central connection, without prior manual start, a separate startup opt-in or repeated boot-time credential prompts. | Verify immediate managed startup and terminal closure; reboot a Debian 13 VM and verify text-mode tools and tunnel before graphical login. Setup must not force a routine reboot. |
|
||||
| GPT-08 | Use systemd encrypted credentials for the normal saved MCP access key, with normal sudo authentication when setup requires it. | Verify systemd 256 or later, protected encrypted storage, no plaintext persistent profile copy, and documented root/full-image recovery limits. |
|
||||
| GPT-09 | Keep disconnect, stop and disable behavior distinct and reversible. | Disconnect retains the local runtime and next-boot enablement; stop ends the current instance; disable stops it and removes only matching owned configuration, reversing changed settings with guards. |
|
||||
| GPT-10 | Provide explicit transactional replacement and normal package removal without mandatory manual stop/disable steps. | Verify connect chatgpt --replace preserves prior managed settings on failure. Verify actual package removal stops/disables only recognized package-managed user units, preserves profiles/encrypted credentials/linger, and does not run removal cleanup on upgrade. Optional guarded autostart disable remains separate. |
|
||||
| GPT-11 | Ask for the visible account/email label first, hidden tunnel input second and hidden MCP server access key third on a first unmanaged connection. | Inspect prompt order and hidden input; distinguish local account labeling from browser login and the MCP access key from an OpenAI API key. |
|
||||
| GPT-12 | Check or resume a valid managed profile using saved encrypted settings without reentering the fields; reserve changes for explicit --replace. | Test repeated connect on running and stopped managed profiles, and safe rejection of corrupt or unowned configuration without a false connected result. |
|
||||
|
||||
An email entered during setup is a local label. It is not proof of the browser account, tunnel ownership or node identity. No browser cookies, saved sessions or account passwords belong in this package or its reports.
|
||||
|
||||
## Original execution and CUA behavior
|
||||
|
||||
| ID | Requirement | Acceptance evidence required |
|
||||
|---|---|---|
|
||||
| EXEC-01 | Preserve original FBEXEC behavior and its job, exit-code, stdout, stderr and hash evidence. | Run real commands through the packaged route and verify their backend evidence. |
|
||||
| EXEC-02 | Use the original execution path without importing the experimental job-approval queue. | Source and runtime review identify the handler actually reached by each public tool. |
|
||||
| CUA-01 | Preserve original X11 CUA where the supported desktop or private display is available. | Run actual observation and interaction tests against the intended display. |
|
||||
| TTY-01 | Provide access to the original GERAMEG CUA-TTY backend, including the supported real-terminal mode. | Verify text input, Enter, actual shell output and terminal cleanup through the original RPC. |
|
||||
| TTY-02 | Distinguish an isolated demo from control of a real persistent Bash terminal. | Tests and help explicitly identify the active mode; demo acknowledgements alone do not certify a real shell command. |
|
||||
| TTY-03 | Separate terminal state for independent instances. | Test distinct sockets and sessions; never copy live socket paths, session IDs or process IDs from another machine. |
|
||||
| AUTH-01 | Do not require a phone or Owner Device for the requested local execution or CUA workflow. | Exercise the workflow without phone enrollment or an Owner Device gate. |
|
||||
|
||||
The original GERAMEG documentation first certified a demo and later certified a real terminal. The real-terminal A/B certificate is the relevant reference for TTY-01; the earlier demo result is not interchangeable with it.
|
||||
|
||||
## Fleet admission and authenticated transport
|
||||
|
||||
| ID | Requirement | Acceptance evidence required |
|
||||
|---|---|---|
|
||||
| FLEET-01 | Central and node roles use authenticated transport. | Successful authenticated node traffic and rejected unauthenticated traffic are demonstrated. |
|
||||
| FLEET-02 | A node's identity and intended central instance are reviewed and approved explicitly before admission. | Record the exact identity presented, the pending request and the resulting approval; no silent acceptance on discovery. |
|
||||
| FLEET-03 | Keep route selection explicit and reject an unknown target without redirecting to another host. | Test local and enrolled-node routes plus an unknown target. |
|
||||
| FLEET-04 | Include the original broker/outbound-agent workflow required by the selected roles. | Demonstrate actual node registration, online status, remote FBEXEC and CUA routing through the central instance. |
|
||||
|
||||
Transport authentication and approved node identity remain required. Removing a phone requirement does not remove either condition. The normal connection workflow saves the MCP access key only as a host-bound encrypted systemd credential; advanced foreground diagnostics keep it in process memory without persistence. Plaintext credentials must not be persisted in profile files or distributed evidence. Generated node identity and transport-authentication material have a separate purpose and may require protected persistent profile state; such state must never be included in a redistributable package or evidence bundle.
|
||||
|
||||
## Graphics and headless operation
|
||||
|
||||
The installer and control console use a text interface in a Linux TTY or terminal emulator. Graphical CUA is a backend selected automatically from a usable supported desktop; its availability does not change the installer or console into a graphical interface.
|
||||
|
||||
The historical R1 FBTERM engine opens a GNOME terminal and uses wmctrl; evidence for that path must identify it. The current persistent-terminal workflow must also work in text mode without a graphical desktop. Graphical X11 CUA needs a verified display, the correct Xauthority and its command-line tools.
|
||||
|
||||
Community Preview 4 and later product decision: headless mode is auto by default. The runtime uses a verified usable physical X11 session when available; otherwise it starts in text mode, reporting display_context.kind=text. Text mode provides FBEXEC, FBTERM and CUA-TTY without a monitor, graphical login or forced virtual desktop. Graphical CUA requests in adaptive mode re-check for a usable physical session when one appears, without restarting persistent FBTERM sessions; per-operation screen checks reject a session change during input. Explicit headless=yes requests the separate private X11 desktop, reported as virtual-x11 and physical=false. Explicit headless=no requires the verified physical session; enabling automatic startup backs up and converts that physical-only setting to auto for boot operation.
|
||||
|
||||
The retained xvfb, openbox, dbus-x11, xauth, x11-xkb-utils and fonts-dejavu-core dependencies support explicit private graphical operation alongside the original execution and CUA dependencies. Graphical capability checks must distinguish optional graphics from text-mode readiness. Prove adaptive text startup, later verified physical CUA, explicit private mode and safe refusal against the exact final runtime in Debian QA. These are acceptance requirements, not passing test results. See the current [connection lifecycle](../../docs/CONNECTION-STATUS.md) and [Debian tutorial](DEBIAN-TUTORIAL.md).
|
||||
|
||||
Node operation must use the configured local user's identity and runtime directory rather than requiring a hard-coded UID such as 1000.
|
||||
|
||||
## Required release evidence
|
||||
|
||||
| Area | Current status | Evidence needed before a passing claim |
|
||||
|---|---|---|
|
||||
| Final package installation on fresh Debian | See VALIDATION.md | Exact package hash, dependencies, installed entry points and environment details. |
|
||||
| English CLI and tutorial | See VALIDATION.md | Review against actual installed help and behavior. |
|
||||
| Three role configurations | See VALIDATION.md | Per-role configuration and lifecycle results. |
|
||||
| Fleet identity approval and transport | See VALIDATION.md | Real central/node admission and routed tools. |
|
||||
| Tunnel parser and memory-only key | See VALIDATION.md | Parser, failure, cleanup and secret-retention checks. |
|
||||
| Original FBEXEC, X11 CUA and real CUA-TTY | See VALIDATION.md | Backend receipts and observed results for the final package. |
|
||||
| Manual ChatGPT connection | See VALIDATION.md | Browser consent and real tool calls against this package. |
|
||||
| Source fidelity and reproducible package | See VALIDATION.md | Reviewed source mapping and independently compared builds. |
|
||||
|
||||
The successful Original R1/R2 tests are historical reference evidence. They must not be reported as fresh Expanded package tests.
|
||||
|
||||
## Historical source documents
|
||||
|
||||
- FrameBridge C8 terminal-first onboarding R7, 2026-10-11: https://drive.google.com/file/d/1LuYF1vGw8FKaD4Izcpw4NnR0HRuws78s/view
|
||||
- Terminal-first onboarding guide R1: https://drive.google.com/file/d/11MEm5eOVke4aSeIBc-024e1zNLke_y_s/view
|
||||
- GERAMEG CUA-TTY demo-only live test, 2026-10-19: https://drive.google.com/file/d/1DixrNUYUhr6pM2wiXeILKmU2dmbE53_D/view
|
||||
- GERAMEG real-terminal FBEXEC/CUA-TTY A/B certificate R3, 2026-10-19: https://drive.google.com/file/d/1VUzhCLJpV8DNQSOlfWYus-nzKAsloGlm/view
|
||||
|
||||
These are historical implementation references. They do not override the current requested product or authorize copying runtime identities or secrets.
|
||||
|
||||
|
||||
## RC7 saved-image and lifecycle acceptance
|
||||
|
||||
The exact saved PNG must be retrievable by node/capture_id without taking a replacement capture or performing input. Presentation must preserve the original bytes, resolution and SHA-256, label saved images as historical, and fail explicitly for unknown or corrupt data. An offline MCP Apps viewer must be tested in the intended ChatGPT account; ImageContent serialization alone is insufficient proof of rendering.
|
||||
|
||||
A central must be usable and manually connectable before any worker is installed. A later separately installed node must join the running central through explicit authenticated approval and become available without reconnecting ChatGPT.
|
||||
|
||||
Persistent tty framebuffer access must be an explicit root opt-in for a named non-root user, limited to reading the real fb0 device. No installation-time broad grant is acceptable. Revocation and package removal must restore only the helper's own change, preserve unrelated changes, and report conflicts. Fresh installation, reboot/recovery/removal and password-backed sudo results must be recorded for the exact RC7 artifact; inherited RC6 evidence is historical context.
|
||||
@@ -0,0 +1,40 @@
|
||||
# FrameBridge Original Expanded — RC7 validation scope
|
||||
|
||||
Date: 2026-10-24
|
||||
Candidate: 0.3.0~expanded.20261024.7
|
||||
Status: release acceptance is determined by the external report and evidence.
|
||||
|
||||
## Preserved baseline evidence
|
||||
|
||||
RC6 (0.3.0~expanded.20261023.6) is a separate frozen artifact. Its final source suite passed 314 tests and two builds produced identical package bytes. RC6 was installed on the isolated Debian CENTRAL and NODE VM filesystems. The real test account and manual tunnel verified status, local and remote EXEC, and authentic physical X11/framebuffer captures without new capture-created FBTERM jobs.
|
||||
|
||||
Those results do not certify RC7. RC6 still had an open ChatGPT image presentation/reuse gate, and the lab framebuffer read ACL was temporary. Three additional direct diagnostic checks passed; two terminal-key negative cases were skipped because the required auxiliary Bash window was not in front. Official CLOUD MT publication was not verified by that diagnostic phase.
|
||||
|
||||
## RC7 implementation scope
|
||||
|
||||
RC7 adds read-only retrieval of saved original PNGs, an offline MCP Apps viewer, and explicit opt-in persistent read-only fb0 access. Existing capture and input contracts remain separate from historical viewing. Central-first/manual-ChatGPT/later-node setup is documented and must be exercised in an installed environment.
|
||||
|
||||
The source suite covers setup, manual connection, TLS and routing, terminal identity and NoNewPrivs transitions, display context, actual-screen transport and input bindings. RC7 must also test saved-image byte integrity, authorization, unknown/corrupt capture handling, the SDK UI contract, and safe framebuffer access/revocation including external ACL conflicts.
|
||||
|
||||
Image fixtures are unit data, not evidence that a physical screen was captured. Terminal transcripts are text data, not screenshots. Unit registration of a UI resource does not prove actual ChatGPT rendering.
|
||||
|
||||
## Required installed-VM gates
|
||||
|
||||
1. Verify the exact RC7 .deb hash and install with APT in clean Debian 13 on separate CENTRAL and NODE VM filesystems.
|
||||
2. Verify declared dependencies, installed commands, package identity and installed critical-file hashes.
|
||||
3. Check start, stop, reboot, recovery and removal with preserved evidence. Removal must not silently leave an enabled framebuffer grant.
|
||||
4. Verify the shared official console from normal graphical and text logins.
|
||||
5. Verify managed-console NoNewPrivs on/off from actual processes and ordinary password-authenticated sudo. Root guest-agent execution and NOPASSWD are not substitutes for a password test.
|
||||
6. In a physical LightDM X11 session, capture complete display pixels and test visible graphical input. Verify stale observations fail after relevant window/geometry/session changes.
|
||||
7. Verify physical tty capture permission persists after reboot only when the explicit opt-in is enabled, and that revocation restores the access this helper owns.
|
||||
8. Connect the CENTRAL manually to the intended ChatGPT account, then enroll and approve a newly installed NODE through verified TLS without reconnecting ChatGPT. Verify routed tools on the added node.
|
||||
9. Complete actual-account observation, original-PNG display and reuse through the RC7 tools. Match the shown capture/node/hash to the backend evidence; do not replace an unavailable capture or infer rendering from a tool response alone.
|
||||
10. Record user-entered manual-tunnel/account consent outcomes without passwords, runtime keys, cookies or other secrets. Verify the selected account separately from its optional email label.
|
||||
|
||||
A single host using two profile directories is not a two-machine installation test. Xvfb is explicitly virtual and cannot satisfy the physical display gate. Fresh isolated clones must not overwrite the existing working VM disks or interrupt their manual tunnel.
|
||||
|
||||
## Evidence and limitations
|
||||
|
||||
The external release report records exact package/source hashes, checks actually run, return codes, machine identities and unresolved gates. Package hashes remain outside packaged documentation to avoid circular builds. A prepared script, simulated APT run, active display-manager daemon or stale Xorg log is not a completed acceptance result.
|
||||
|
||||
Creating the isolated RC7 source tree does not deploy to production or change host network, kernel or GPU configuration. The package does not grant passwordless root access, auto-enable a framebuffer policy or connect silently to ChatGPT. Read the external acceptance status before calling this candidate a finished release.
|
||||
@@ -0,0 +1,285 @@
|
||||
.TH FRAMEBRIDGE 1 "2026-10-26" "FrameBridge 0.3.1" "User Commands"
|
||||
.SH NAME
|
||||
framebridge, fb \- use local Linux tools and enrolled nodes with ChatGPT
|
||||
.SH SYNOPSIS
|
||||
.B framebridge
|
||||
[\-\-json] [\-\-state\-dir DIRECTORY] COMMAND [ARGUMENTS]
|
||||
.SH DESCRIPTION
|
||||
FrameBridge provides one command-line interface for human operators and authorized agents.
|
||||
The names fb and framebridge execute the same program.
|
||||
The tools run on the selected Linux computers; the ChatGPT model remains hosted.
|
||||
.SH START WITH FRAMEBRIDGE
|
||||
.SS One interface for people and agents
|
||||
FrameBridge provides tools and a shared command\-line interface for human operators and authorized agents. fb is the short name for framebridge; both run the same program. The tools run on your Linux computers. The ChatGPT model remains hosted. Read this guide for the installed version before operating; confirm the receiver, target and available capabilities. Use the installed CLI and tools for normal work. Edit software only when the owner explicitly requests development, using a separate source clone and reviewable changes rather than rewriting the installed program.
|
||||
.PP
|
||||
.nf
|
||||
fb help
|
||||
fb status
|
||||
fb \-\-json status
|
||||
.fi
|
||||
.SS Install and connect
|
||||
On a supported Debian system, install the downloaded package with the package manager. Normal first connection does not require a separate setup, doctor or start sequence. Run connect in a normal interactive terminal. Advanced setup is optional for selecting central/node roles and public settings.
|
||||
.PP
|
||||
.nf
|
||||
sudo apt install ./FrameBridge\-0.3.1.deb
|
||||
fb connect
|
||||
.fi
|
||||
.SS Updating and removal
|
||||
Install an official update through the normal package manager. Normal package removal stops package\-owned managed processes and retains the profile and saved encrypted connection material for deliberate reuse; it is not a credential\-forgetting operation. Use the separately documented explicit forget action first if that is your intended outcome. Do not assume purge erases user\-profile data.
|
||||
.PP
|
||||
.nf
|
||||
sudo dpkg \-\-remove framebridge\-original\-expanded
|
||||
.fi
|
||||
.SS Human authentication
|
||||
The normal connection asks for an optional account label, a hidden tunnel ID and a hidden MCP server access key. The label is metadata, not proof of ChatGPT login. Browser login/consent and normal operating\-system authentication remain human actions in the normal interface. Never put credentials in chat, command arguments, documentation or example files. A successful managed connection returns to the prompt and can run independently of that terminal. Reboot only when an actual system change requires it.
|
||||
.SS Choose the right guide
|
||||
Use commands for the reference, connection and lifecycle for state changes, nodes for central/node work, terminals for persistent Bash, and screens for authentic CUA evidence. Query success alone does not mean the connection is ready. The guide describes registered operations; use status/doctor to investigate current state.
|
||||
.PP
|
||||
.nf
|
||||
fb help commands
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
.fi
|
||||
.SH COMMAND REFERENCE
|
||||
.SS Everyday commands
|
||||
connect establishes or resumes the managed ChatGPT connection. disconnect pauses that connection until an explicit connect, including across recovery and reboot. status reports runtime, connection, intended connection state and boot policy. doctor diagnoses prerequisites/problems. setup edits advanced stopped\-profile settings. console opens the text work view. help reads this versioned reference.
|
||||
.PP
|
||||
.nf
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
fb status console
|
||||
fb doctor
|
||||
fb setup
|
||||
fb console
|
||||
fb help
|
||||
.fi
|
||||
.SS Services and boot
|
||||
For an already configured managed profile, service start/stop control the current stack symmetrically. Boot enable/disable changes future startup policy without stopping current work or forgetting the saved credential. First node provisioning is an explicit exception described in lifecycle. Without managed setup, non\-node service start starts local tools only; normal first connection should use connect. Read status before and after changes. The separate credentials forget action is destructive and requires explicit confirmation.
|
||||
.PP
|
||||
.nf
|
||||
fb service start
|
||||
fb service stop
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
.fi
|
||||
.SS Console and specialized operations
|
||||
console login manages optional work\-view opening after an authenticated tty1 login; it does not enable automatic login. tty service manages the terminal daemon; tty list lists sessions. nodes, certificates and screen\-access retain their domain\-specific subcommands. Use \-\-help at the relevant command for its exact arguments. Avoid compatibility aliases in new automation.
|
||||
.PP
|
||||
.nf
|
||||
fb console login status
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb nodes \-\-help
|
||||
fb certificates \-\-help
|
||||
fb screen\-access \-\-help
|
||||
.fi
|
||||
.SS Human and structured output
|
||||
Use explicit commands in automation rather than the interactive no\-argument menu. \-\-json selects structured output for an agent; examine operation success, readiness and state separately. Read errors and the exit status. If human interaction is required, complete it in the normal terminal/interface rather than attempting to supply a secret through the agent. CLI JSON uses an envelope with schema_version, product, version, command, ok and result. Read runtime, connection and boot truth inside result; envelope ok denotes request success. Exit 0 means successful query/operation, not necessarily a connected transport; exit 1 reports operation/diagnostic failure, exit 2 invalid arguments or required human interaction/confirmation, and exit 130 cancellation.
|
||||
.PP
|
||||
.nf
|
||||
framebridge \-\-json status
|
||||
fb \-\-json status connection
|
||||
.fi
|
||||
.SH CONNECT AND DISCONNECT CHATGPT
|
||||
.SS Normal managed connection
|
||||
connect creates the default standalone profile when absent and establishes managed startup. It asks for initial human input in the terminal, checks progress, reports readiness or an actionable failure, and returns to the prompt. Valid saved setup can be resumed without repeating the initial fields. The MCP access key is not an OpenAI API key. Keep the browser's ChatGPT account login and consent separate from the optional local account label.
|
||||
.PP
|
||||
.nf
|
||||
fb connect
|
||||
fb status connection
|
||||
.fi
|
||||
.SS Saved credentials and next boot
|
||||
Managed startup uses protected, host\-bound encrypted connection material. The normal terminal does not have to remain open. This is a persistence feature, not a promise that an account, network or tunnel service can never fail. Connection intent and boot policy are separate: enabled startup runs the stack at boot, while an intentional disconnected state remains disconnected until connect.
|
||||
.PP
|
||||
.nf
|
||||
fb status boot
|
||||
fb status
|
||||
.fi
|
||||
.SS Intentional disconnect
|
||||
disconnect keeps local tools and saved material, but records the intention to stay disconnected across worker recovery and reboot. Explicit connect clears that pause. Check the returned state rather than interpreting a successful query as an active transport.
|
||||
.PP
|
||||
.nf
|
||||
fb disconnect
|
||||
fb status connection
|
||||
.fi
|
||||
.SS Replacement and temporary foreground mode
|
||||
Use connect \-\-replace only when deliberately replacing the account label/tunnel/access configuration. The advanced \-\-foreground mode is temporary, needs a ready local runtime and occupies its terminal until interrupted; it is not the normal managed workflow. Do not use advanced mode merely to recover a normal saved connection.
|
||||
.SH SERVICES, CONNECTION INTENT AND BOOT POLICY
|
||||
.SS Separate states
|
||||
FrameBridge distinguishes actual local runtime, desired connection, verified transport, boot enablement and saved credential presence. A healthy runtime can be intentionally disconnected; a service can be active while disabled for the next boot. Read the labelled status fields together.
|
||||
.PP
|
||||
.nf
|
||||
fb status
|
||||
fb \-\-json status
|
||||
.fi
|
||||
.SS Current managed stack
|
||||
For an already configured managed profile, service start and service stop use the same current\-stack boundary without changing boot enablement. Stop ends current managed work and transport but keeps profile, boot policy and saved material. Startup on the next boot follows the retained policy and intended connection state. A non\-node profile without managed setup starts only local tools. Stopping a terminal service or session can interrupt its running work.
|
||||
.PP
|
||||
.nf
|
||||
fb service start
|
||||
fb service stop
|
||||
.fi
|
||||
.SS Future boot policy
|
||||
Once managed setup exists, service boot enable/disable changes unit enablement only. It does not immediately stop or start current work and does not delete saved connection material. Initial node provisioning is described separately below. Explicitly forgetting saved material is a separate destructive operation. Legacy autostart disable has its old broader destructive behavior; use the canonical service boot commands for new workflows.
|
||||
.PP
|
||||
.nf
|
||||
fb service boot enable
|
||||
fb service boot disable
|
||||
fb status boot
|
||||
.fi
|
||||
.SS First managed startup for a node
|
||||
After advanced node setup and the required enrollment/approval, a node without a managed installation can run service start in a normal terminal. This first call creates managed startup, enables future boot and starts the node now; the result explicitly reports initial_configuration and boot_policy_changed. Alternatively, first service boot enable prepares and enables the node unit without starting current work. Initial preparation can require normal owner authentication and is not silently performed by an unattended JSON request. Once configured, the ordinary start/stop and boot\-policy\-only contracts apply. A node does not need its own ChatGPT tunnel.
|
||||
.PP
|
||||
.nf
|
||||
fb service start
|
||||
fb service boot enable
|
||||
fb status boot
|
||||
.fi
|
||||
.SS Console opening
|
||||
Opening console is a view operation, separate from Linux service startup. Optional console login enable/disable changes the owned startup hook after an authenticated tty1 Bash login. This hook does not bypass normal login. Review the command's scope before changing it.
|
||||
.PP
|
||||
.nf
|
||||
fb console login status
|
||||
.fi
|
||||
.SH CENTRAL AND NODE OPERATION
|
||||
.SS Roles
|
||||
Standalone provides local tools. Central adds the broker for enrolled nodes. A node joins one selected central instance and uses its ChatGPT connection; it does not need another ChatGPT tunnel or phone pairing. Advanced setup selects the role. Preserve explicit authenticated node transport and real identity approval.
|
||||
.PP
|
||||
.nf
|
||||
fb setup
|
||||
fb nodes \-\-help
|
||||
.fi
|
||||
.SS Enrollment is not availability
|
||||
Enrollment submission, central approval, node receipt of authorization and a running node agent are separate stages. status reports what it actually knows; an unchecked agent is not evidence that the node is online. Central list/pending/approve and node enroll/poll/status/run have role\-specific purposes. poll can complete saved authorization; it is not a purely observational operation. After enrollment, consult the lifecycle topic for first managed node startup and its explicit initial boot\-policy effect.
|
||||
.PP
|
||||
.nf
|
||||
fb nodes list
|
||||
fb nodes pending
|
||||
fb nodes status
|
||||
.fi
|
||||
.SS Targets
|
||||
LOCAL means the actual receiving machine. Use enrolled, confirmed aliases or IDs and inspect the selected target before work. Do not guess SSH identities or use historical lab hostnames as defaults. CLI tty \-\-node can use the authenticated node transport. The interactive console command is local; run it at the destination or use an explicitly configured SSH destination.
|
||||
.SS Transport trust
|
||||
certificates create manages a private central/node transport CA, not a public website certificate or ChatGPT account authentication. Private keys stay protected on the central host; distribute only the required public trust material. Off\-loopback broker use requires correctly configured verified TLS. Do not recreate trust merely to work around a connection symptom.
|
||||
.PP
|
||||
.nf
|
||||
fb certificates \-\-help
|
||||
.fi
|
||||
.SH PERSISTENT BASH TERMINALS
|
||||
.SS Service and sessions
|
||||
tty service controls the profile's terminal daemon. tty open creates a real Bash session and returns its identifier. Use that identifier for subsequent observations and input. The same Bash preserves directory, variables and work between requests while the session/service remains alive. It does not preserve running processes across an operating\-system reboot. Tool jobs use a profile\-specific HOME; a job's home directory can therefore differ from the human login home. Commands retain the connecting account's normal operating\-system permissions.
|
||||
.PP
|
||||
.nf
|
||||
fb tty service status
|
||||
fb tty list
|
||||
fb tty open
|
||||
.fi
|
||||
.SS Observe, type and keys
|
||||
tty observe returns terminal transcript text, cursor, dimensions and process state; it is not an authentic full\-screen image. tty type sends text without automatically adding Enter, though supplied newlines can affect execution. tty key accepts exact uppercase names such as ENTER and CTRL_C. Replace session arguments with an identifier returned by open/list; never guess one.
|
||||
.PP
|
||||
.nf
|
||||
fb tty key \-\-help
|
||||
fb tty type \-\-help
|
||||
fb tty observe \-\-help
|
||||
.fi
|
||||
.SS Lifetime and closing
|
||||
Default real idle expiry is disabled, but a profile can configure a timeout. Global status/list does not refresh each session's per\-session activity. close destroys a session rather than merely separating a viewer. Graceful service stop attempts to close its sessions; elevated or unverifiable process state can prevent cleanup. Inspect the outcome instead of assuming that all child processes disappeared.
|
||||
.PP
|
||||
.nf
|
||||
fb tty close \-\-help
|
||||
fb tty resize \-\-help
|
||||
.fi
|
||||
.SS Sudo mode
|
||||
A session's sudo on/off controls normal privilege eligibility; it does not log in as root or bypass operating\-system authentication. Changing the mode recreates Bash, preserving directory and dimensions but not shell variables or internal state. Authentication stays in the normal human terminal/interface. Never send a password through type or chat.
|
||||
.PP
|
||||
.nf
|
||||
fb tty sudo \-\-help
|
||||
.fi
|
||||
.SS Work console panels
|
||||
console combines an ordinary Bash pane with a read\-only FBTERM activity dashboard. The dashboard is not a second interactive shell. The tmux prefix is Ctrl+B: release both keys, then press lowercase z to enlarge/restore a pane, or lowercase o to switch panes. The release accepts common zoom\-key variants within its dedicated console. Closing a viewer normally leaves its tmux session alive; leaving Bash, killing its server or rebooting is different. In a desktop terminal the shared work view is horizontal with FBTERM on the left and Bash on the right. Explicit TTY mode is vertical with a short FBTERM monitor above Bash. The layout belongs to the shared tmux window and follows the last requested view mode; it is not isolated per viewer.
|
||||
.PP
|
||||
.nf
|
||||
fb console
|
||||
fb status console
|
||||
.fi
|
||||
.SH AUTHENTIC SCREEN OBSERVATION AND INPUT
|
||||
.SS Text transcripts and pixels
|
||||
A CLI tty transcript describes a terminal and explicitly does not claim authentic pixels. MCP real\-screen CUA\-TTY and graphical screen tools operate through the real screen client and capture\-linked interaction. Use those supported observation tools when authentic complete screen evidence is required. Never present a reconstructed terminal, animation or partial invented view as a real screenshot.
|
||||
.SS Automatic graphical discovery
|
||||
The installer and control console stay text interfaces in both TTY and a desktop terminal. Compatible graphical CUA is discovered automatically; availability depends on the actual display/session and permissions. A loaded module is not proof that real pixel capture or input succeeded. New profiles use adaptive auto mode: without a verified active X11 session the runtime provides FBEXEC, FBTERM and CUA\-TTY in text mode, without requiring a graphical login or automatically creating a private desktop. Explicit virtual\-desktop settings remain advanced options and are labelled separately from physical\-screen evidence.
|
||||
.PP
|
||||
.nf
|
||||
fb status
|
||||
fb doctor
|
||||
.fi
|
||||
.SS Frame\-buffer read access
|
||||
screen\-access is a narrow, explicit administrative permission for reading the real frame buffer. It does not by itself enable graphical CUA, keyboard/mouse control or arbitrary VT switching. Persistent read access can remain effective after logout or a VT switch; review the command's displayed scope and use normal local administrator authentication.
|
||||
.PP
|
||||
.nf
|
||||
fb screen\-access status
|
||||
.fi
|
||||
.SS Shared desktop
|
||||
A graphical desktop shares focus, keyboard and mouse. Use one controlling agent per desktop at a time and avoid overlapping work. This is an operating recommendation, not a claim of certified automatic isolation. Independent non\-overlapping execution jobs may be possible; do not infer isolation or physical parallel execution from that alone.
|
||||
.SH STATUS AND DIAGNOSIS
|
||||
.SS Inspect before acting
|
||||
status summarizes current runtime, connection, desired state and boot policy. A query completing successfully is distinct from the components being ready. Connection verification has a freshness boundary; retrying or unknown must not be treated as connected. Focused status uses the same underlying state model.
|
||||
.PP
|
||||
.nf
|
||||
fb status
|
||||
fb status connection
|
||||
fb status runtime
|
||||
fb status boot
|
||||
.fi
|
||||
.SS Doctor
|
||||
doctor diagnoses prerequisites and reports findings with suggested next steps. It is not an implicit repair, and it is not a substitute for checking actual live connection state. Inspect the diagnosis and relevant private application logs before considering configuration changes.
|
||||
.PP
|
||||
.nf
|
||||
fb doctor
|
||||
.fi
|
||||
.SS Logs and progress
|
||||
Normal connection presents concise progress and a final result, then returns to the prompt. Detailed diagnostics belong in protected application logs. Share only the minimum relevant redacted result; never expose credentials, private keys, browser session data or unrelated personal paths. Avoid rerunning setup, enrollment or broad lifecycle tests merely because a view is confusing.
|
||||
.PP
|
||||
.nf
|
||||
fb help connection
|
||||
fb help lifecycle
|
||||
.fi
|
||||
.SH AUTHORIZATION, DISTRIBUTION AND SAFE OPERATION
|
||||
.SS Authorized scope
|
||||
An agent can use the documented CLI and MCP tools within the user's authorized scope. Reading this guide does not grant permission. Verify the receiver and selected target. Normal human terminal/browser authentication remains separate; do not request credentials in chat or invent phone/Owner\-TTY enrollment requirements. Normal use should operate through the installed CLI and tools, not edit or rebuild installed FrameBridge program files. If the owner explicitly requests development, use a separate source clone, make reviewable changes, and do not present a modified build as an official release. This operating guidance does not restrict GNU GPL freedoms or require private forks to submit changes upstream.
|
||||
.SS Official releases
|
||||
The source is distributed under GNU GPLv3\-only terms and the applicable third\-party notices. Verify official release checksums and published signatures/repository metadata before installing. Signature verification identifies the publisher and detects alteration; it does not prohibit lawful modified versions. Official releases are reviewed through the project's release process.
|
||||
.SS Side effects
|
||||
Read status before service stop, credential forgetting, node approval, startup\-hook changes or administrative screen permission changes. Explain material scope and consequences and follow the user's authorization. A sensitive operation must report the actual result, not just that a query succeeded. Keep real captures complete and distinguish observations from hypotheses.
|
||||
.SH COMPATIBILITY WITH EARLIER COMMANDS
|
||||
.SS Preferred spelling
|
||||
Use the short canonical interface in new documentation and automation. fb and framebridge remain equivalent. Older connect chatgpt, disconnect chatgpt and connection status spellings are compatibility routes. New status scopes replace the need to learn an extra connection noun.
|
||||
.PP
|
||||
.nf
|
||||
fb connect
|
||||
fb disconnect
|
||||
fb status connection
|
||||
.fi
|
||||
.SS Legacy lifecycle behavior
|
||||
Older root start/stop and autostart commands are retained for compatibility where documented, but their historical scopes can differ from the canonical service controls. In particular, legacy autostart disable removes managed setup and saved encrypted material; it is not an alias for boot\-policy\-only disable. Read the command's help before using a legacy script.
|
||||
.PP
|
||||
.nf
|
||||
fb help lifecycle
|
||||
.fi
|
||||
.SS Versioned help
|
||||
This guide describes the installed product and guide schema. Read the matching release notes for any semantic migration. The CLI help, MCP guide and static web documentation are generated from the same reviewed guide data; a cached manual from an earlier build can describe a different workflow.
|
||||
.PP
|
||||
.nf
|
||||
fb help compatibility
|
||||
.fi
|
||||
.SH AUTHORS
|
||||
Programming: ChatGPT.
|
||||
Concept and project coordination: Gerardo Betancourt.
|
||||
.SH LICENSE
|
||||
GNU GPL version 3 only, with the applicable third-party license notices.
|
||||
See the installed copyright and source license files.
|
||||
.SH SEE ALSO
|
||||
.BR systemctl (1), .BR dpkg (1), .BR apt (8)
|
||||
Reference in new issue
Block a user