gerardo/framebridge
1
0 Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: add three-step and agent-assisted setup workflow

Browse Source
This commit is contained in:
FrameBridge contributors committed 2026-10-27 15:05:05 -04:00
1 parent 5682508644
commit 0ae1fccfba
2 files changed
+174 -61
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+72 -61
View File
@@ -1,103 +1,114 @@
> Development candidate: **0.3.2~compat.20261027.1** for Debian, Ubuntu and Linux Mint on amd64. See [candidate scope and validation](docs/LINUX-COMPATIBILITY-CANDIDATE.md). Build profiles are not proof of live production compatibility. The official signed 0.3.1 release described below remains a separate artifact.
# FrameBridge
**Bring your ChatGPT conversations to Linux computers you control.**
FrameBridge connects a hosted ChatGPT conversation to tools running on your own computers. Run a task, return to a persistent Bash terminal, inspect the real desktop, and select an enrolled node.
Run a task on your own machine, return to the same Bash terminal, inspect an X11 desktop, or select an enrolled computer. ChatGPT remains hosted; FrameBridge runs the tools on your Linux computers.
**Community Release 0.3.1** · **Debian 13 amd64** · **Python 3.13**
> **Development candidate: `0.3.2~compat.20261027.2`.** This revision is being validated. It is not a signed public release. The separately signed 0.3.1 release remains a different artifact. Read the [candidate scope and validation record](docs/LINUX-COMPATIBILITY-CANDIDATE.md) before choosing a package.
The installer and control console are text interfaces in a Linux TTY or desktop terminal. FrameBridge detects a usable graphical X11 session automatically and adds graphical CUA when available. Text mode provides FBEXEC, persistent terminals and CUA-TTY. Adaptive mode does not silently create a virtual desktop.
## Start here
ChatGPT remains hosted. The tools execute on your own machines. Your own ChatGPT account and manual browser approval are required; a local account label does not authenticate you. No phone pairing is required.
Start on the Linux computer you want to connect, with a person at its terminal or an assistant already given shell access there. Your ChatGPT account and manual browser approval complete the connection. No phone pairing is required.
## Install and connect
| Step | What you do | What to check |
| --- | --- | --- |
| **1. Install** | Choose the package matching your distribution and Python version, verify its release record, then install it with APT. | The package manager resolves dependencies for that computer. |
| **2. Connect** | Run `fb connect` in your normal terminal and enter the requested connection details there. Complete browser sign-in and approval yourself. | The command reports the real connection result and returns to the prompt. |
| **3. Verify** | Run `fb status`, `fb doctor`, then `fb console`. In ChatGPT, ask the connected FrameBridge help tool for a small terminal task. | Confirm the selected machine and the result of the task. |
Verify the release checksums and signatures using the independently trusted project key before installing. See [Official releases](OFFICIAL-RELEASES.md) for the trust model and the project site for the signed release record.
### 1. Install the matching package
On Debian 13 amd64, with the downloaded installer in the current directory:
The compatibility candidate has separate native Python builds; it is not one interchangeable `.deb` for every Linux system.
| Distribution | Architecture | System Python | Candidate package profile |
| --- | --- | --- | --- |
| Debian 13 | amd64 / x86_64 | 3.13 | `debian13-amd64-py313` |
| Ubuntu 24.04 | amd64 / x86_64 | 3.12 | `ubuntu24.04-amd64-py312` |
| Linux Mint 22.x | amd64 / x86_64 | 3.12 | `mint22-amd64-py312` |
The preceding `.1` candidate passed VM tests on these systems, including Cinnamon on Mint 22.3, and a Debian production pilot. This `.2` revision needs its own validation. Ubuntu 26.04 and LMDE 7 builds remain experimental; other distributions, older releases and CPU architectures are outside this candidate's scope.
Verify official releases with the independently trusted project key as described in [Official releases](OFFICIAL-RELEASES.md). A candidate's recorded SHA-256 identifies its reviewed file; it is not a release signature. Candidate packages are for reviewed pilots.
For example, with the **Mint** candidate downloaded into the current directory:
~~~bash
sudo apt install ./FrameBridge-0.3.1.deb
fb connect
fb status
sudo apt install ./FrameBridge-0.3.2~compat.20261027.2-mint22-amd64-py312.deb
~~~
Normal first connection needs no separate setup or start command. The terminal asks for an optional account label, a hidden tunnel ID and a hidden MCP server access key. This access key is not an OpenAI API key. Complete any browser sign-in and approval separately.
Use the corresponding profile filename on Debian or Ubuntu. Review APT's proposed changes for the actual computer. Installation places the software on disk; it does not establish a ChatGPT connection or replace the system Python.
Normal connection prepares managed Linux startup, stores the saved credential encrypted on this machine, reports progress and returns to the prompt. It does not force a reboot. Repeating the command resumes valid saved settings; explicit replacement is available through fb connect --replace.
### 2. Connect from your terminal
## One command interface for people and agents
~~~bash
fb connect
~~~
The executable names fb and framebridge run the same program.
First connection needs no separate setup or start command. Have your tunnel ID and MCP server access key ready from the manual connection setup described in `fb help`. Enter them in the hidden local prompts and complete browser approval yourself. The key is not an OpenAI API key; the optional account label does not authenticate you.
| Command | Purpose |
| --- | --- |
| fb connect | Establish or resume the managed ChatGPT connection. |
| fb disconnect | Pause that connection until the next explicit connect, including after restart. Local tools and saved material remain. |
| fb status | Observe actual tools, connection and boot policy together. |
| fb status connection | Observe just the connection, including its intended state. |
| fb doctor | Diagnose prerequisites and problems; it does not repair or connect. |
| fb console | Open or reattach the text Bash/FBTERM work view. |
| fb help | Read the versioned English guide. |
| fb setup | Optional advanced role/profile configuration. |
The managed connection saves an encrypted credential locally, prepares startup, reports progress and returns to the prompt without requiring a reboot. Repeating `fb connect` resumes valid saved settings. Read the guide before replacing them with `fb connect --replace`.
Read fb help commands for specialized service, boot, node, framebuffer-access and terminal-session controls. Legacy spellings are described separately in fb help compatibility.
### 3. Verify and use it
For an agent or script:
~~~bash
fb status
fb doctor
fb console
~~~
Start with a harmless terminal task, such as reporting the hostname and current directory. Status distinguishes local tools, connection and startup policy. Doctor diagnoses prerequisites; it does not repair or connect.
The console works in a Linux TTY or desktop terminal. A local X11 session adds graphical CUA. Terminal text, real screen captures and explicitly selected virtual displays are identified separately. A VM test does not prove the owner's physical desktop or Wayland.
### Optional virtual desktop
Text mode and an existing X11 desktop work without a virtual desktop. For an explicitly selected virtual display, install its optional tools yourself:
~~~bash
sudo apt install xvfb openbox xauth
~~~
Openbox can register itself as the generic window manager when installed. Review that desktop choice when opting in. Normal FrameBridge installation does not request Xvfb or Openbox; `xauth` remains a shared X11 dependency. `fb doctor` reports virtual-display availability separately. Read `fb help commands` for the explicit virtual mode.
## Use it with an assistant
Give a coding assistant that already has shell access the [FrameBridge agent-start workflow](docs/FRAMEBRIDGE-AGENT-START.md). The same CLI is available for people and scripts:
~~~bash
fb --json status
fb help commands --json
~~~
Explicit JSON output is versioned and does not request interactive input. When owner authentication is needed, it reports INTERACTION_REQUIRED with an action for a normal terminal. The MCP server also invites an agent to read its registered help tool. This supplies usage context; client compliance must not be assumed from the invitation alone.
JSON output is versioned and never prompts. `INTERACTION_REQUIRED` gives an action for the owner's normal terminal. The agent workflow helps an existing shell-based assistant install and diagnose FrameBridge; it does not claim every AI client is a tested replacement for ChatGPT.
## Services, terminals and desktops
`fb` and `framebridge` are names for the same program. Read `fb help` for the English guide and `fb help compatibility` for legacy commands.
Service execution, connection intent, boot policy and saved material are separate:
## Pause, stop or remove
- fb service start and fb service stop control the current stack. The first start of a configured node can also prepare its managed startup; that initial provisioning is reported explicitly.
- fb service boot enable and fb service boot disable control future startup without stopping current work or forgetting a saved credential.
- fb service credentials forget --confirm is a separate destructive operation: it removes the managed connection setup and saved material while retaining the profile and user persistence.
| Intended result | Command | What remains |
| --- | --- | --- |
| Pause the ChatGPT connection until the next explicit connect, including after restart | `fb disconnect` | Local tools and saved material. |
| Stop the current managed stack | `fb service stop` | Future startup policy and saved material. |
| Disable future managed startup | `fb service boot disable` | Current execution and saved material. |
| Remove the package without removing its dependencies automatically | `sudo dpkg --remove framebridge-original-expanded` | User-profile data can remain. |
Persistent Bash sessions retain shell state between calls while the session and service remain alive. They do not preserve running processes across an operating-system reboot. Changing a session's sudo mode recreates Bash and loses its internal shell state; consult the guide before doing so.
Removal stops package-owned managed processes and revokes administrative helper grants. Reinstalling requires an interactive `fb connect` to reprovision what is needed. Removal/purge may retain profiles; forgetting saved connection material is a separate action in `fb help commands`.
CLI terminal observation is text. Real CUA captures are separate, authentic screen evidence. Private virtual displays, when explicitly selected, are identified as virtual.
These controls undo specific operations, not a whole computer snapshot. Bash state persists between calls while the session lives, not across reboots. Changing its sudo mode recreates Bash and loses its shell state.
Independent FBEXEC tasks have been observed to work on one computer when their targets and changes do not overlap. This is not an isolation guarantee. Use one controller at a time for a shared graphical desktop.
## Source, licensing and contributions
## Source, licenses and official releases
Original FrameBridge material is **GNU GPL version 3 only (`GPL-3.0-only`)**. Third-party material keeps its own licenses and notices. Read [LICENSING.md](LICENSING.md), [COPYRIGHT.md](COPYRIGHT.md) and [LICENSE-STATUS.md](LICENSE-STATUS.md).
Original FrameBridge material is licensed under **GNU GPL version 3 only (GPL-3.0-only)**. Third-party material retains its own notices and license terms. Read [LICENSING.md](LICENSING.md), [COPYRIGHT.md](COPYRIGHT.md) and [LICENSE-STATUS.md](LICENSE-STATUS.md).
Versioned source archives include the FrameBridge implementation, builders, tests and legal records. The shared Python/Rust dependency source asset and the tunnel client's dependency sources retain their reviewed historical 0.3.1 filenames. Exact sizes, hashes, scope and upstream provenance are recorded in `licensing/third-party`. The retained tunnel executable is not presented as independently rebuilt from an identified upstream source revision. Building FrameBridge does not claim an independent rebuild of every embedded native component.
The distribution source set contains:
Use `python3 source/packaging/build_expanded.py --help` for package build profiles and `python3 source/packaging/archive_sources.py --help` for source archiving. Building does not install, start, sign or publish the product.
- FrameBridge-0.3.1-source.tar.gz — FrameBridge implementation, builder, tests and legal records.
- FrameBridge-0.3.1-Community-Preview1-dependency-sources.tar.gz — the immutable shared Python/Rust dependency source asset; its historical name is retained deliberately.
- FrameBridge-0.3.1-tunnel-client-dependency-sources.tar.gz — retained source archives and notices for the tunnel executable's Go dependencies.
Exact sizes, hashes, scope and upstream provenance are recorded in licensing/third-party. The retained tunnel executable is not presented as independently rebuilt from an identified upstream source revision.
~~~bash
python3 source/packaging/build_expanded.py
python3 source/packaging/archive_sources.py
~~~
These commands assemble the Debian package and project source archive; they do not install or start FrameBridge. Build prerequisites must already be available. Rebuilding the project package does not claim an independent rebuild of every embedded native component.
Release signatures and publication readiness are recorded separately from the builder. A successful build alone is not proof that a release is signed or publicly available.
Everyone retains the applicable freedoms to modify and redistribute lawful copies. Contributing through the project Git is welcome; it is not an additional license condition. Maintainers review what enters the official repository and sign official releases. Independent variants must not be represented as maintainer-approved releases.
## Community and credits
Read [CONTRIBUTING.md](CONTRIBUTING.md) to propose a change and [SECURITY.md](SECURITY.md) for security reports. Useful compatibility reports name the exact distribution, version, Python version, package profile and tests actually performed. Independent copies retain their applicable software freedoms; they must not be presented as maintainer-approved releases.
Project home: https://framebridge.betancourt.one/
Programming: **ChatGPT**.
Original concept and project coordination: **Gerardo Betancourt**.
FrameBridge is an independent community project. No endorsement by OpenAI is claimed.
Read [CONTRIBUTING.md](CONTRIBUTING.md) before proposing changes and [SECURITY.md](SECURITY.md) for the security process. The English Debian guide is available through fb help and the included documentation. Demonstration animations are conceptual illustrations, not recordings of tool execution.
FrameBridge is an independent community project; no OpenAI endorsement is claimed. Demonstration animations are conceptual illustrations, not recordings of tool execution. Use one controller at a time for a shared graphical desktop. Independent FBEXEC tasks observed on different work targets are not an isolation guarantee.
docs/FRAMEBRIDGE-AGENT-START.md
+102
View File
@@ -0,0 +1,102 @@
# Start FrameBridge with a coding assistant
This is a setup and verification workflow for an assistant that **already has authorized shell access to the target Linux computer**. A person can run the same commands by hand. For first setup, the owner uses that computer's normal terminal and completes the ChatGPT browser approval.
The currently tested connection is the manual ChatGPT workflow. A coding assistant can help prepare it through the CLI; this document does not claim drop-in integration with every AI client.
## Before handing over
Give the assistant the computer you want to work on, the intended task, and the local path of the reviewed matching package. Use the [README's package matrix](../README.md#1-install-the-matching-package). If this is a pilot beside an existing installation, identify a new isolated `--state-dir` and the existing services that must remain running.
Do not put passwords, tunnel IDs, server access keys or browser codes in the prompt. The owner will enter them in the local hidden prompts. An MCP server access key is not an OpenAI API key.
## Copy this into your assistant
~~~text
Help me install and verify FrameBridge on this Linux computer.
Target computer: [the computer to which you already have authorized shell access]
Reviewed package: [absolute local path to the matching FrameBridge .deb]
Scope: [new installation, or the specifically authorized pilot/profile]
First establish where you are running. Inspect the distribution/version,
architecture and system Python. Match them to the package's release profile.
Read the project's README and the installed versioned help where available.
Reuse FrameBridge's existing CLI and package; do not invent a replacement
transport or rewrite the application to complete setup.
Use my existing task authorization. Complete the authorized preparatory work
before asking for information or a decision that is actually missing.
Before package installation:
- Check the exact reviewed file's identity, version and architecture. Verify
an official release through its signature/trusted key. An unsigned candidate
must remain labelled a candidate; a checksum is not a release signature.
- Inspect the actual package-manager plan. Record package versions and relevant
desktop selections before changes. Explain an unexpected upgrade/removal or
desktop change rather than approving a different plan silently.
- For a pilot, keep the existing connection and service processes available.
Use the agreed isolated state directory; do not guess an existing profile.
Treat optional virtual-display prerequisites as optional: install them only
when a virtual desktop is part of my task.
Install the matching local .deb through APT in the owner's normal terminal.
If OS authentication is required, show the exact action and target terminal
once and let me type there. Keep that terminal available until post-install
verification and any required correction have finished. Never ask me to paste
credentials into chat, command arguments, environment variables or a log.
Do not weaken a service's restrictions or grant permanent passwordless root
as a workaround for a restricted execution channel.
Run fb connect interactively in that same normal terminal when connection is
part of the authorized scope. I will supply the hidden connection details and
complete the browser sign-in/approval. Installing a package or setting an
account label is not evidence that ChatGPT is connected.
For programmatic observation, use fb --json status and fb help commands --json.
JSON mode never prompts. If it returns INTERACTION_REQUIRED, use the stated
normal-terminal action; do not send a secret to a noninteractive tool.
Verify installed files, the selected release profile, fb status and fb doctor.
When connected, read FrameBridge's registered help tool before choosing a
small authorized terminal task. Prove a persistent Bash session by keeping
its session ID and checking a variable/working directory in later calls.
Close only the test session and test service you created.
If desktop access is in scope, first identify the actual X11 session and use
a new test window. A virtual display must be described as virtual. Terminal
text is not a screen capture, and a VM's desktop is not the owner's physical
display. Do not claim a screenshot or successful input unless it was observed.
Check actual command exit codes and operation results. An outer tool wrapper's
success flag is not proof that its inner command succeeded. Distinguish local
tool readiness, real connection state, boot policy and saved material.
Finish by comparing the relevant before/after package and desktop state,
confirming original service processes are still running where required, and
giving me a short result: exact version/profile, tests passed, what remains
unproved, and the commands to pause or remove this installation.
~~~
## The same short route without an assistant
After verifying and installing the matching `.deb`:
~~~bash
fb connect
fb status
fb doctor
fb console
~~~
Normal first connection needs no separate `fb setup` or `fb service start`. Advanced roles, enrollment, startup policy and credential management are documented in `fb help commands`.
## Keep undo specific
- `fb disconnect` pauses the connection until the next explicit connect, including after reboot; local tools and saved material remain.
- `fb service stop` stops current managed services without changing future startup policy.
- `fb service boot disable` changes future startup policy without stopping the current stack or forgetting its saved credential.
- `sudo dpkg --remove framebridge-original-expanded` removes the package without automatically removing dependencies. User profiles may remain, and administrative helper grants are revoked. An interactive reconnect can be needed after reinstalling.
Forgetting credentials is a separate destructive operation in the installed guide. Do not use it as routine cleanup or present package removal as a whole-machine restore. For a pilot, retain the original inventory and the exact profile path so the owner can distinguish the test installation from other work.