Networking and TLS

By default Portside instances listen on localhost only. The LAN (TLS) option lets other machines on your network connect to an instance, with encryption handled per instance by a self-signed certificate.

Local versus LAN strings

Button	String	Works when
Copy connect	localhost host, mapped port	From the machine running Portside and Docker
Copy LAN	This machine's LAN IP, instance port	From any machine on the same network, for LAN-enabled instances

Both strings are ready to paste into .env files, DATABASE_URL, or an agent's configuration. Copy LAN is only available on instances with LAN enabled.

Enabling LAN (TLS)

Toggle LAN (TLS) on an instance. Portside:

1. Makes the container's port reachable from other machines on the network, not just localhost.
2. Encrypts connections with a self-signed certificate generated for that instance.

The self-signed certificate caveat

Self-signed TLS means traffic is encrypted at rest on the wire, but clients do not verify the certificate by default. Practical consequences:

• Encryption vs authentication: the connection is encrypted, but a man-in-the-middle on your network could in principle impersonate the server. Most LAN-only dev setups accept this trade.
• Client-side flags: SQL clients vary in how they treat self-signed certs. Postgres' libpq defaults sslmode to prefer (accepts self-signed), MySQL/mariaDB clients may need --ssl-verify-server-cert=off depending on version, and Redis clients commonly need ssl: false plus accept_invalid_certs: true or equivalent. If a client refuses to connect, look for its "verify certificate" or "trust self-signed" setting first.
• Scope it like a dev environment: LAN sharing is designed for your home or office network during active development, not for exposing databases to the internet. Firewalls still apply; keep the host machine's firewall carve-out permissive only on the local subnet.

The intended pairing is the network you already trust: a laptop running an agent, a desktop running Portside, both on the same LAN.

Agent-on-another-machine workflow

This is the configuration the LAN feature was built for:

Desktop (Portside)             Laptop (coding agent + your IDE)
[Postgres 17 instance]  <--TLS--> .env: DATABASE_URL=(LAN string)

1. On the desktop, create the instance and toggle LAN (TLS).
2. Copy the Copy LAN string.
3. On the laptop, paste it into the agent's environment.
4. Prototype; when done, stop the instance, remove it, or wipe it in Portside from the desktop - the laptop needs nothing installed.

Troubleshooting LAN connections

Symptom	Likely cause	Fix
LAN string refused, localhost works	LAN toggle not enabled on that instance	Toggle LAN (TLS), recopy the LAN string
Connection closed on start	Client requires verified cert	Enable the client's trust-self-signed option or downgrade sslmode
Connects locally but not across machines	OS firewall blocking the port	Allow the instance's port on the host machine's firewall for the local subnet
Wrong IP in LAN string	Multiple network adapters (VPN, virtual NIC)	Regenerate/copy the LAN string after disabling the VPN, or pin the port and hand-build the string with the desktop's LAN IP

Note that restarting an instance rebinds to its stored port; if the mapped port changed after a container restart while using auto-assignment, recopy the connect or LAN string.