Table of Contents

Network

Last updated:

Network settings control how the Oscova host listens, whether web_fetch may read trusted private pages, and which address Oscova uses for QR sharing and generated absolute links.

Note

A listener is the address and port where the web server accepts connections. The public app URL is an address Oscova advertises. It does not configure DNS, TLS, a proxy, or the listener itself.

Who can change these settings

Only the administrator can see or use the Network section. The settings are system-wide, and server requests from regular users are rejected.

Allow access from other devices

Enable Allow access from other devices when phones, tablets, other computers, or LAN services must open Oscova.

Set Port from 1 to 65535. The default is 11317.

Click Save Network Settings to persist the draft. Reset discards unsaved edits.

Important

Saved access and port changes require an Oscova restart. The warning remains while the saved listener intent differs from Active Server URLs.

After restarting:

  • Local URL uses localhost and the saved port.
  • Auto Network URL uses a detected LAN IPv4 address when one is available.
  • Active Server URLs shows the listeners opened during startup.

Enabling network access does not change firewall rules. If another device still cannot connect, allow the selected port through the host firewall and any intervening network controls.

Allow trusted private web fetches

The built-in web_fetch tool normally accepts public HTTP and HTTPS destinations but rejects loopback and private-network addresses. This reduces the chance that a malicious page or prompt can make the agent inspect an internal service.

Enable Allow fetching local and private-network URLs only when agents must read trusted resources such as:

  • a local documentation server.
  • a private intranet page, or
  • a service on a private LAN address.

The setting takes effect after save and does not require a host restart. It allows loopback, RFC 1918 private IPv4, and IPv6 unique-local destinations. Unspecified, link-local, carrier-grade NAT, multicast, and reserved ranges stay blocked.

Address checks also apply after DNS resolution and redirects. A redirect to a disallowed address is rejected.

Caution

This toggle weakens web_fetch protection. It does not grant browser login access and does not override Offline mode, which removes the Internet-scoped web_fetch tool from air-gapped agent runs.

Allow sandbox network access

Allow sandbox network access is an administrator-controlled, installation-wide grant for Docker shell execution. It is off by default. When enabled, every user's ordinary online sandbox run uses Docker bridge networking. Individual users cannot enable or override it for themselves.

The setting takes effect after Save Network Settings and does not require a host restart. Local-only and air-gapped runs always force Docker networking off, even when the installation-wide grant is enabled.

Caution

A network-enabled container can contact destinations independently of Oscova's HTTP clients. That traffic is outside Oscova's egress ledger, so enable the grant only when all users and sandbox workloads are trusted to use network access.

Choose the public app URL

Mode controls the address Oscova advertises:

  • Auto-detected network URL uses the detected LAN address and saved port. It is unavailable when network access is disabled or no suitable interface is detected.
  • Custom URL uses the complete absolute address you enter, such as https://oscova.company.local.

Use a custom URL when a reverse proxy, tunnel, hostname, or HTTPS gateway provides the externally reachable address.

Saving a public URL updates later generated links and the Network summary without restarting the listener. The current host does not verify that the custom address resolves or is reachable.

Important

OAuth callbacks do not use this public URL setting. Connected Accounts builds its callback from the current request scheme, host, and path base. Open Oscova through the address the provider can return to before starting OAuth consent.

Effective Public App URL shows the selected advertised address. Oscova uses it for the QR code and when a feature must turn an app-relative resource into an absolute URL, such as media consumed by another runtime.

Share the QR code

When an effective public URL exists, expand QR Code and scan it from another device. Click Download QR Code to save the PNG.

The QR code contains only the effective URL. It does not bypass login, configure the firewall, or prove the address is reachable.

Troubleshooting

  • Another device cannot connect: enable network access, save, restart Oscova, and check the firewall.
  • Restart warning remains: compare the saved access and port with Active Server URLs.
  • Auto network URL unavailable: use a custom URL or fix the host's active network interface.
  • Port rejected: choose a value from 1 to 65535.
  • Custom URL rejected: enter a complete absolute URL with a scheme.
  • Custom URL opens the wrong service: correct the proxy, DNS, or URL. Saving does not configure them.
  • OAuth returns to the wrong host: reopen Oscova through the intended address, then restart the connection flow.
  • Private web_fetch target blocked: enable the private fetch setting only for a trusted destination.
  • Target remains blocked: its resolved address may be link-local, reserved, multicast, or otherwise non-routable.
  • QR code is wrong: check Mode and Effective Public App URL, then regenerate it.