byway

Byway · English noun

A secondary road or path, away from the main route.

byway is a userspace client that speaks the Cisco AnyConnect VPN protocol. No tun device, no virtual adapter, no routing changes, no administrator rights: the tunnel and everything carried over it live inside the Python process. Access is through a local SOCKS5 proxy, so ssh and curl work unchanged, and an in-process API.

Use it when you need to reach a REST API or SSH into a host inside a corporate VPN, but cannot, or would rather not, install a VPN client, change routing, or use admin rights. VPN access is scoped to one process rather than to the whole machine.

Install and run

$ uv tool install byway
$ byway probe vpn.corp.example          # what does this gateway ask for?
$ byway up vpn.corp.example -u user --socks
address   172.29.29.3/255.255.0.0
mtu       1383
routes    10.0.0.0/23
socks5    127.0.0.1:1080

byway up prompts for the password and holds the tunnel open. From another terminal:

curl --socks5 127.0.0.1:1080 http://10.0.0.20/
ssh -o ProxyCommand="byway nc --via 127.0.0.1:1080 %h %p" user@10.0.0.32

Saved profiles, other ways to pass the password, and certificate pinning are in the manual.

Use it from your own program

uv add byway

import byway

async with byway.connect("vpn.corp.example", user, password) as vpn:
    reader, writer = await vpn.open_connection("10.0.0.32", 22)

    async with vpn.httpx_client() as http:
        response = await http.get("http://10.0.0.20/v1/things")

Caveats

• Hosts are IP addresses, or names from a fixed table in the profile: there is no in-tunnel DNS.
• byway supports IPv4, TLS, outbound TCP and username/password authentication only.
• Many organisations require a sanctioned VPN client, and byway bypasses posture assessment (CSD/HostScan) entirely. Check that you are allowed to use it before you point it at a corporate gateway.

Documentation

• docs/MANUAL.md — all commands, profiles, credentials, certificate pinning and the library API.
• docs/http-async.md — calling REST APIs from async code.
• docs/http-sync.md — calling REST APIs from sync code.
• docs/OPERATIONS.md — runtime behavior: idle timeouts, reconnects, sessions, throughput, diagnostics.
• docs/DESIGN.md — architecture, core principles and deliberate omissions.
• docs/protocol.md — protocol notes and gateway observations.
• docs/throughput.md — throughput measurements.
• docs/DEVELOPMENT.md — building and testing.

AI disclosure

Substantial parts of this code were generated with Sonnet 5.x/Opus 5.x. Generated code was tested, but not every line was reviewed in detail.

License

0BSD