# flylab connection notes

Current local edition: read [RUN.md](./RUN.md). The default endpoint is unset.
This edition uses an open lab and the unchanged experimental neural backend.
The instructions below are adapted from the supplied connection handoff; external
hosting and paid services are not configured by this package.

# flylab: what is needed for live brain activity

8 September 2026. This viewer is at http://localhost:8080 . Its neural endpoint is currently unset. The connection UI and server code are included; the neural service still needs a host.

## What you already see

The browser displays 1,430 sampled MaleCNS cell-body locations next to the selected fly. This anatomical view and the local behavior demo need no remote GPU. The anatomy is a sample, not a rendering of every neuron and its full branches.

Live colors require measured spike rates from the included experimental Python model. Google's article describes an anatomical wiring map, not a hosted live-activity API or a validated functional fly simulator: https://blog.google/innovation-and-ai/technology/research/male-fruit-fly-brain-map/ . Connecting our server shows our model's activity on that connectivity; it does not turn its behavior into biologically validated behavior.

## The host must provide

| Requirement | What to supply |
| --- | --- |
| Persistent compute | A Linux machine or container that can keep the Python service running, with authorized terminal or container access for installation and deployment. A generic LLM inference API is insufficient. |
| Python/data | Python 3.11+, the pinned requirements, and permission to download the official MaleCNS dataset. Raw downloads total about 1.1 GB; the importer needs several GB of RAM and at least 3 GB of disk for data alone. Dependencies, Docker images and retained checkpoints need additional space. Peak import RAM is not measured. |
| Durable volumes | Keep `data/graph` and `state` across restarts. Retain the matching atlas, source manifest and checksums. |
| Browser access | A public `wss://HOST/ws` endpoint with TLS and WebSocket upgrades, routed to the Python service. The existing HTTPS Site can remain the viewer host. |
| Authentication | Configure a random secret as `FLYWORLD_TOKEN` through the host secret manager, and allow the viewer origin with `FLYWORLD_ORIGINS`. Enter the secret into the app's Session token field; never put it in public configuration or send it in chat. |
| GPU, if supplied | The implemented acceleration path uses NVIDIA CUDA and PyTorch (`Dockerfile.cuda`). Supply the GPU model and VRAM so the agent can run numerical parity and throughput checks. A provider must allow a persistent process and incoming WebSockets. |

CPU execution is functional. The recorded 12-brain benchmark took a median 1,371.8 ms to compute 50 ms of simulation time, approximately 27 times slower than real time. That benchmark is in `docs/cpu-benchmark-v02.json`; it is not a hardware sizing guarantee or a public-server latency measurement. No GPU model, VRAM minimum, parity result or real-time GPU performance has been verified. Benchmark the available hardware before committing to capacity or speed.

## Bring the service online

1. Give the deployment agent authorized access to that host and the complete source bundle. It needs the host's CPU/RAM/disk details, any GPU details, and its domain or WebSocket route. Set secrets through the host, not in the source bundle.
2. Follow `ORBOFI-CONNECTION-TASK.md` to import the official graph and build the matching atlas. Retained graph: 164,506 typed neurons and 25,135,616 directed edges. Each of twelve agents owns its neural state and shares the same source anatomy.
3. Set `FLYWORLD_ORIGINS=http://localhost:8080` and the secret, then launch behind the host's TLS proxy:

```bash
python -m backend.server --graph data/graph --host 127.0.0.1 --port 8765 --state-dir state --device cpu
```

For the supplied Dockerfiles, the service listens on container port 8000 by default. Map the host's proxy accordingly. Use `--device cuda` only after installing the CUDA dependencies and verifying the device.

4. In flylab, choose **Connect live brain**, enter the real `wss://HOST/ws` endpoint and the session token, and connect. For subsequent visitors, the agent can prefill the endpoint by running:

```bash
python configure_neural.py wss://YOUR_ACTUAL_HOST/ws
```

Then publish the updated `dist/neural-config.json` and matching atlas. The token remains separate and is not persisted by the viewer.

5. Verify all twelve residents, advancing measurement windows, pause/resume, wrong-token rejection, atlas matching and disconnection behavior at the actual public endpoint. Run CPU/CUDA parity and full-population benchmarks when using a GPU. Add measured results and hosting instructions to the handoff.

The service currently hosts one shared world. All authenticated viewers can control it. Browser rendering performance and server neural throughput are separate measurements.

## If the server is your own computer

You can run both services locally: serve `dist` over HTTP and start the Python backend. Open the local viewer and use `ws://127.0.0.1:8765/ws`, adding that local viewer's origin to `FLYWORLD_ORIGINS`. The hosted HTTPS viewer needs a secure WSS endpoint; a local HTTP trial does not publish a server for other people.

## Compatibility

The app is now named **flylab**. Existing `FLYWORLD_*` environment variables, model version identifiers, and the download path `flylab-source.zip` remain stable so previous server setups continue to work. Historical reports named flylab remain evidence for the same implementation.