flowscape
A 3D landscape of your network flows.
Scaffold status: PyPI name reservation. This package is a placeholder scaffold to claim the
flowscapename on PyPI. Implementation has not yet started; see the design spec below for the full v1 plan.
Modern Etherape-shaped network visualization for macOS. SwiftUI + Metal
frontend, Python backend with dpkt for parsing and pcapy-ng for live
capture. Two SOCK_SEQPACKET Unix-domain sockets wire the Swift renderer
to the Python capture pipeline via Protocol Buffers (data plane) and
JSON-RPC 2.0 (control plane).
Reserve the PyPI name
cd /Users/les/Projects/flowscape
uv build
uv publish # uses UV_PUBLISH_TOKEN from env
The package name flowscape is currently free on PyPI (verified 2026-08-31).
Publishing a placeholder 0.1.0 release locks the name.
Design spec
The full v1 design lives in
docs/superpowers/specs/2026-08-31-flowscape-design.md.
Key commitments:
- macOS-only, signed
.appbundle as headline distribution - 3D rendering as a headline feature (orbit camera, click-a-host, hover-to-inspect)
- Structural no-payload guarantee — packet payload bytes never leave the capture process; wire format carries metadata + a 32-byte SHA-256 prefix per edge
- Two-process split — Swift owns GPU/UI; Python owns capture/decode/aggregation/heuristics
- One source of truth for IPC —
proto/flowscape.protogenerates both Python (betterproto2) and Swift (SwiftProtobuf) types
Architecture (planned)
| Module | Purpose |
|---|---|
settings.py |
Oneiric settings model (FlowscapeSettings extends MCPServerSettings) |
capture.py |
libpcap source via pcapy-ng; pcap_thread posts packets to asyncio |
decode.py |
dpkt parsing; emits FlowEvent with payload_sha256_prefix (32-byte) |
aggregate.py |
Per-flow rolling counters + per-host byte totals (60s window) |
graph.py |
Derives GraphState from aggregator on tick |
heuristics.py |
Beaconing, port-scan, top-N churn detectors |
publisher.py |
Encodes graph snapshots + alerts as protobuf on data.sock |
ipc_server.py |
JSON-RPC on control.sock |
app.py |
Oneiric-driven entrypoint; signal/cleanup |
cli.py |
flowscape live, replay, doctor, interfaces, version |
Realistic v1 timeline: 14-20 weeks for one experienced developer.
Status
| Phase | State |
|---|---|
| PyPI name reservation | pending (run uv publish) |
| Spec / design | complete (in mahavishnu/docs/superpowers/specs/) |
| Implementation | not started |
| Tests | not started |
License
BSD-3-Clause. See LICENSE.
Etherape is GPLv2. We do not study its source code — see the design spec for the clean-room protocol.
1 maintainer
Metadata
1 maintainer
Release files for flowscape 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| flowscape-0.1.0.tar.gz | 4.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| flowscape-0.1.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 8.6 kB
Release files / flowscape-0.1.0.tar.gz
| Download URL | flowscape-0.1.0.tar.gz |
|---|---|
| Size | 4.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
248a5f41d5d5cc94531abbb09cb8b065dab851ab1679efca5824f3ca26e1e7d0
|
|
BLAKE2b-256 checksum How to use checksums |
5701513a4240320a510c7fac413d2b4e4fac86541799eeb98a0879cc088f9542
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / flowscape-0.1.0-py3-none-any.whl
| Download URL | flowscape-0.1.0-py3-none-any.whl |
|---|---|
| Size | 4.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
28610092415191cca69ec7fb92d018b73e50d562485c34f6ce6df455dc8a8d59
|
|
BLAKE2b-256 checksum How to use checksums |
3bdd29164e661e6aea8d0222d7896e2d180e362949fcab81a01fc761f6fde728
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
