# Twoman 1.0.0

Twoman 1.0.0 is the Go dataplane and managed-host Node release.

This release keeps the public host in the path for camouflage, but moves the
high-throughput helper/agent runtime to Go, makes the Node broker advertise the
profile it is actually running, and adds WARP-aware hidden-server routing for
hosts that are only reachable through WireProxy/WARP.

## Highlights

- Added `helper-agent/`, a Go helper/agent runtime for the local client and
  hidden server dataplane.
- Made the Linux server deploy path use Go by default:
  `scripts/deploy_hidden_server.sh` and
  `scripts/install_hidden_server_local.sh` build and install
  `twoman-helper-agent`.
- Made the local client script use Go by default:
  `scripts/start_client.sh` builds `helper-agent` and runs it in helper mode.
- Made Android use the packaged Go helper binary instead of the embedded Python runtime.
- Made desktop helper sidecars use the Go helper runtime:
  `desktop_app/scripts/build_sidecars_linux.sh`,
  `desktop_app/scripts/build_sidecars_windows.bat`, and source-mode desktop
  runtime now prefer the Go helper.
- Added broker-advertised managed-host capabilities in
  `host/node_selector/broker.js`, including data upload worker counts, upload
  batch sizing, down-lane selection, cipher suites, and max frame size.
- Added adaptive runtime overrides in the Go transport so helper/agent can
  apply broker-advertised profiles or explicit config overrides.
- Increased the fast managed-host profile defaults to the measured production
  shape:
  `32` helper data upload workers, `8` agent data upload workers, `512 KiB`
  data upload batches, `6 ms` data flush delay, `4 MiB` broker bulk batches,
  and larger Go stream windows/reorder buffers.
- Reduced dataplane overhead by avoiding unnecessary frame/body copies in the
  Go transport and receive path.
- Added `scripts/benchmark_live_ceiling.py` to record raw host ingress and
  end-to-end tunnel throughput against a live deployment.
- Enabled generated camouflage websites by default in host deploy scripts.

## Acknowledgements

Thanks to [@motixo](https://github.com/motixo) for the pull requests that moved
Twoman's dataplane direction forward:

- [#2](https://github.com/ShahabSL/twoman/pull/2) introduced the AES-256-CTR
  migration work across the broker and edges.
- [#3](https://github.com/ShahabSL/twoman/pull/3) introduced the Go
  helper/agent rewrite that became the foundation for the 1.0.0 dataplane.

The final 1.0.0 integration includes additional hardening, deployment, client,
benchmark, documentation, and packaging work on top of those contributions, but
those PRs are the upstream contribution that started the Go release track.

## WARP and Outbound Routing

WARP support in this release is specifically for the hidden server side.

- `TWOMAN_UPSTREAM_PROXY_URL` routes hidden-server traffic to the public broker
  through a proxy such as local WireProxy/WARP.
- `TWOMAN_OUTBOUND_PROXY_URL` routes final hidden-server egress through a
  separate proxy when desired.
- `scripts/deploy_hidden_server.sh` and
  `scripts/install_hidden_server_local.sh` auto-detect local WireProxy on
  `127.0.0.1:1280` and use it for broker reachability and outbound egress
  unless overridden.
- WARP does not remove the public host from the architecture. The visible
  tunnel still traverses the managed host, so camouflage and host limits still
  matter.

## Performance

Latest stable live benchmark artifact:
`output/twoman-toork-stable-candidate-20260507T143900Z.json`

Measured on `2026-05-07` against the live `/parvaneh` managed-host Node path:

- Go tunnel, 1 concurrent 100 MB download:
  `30.81 Mbps`.
- Go tunnel, 4 concurrent 100 MB downloads:
  `51.30 Mbps`.
- Go tunnel, 1 concurrent 25 MB upload:
  `29.48 Mbps`.
- Go tunnel, 4 concurrent 25 MB uploads:
  `49.37 Mbps`.
- Go tunnel, 8 concurrent 25 MB uploads:
  `49.07 Mbps`.

The release default is the broker-advertised stable profile: `32` helper data
upload workers, `8` agent data upload workers, `512 KiB` data upload batches,
`4` data down polls, and a `4 MiB` broker bulk lane. Higher concurrency is not
automatically better on the managed host; aggressive profiles reached higher
download bursts, but repeated stress showed stalls and upload instability.

Best aggressive download-only artifact:
`output/twoman-toork-absolute-aggregate-20260507T133821Z.json`

That profile reached `79.74 Mbps` at 8 concurrent 100 MB downloads. It is
documented as an upper-bound burst result, not the default.

More detail: [../PERFORMANCE.md](../PERFORMANCE.md)

## Operator Options

New or promoted deploy/runtime controls:

- `TWOMAN_DATA_UP_WORKERS`
- `TWOMAN_DATA_UP_MAX_BATCH_BYTES`
- `TWOMAN_DATA_UP_FLUSH_DELAY_SECONDS`
- `TWOMAN_HELPER_DATA_UP_WORKERS`
- `TWOMAN_AGENT_DATA_UP_WORKERS`
- `TWOMAN_HELPER_DATA_UPLOAD_MAX_BATCH_BYTES`
- `TWOMAN_AGENT_DATA_UPLOAD_MAX_BATCH_BYTES`
- `TWOMAN_HELPER_DATA_UPLOAD_FLUSH_DELAY_SECONDS`
- `TWOMAN_AGENT_DATA_UPLOAD_FLUSH_DELAY_SECONDS`
- `TWOMAN_ADAPTIVE_UPLOAD_ENABLED`
- `TWOMAN_ADAPTIVE_UPLOAD_MIN_WORKERS`
- `TWOMAN_ADAPTIVE_UPLOAD_INITIAL_WORKERS`
- `TWOMAN_ADAPTIVE_UPLOAD_MAX_WORKERS`
- `TWOMAN_ADAPTIVE_UPLOAD_MIN_BATCH_BYTES`
- `TWOMAN_ADAPTIVE_UPLOAD_MAX_BATCH_BYTES`
- `TWOMAN_ADAPTIVE_UPLOAD_INCREASE_AFTER_SUCCESSES`
- `TWOMAN_ADAPTIVE_UPLOAD_DECREASE_AFTER_ERRORS`
- `TWOMAN_ADAPTIVE_UPLOAD_BACKLOG_THRESHOLD_FRAMES`
- `TWOMAN_ADAPTIVE_UPLOAD_DECISION_INTERVAL_SECONDS`
- `TWOMAN_UPSTREAM_PROXY_URL`
- `TWOMAN_OUTBOUND_PROXY_URL`

## Compatibility Notes

- Python helper/agent runtime code was removed from the shipped client/server
  path for this release.
- Android, desktop, local CLI, and hidden-server installs use the Go helper.
- Desktop Proxy/System proxy modes use the Go helper sidecar after rebuilding
  sidecars. The separate desktop gateway and Windows TUN sidecar remain
  separate components.

## Validation

Validated before release handoff:

- `go test ./...` in `helper-agent/`
- shell syntax checks for deploy/start scripts
- `node --check` for `host/node_selector/broker.js` and bundled `app.js`
- focused Python tests
- `tests/run_e2e_go_node_http.sh`
- `tests/run_desktop_client_e2e.sh`
- `cargo check --manifest-path desktop_app/src-tauri/Cargo.toml`
- Android `assembleArm64Debug`
- live host redeploy for `/parvaneh`
- live hidden-server Go agent redeploy
- live 100 MB tunnel benchmark

## Rebuild Scope

Rebuild release artifacts that include helper/agent runtime changes:

- Linux server installer/deploy bundle
- Linux desktop sidecars
- Windows desktop sidecars and portable bundle
- Android APK/AAB because the app now packages the Go helper binary for each
  supported ABI.
