roof/pic

Fork 0

Table of Contents

Admin – Configure Connectivity

Concepts

Connection instances
Fail-open vs fail-closed
Cell-relay connections

Setting up a connection

Purpose
Prerequisites
Steps
Verification
Rollback

Assigning a peer to a connection
Assigning a service to a connection
Connection health
Removing a connection
Cell-to-cell links

Status: Active | Owner: @roof | Applies to: main (2026-06) | Updated: 2026-06-11

Admin – Configure Connectivity

The Connectivity feature lets you route individual peers (or services) through an alternate exit instead of the cell's default internet gateway. This is useful for privacy, geographic routing, or compliance requirements.

Concepts

Connection instances

A connection is a named, configured instance of an exit type. You create as many as you need and give each a name (for example, "Home VPN", "US Exit", "Tor").

Once a connection is created, you assign peers to it. Each peer uses exactly one connection (or the default gateway if none is assigned).

Connection types:

Type	Mechanism	Required service
`wireguard_ext`	WireGuard client tunnel to an external server	`wireguard-ext`
`openvpn`	OpenVPN client tunnel	`openvpn-client`
`tor`	Transparent proxy through Tor SOCKS	`tor`
`sshuttle`	SSH tunnel via sshuttle	`sshuttle`
`proxy`	HTTP/SOCKS5 upstream proxy via redsocks	`proxy`

ℹ️ Note: Tor is limited to one instance per cell. All other types support multiple named instances.

Fail-open vs fail-closed

When the exit a peer is assigned to goes down, PIC decides whether to block the peer's traffic or let it fall back to the direct internet:

Fail-closed (default for all types except Tor): if the exit is down, traffic from that peer is blocked by a kill-switch FORWARD rule in cell-wireguard. The peer loses internet access until the exit recovers.
Fail-open (default for Tor only): if the exit is down, traffic falls back to the default gateway.

You can override the fail-open behaviour per peer from the peer's detail page or via:

PUT /api/connectivity/peers/<peer_name>/failopen

Cell-relay connections

A cell-relay connection is auto-derived from a cell-to-cell link where the remote cell offers its internet exit. You do not create these manually — they appear automatically in the connection list when a linked cell advertises an exit. Assigning a peer to a cell-relay connection routes their traffic through the remote cell's WAN. Cell-relay connections fail-closed by default.

Setting up a connection

Purpose

Route one or more peers through an alternate internet exit.

Prerequisites

Install the corresponding exit service from the Services catalog first (for example, install wireguard-ext before creating a wireguard_ext connection). See Admin – Manage Services.

Steps

Go to Connectivity in the sidebar.
Click Add Connection.
Choose the type, give it a name, and fill in the required config (for example, upload the WireGuard config file for wireguard_ext, or supply the host/user/port for sshuttle).
Click Save.

The connection now appears in the list with a health status indicator.

Verification

The connection should appear with a working status. If it shows down or unknown, check the exit service logs from the Logs page.

Rollback

Delete the connection from the Connectivity page (after unassigning any peers). The exit service remains installed; only the connection instance is removed.

Assigning a peer to a connection

Go to Connectivity and select the connection.
In the Peers tab, add the peer by name.
Click Apply.

Alternatively, from the Peers page, open a peer and set the Exit field.

PIC immediately applies the routing change in cell-wireguard using fwmark and policy routing tables. No restart is needed.

Assigning a service to a connection

Services that declare has_egress: true in their manifest (typically the email service) can have their outbound traffic routed through a specific exit. From the Connectivity page, select a connection and go to the Services tab.

Connection health

Each connection has a health status: working, down, or unknown. PIC probes health on demand when you load the Connectivity page, and caches the result for 30 seconds. You can also request an immediate probe:

GET /api/connectivity/connections/<conn_id>/health

Health check mechanism by type:

Type	How health is checked
`wireguard_ext`	Last WireGuard handshake age (down if older than 3 minutes)
`openvpn`	Interface presence check
`tor`	TCP connect to Tor SOCKS port
`sshuttle`	TCP connect to the sshuttle transparent proxy port
`proxy`	TCP connect to the redsocks proxy port

Removing a connection

A connection cannot be removed while peers are assigned to it. First unassign all peers (set their exit to default), then delete the connection from the Connectivity page. Deleting a connection that is still in use returns HTTP 409.

Cell-to-cell links

Cell-to-cell links (site-to-site WireGuard tunnels between two PIC cells) are managed from the Cell Network page, not the Connectivity page. When a remote cell offers its internet exit, the resulting cell_relay connection appears automatically in the Connectivity page's connection list and can be assigned to peers like any other connection.

Internals: see Dev – Architecture

Personal Internet Cell

Home