Agent Forge customer-owned connector

Requirements: Python 3.11+. Open a terminal INSIDE this extracted folder.
Use the Mac/Linux or Windows commands shown in your world. They create a private
Python environment and install the public CA roots. Manual environment setup:
python -m pip install -r requirements-connector.txt
The generic connector uses no model-provider SDK. HTTPS verification remains enabled.
Install the framework/provider SDKs your own agents require separately.

Fast path for an existing JSON HTTP agent:
python connect.py
Use Create my world & connect in the web app to get a command: no JSON upload needed.
The guided setup asks for your endpoint and pairs using the hidden one-use code.
Restart later using the SAME command/settings file. For a revoked token, add --re-pair.
To correct a saved endpoint or token, stop the connector and add --configure.
No agent or provider call is made until you launch a task from your world.
Endpoint contract: POST {"prompt":"..."} returns {"text":"..."}. Provider keys stay local.

Advanced Python agent path:
1. Extract this folder somewhere private on the machine running YOUR agents.
2. Edit my_team.py: replace the explicit placeholder with your existing agent call.
   Keep provider credentials in your own environment. Never upload them to Forge.
3. Export your team definitions (does not run the handler or call a provider):
   python -m integrations.runner --team my_team:team --export-manifest agent-team.json
4. Upload agent-team.json in World Studio and build the world.
5. Click Pair a runtime and run the command shown there. Use --team my_team:team
   and the unique private --config filename shown for this world.
6. Paste the one-use code into the connector's hidden prompt. Keep it running.
7. Launch a bounded task in your world. Your handler runs here, using your account.

Only expose handlers you intend workspace operators to launch. Do not wrap arbitrary
shell execution or give untrusted operators privileged agents. Pause/cancel applies at
wrapped step boundaries; in-flight calls can finish. A process restart cannot resume
in-memory execution and unfinished runs are never automatically replayed.

Server option: use a Linux server you already own. Pair there once, then generate
an optional user service with:
.venv/bin/python scripts/server_service.py --settings YOUR_SAVED_SETTINGS.json
Follow https://forge.ku13sh.com/static/connect.html#server to install it. The helper
only writes a file; it does not change the server, install a service or buy hosting.
The connector and agent must both run somewhere that stays online. A sleeping laptop
cannot run its local agents. Forge supplies no server or provider allowance.

Stop: Ctrl+C. Revoke: Disconnect runtime in World Studio. A token revocation blocks
future server access but cannot forcibly kill a function already running here.

Prompt text, selected progress, reports and measured usage go to the Forge workspace.
Agent code and provider keys remain local. This kit supplies no model or AI credits.
