Status: Active | Owner: @roof | Applies to: main (2026-06) | Updated: 2026-06-11
Admin – Manage Services
Optional services are installed from the built-in service store. None of them run by default — only the six core containers start automatically.
Core containers (always running)
| Container | Purpose |
|---|---|
cell-caddy |
Caddy reverse proxy, TLS termination |
cell-dns |
CoreDNS — .cell TLD and split-horizon DNS |
cell-ntp |
chrony NTP server for VPN peers |
cell-wireguard |
WireGuard VPN (NET_ADMIN capability only, not privileged) |
cell-api |
Flask REST API |
cell-webui |
React web UI (Nginx) |
ℹ️ Note: PIC does not include a DHCP server. The
cell-dnscontainer runs CoreDNS only.
Available store services
| Service ID | Name | What it provides |
|---|---|---|
email |
Email Server | Postfix + Dovecot SMTP/IMAP; per-peer mailboxes |
calendar |
Calendar and Contacts | Radicale CalDAV/CardDAV; per-peer calendars and address books |
files |
File Storage | WebDAV per-user storage + Filegator browser-based file manager |
webmail |
Webmail | Roundcube webmail UI; requires the email service |
wireguard-ext |
WireGuard External Exit | Route selected peers through an external WireGuard server |
openvpn-client |
OpenVPN Exit | Route selected peers through an OpenVPN server |
tor |
Tor Exit | Route selected peers through Tor (transparent proxy) |
sshuttle |
SSH Tunnel Exit | Route selected peers through an SSH server via sshuttle |
proxy |
HTTP/SOCKS5 Proxy Exit | Route selected peers through an upstream proxy via redsocks |
Installing a service
- Go to Services in the left sidebar.
- Find the service card.
- Click Install. PIC fetches the manifest from
git.pic.ngo/roof/pic-services, validates it, starts the container(s), and wires up DNS and Caddy routes automatically. - The service card shows a progress state while installation runs. Reload the page to check status.
- Once installed, the service appears in the sidebar navigation.
Image signature verification
Every store image is digest-pinned and signed by the PIC build pipeline. Before starting a container, the cell verifies the image signature with cosign against the bundled public key. The mode is the image_verification setting in config/api/cell_config.json (changing it requires an API restart):
| Mode | Behaviour |
|---|---|
enforce (default) |
Installation is refused if the image is not digest-pinned, unsigned, or the signature does not verify. |
warn |
Verification failures are logged but installation proceeds. |
off |
No verification. |
Leave it on enforce unless you are developing your own service images — see Dev – Build a Store Service.
Using installed services
Each installed service gets a subdomain. For example, with cell name myhome and domain mode pic_ngo:
| Service | URL |
|---|---|
| Email (webmail, if installed) | https://mail.myhome.pic.ngo |
| Calendar | https://calendar.myhome.pic.ngo |
| Files | https://files.myhome.pic.ngo |
IMAP/SMTP ports for email:
| Protocol | Port | Security |
|---|---|---|
| IMAP | 993 | SSL/TLS |
| SMTP (submission) | 587 | STARTTLS |
These ports are only opened on the host when the email service is installed.
Managing peer accounts on services
Each installed service can provision per-peer accounts. From the service's admin page (for example /services/email):
- Go to the Accounts tab.
- Click Add Account and enter the peer's username. PIC generates a password automatically, or you can supply one.
- The peer can see their connection credentials from the peer dashboard.
To remove a peer's account, click Remove next to the account entry. When a peer is deleted from the Peers page, their accounts on all services are also removed automatically.
Uninstalling a service
- Go to Services in the sidebar.
- Click Uninstall on the service card.
The container is stopped and removed. Service data in data/services/<id>/ is kept on disk. You must delete it manually if you want to free the space. Use the API-driven backup before uninstalling if you want to preserve user data — see Admin – Back Up and Restore.
Service status
The Services page shows each installed service with a running/stopped indicator. You can also query the API:
# Run on: the cell server host (or via the VPN)
curl -s http://127.0.0.1:3000/api/services/active
To restart a service from the command line:
# Run on: the cell server host, from /opt/pic
make shell-api
# then inside the container, call:
# POST /api/services/catalog/<id>/restart
Connectivity exit services
The five connectivity exit services (wireguard-ext, openvpn-client, tor, sshuttle, proxy) integrate with the Connectivity feature. After installing one, you create a named connection instance from the Connectivity page and then assign peers to it. See Admin – Configure Connectivity for details.
Internals: see Dev – Architecture
Personal Internet Cell
New here?
Users
User – Connect to the VPN User – Use Your Services User – Troubleshooting
Admins
Admin – Overview Admin – Install and First Run Admin – Configure Domains and TLS Admin – Manage Services Admin – Configure Connectivity Admin – Manage Peers Admin – Back Up and Restore Admin – Logging and Audit Admin – Monitor and Troubleshoot
Developers
Dev – Overview Dev – Architecture Dev – Build a Store Service Dev – Service Manifest Reference Dev – API Reference Dev – Testing Dev – Install Internals
Decisions (ADRs)
ADR – 001 Store Images Are Signed and Verified by Cells ADR – 002 Named Connection Instances for Connectivity ADR – 003 All Optional Functionality Ships as Store Services
Meta
Meta – Glossary Meta – Template Runbook Meta – Template ADR
Archive
Archive – User Guide Archive – ADR 004 The Wiki Is the Single Documentation Source