← Integrations

External Connections (execonnect)

An External Connection lets your VMs reach a service on a private network, like an internal API or a staging server behind a firewall. You run execonnect on a machine in that network. It dials out to exe.dev, so you don't need inbound ports, a public IP, or a VPN.

VMs use the service through an HTTP Proxy integration:

VM ──► NAME.int.exe.xyz ──► exe.dev ══ tunnel ══► execonnect ──► your service

VMs can only reach endpoints you publish, and execonnect can't reach your VMs.

Quick start

1. Create a connection. On the Integrations page, add an External Connection, or run:

exe.dev ▶ integrations setup execonnect --name=office

Add --team to share it with your team. Copy the execonnect enroll … command it shows; the token is single-use and isn't shown again.

2. Install and start execonnect on a machine in your network:

curl -fsSL https://exe.dev/execonnect/install.sh | sh
sudo systemctl enable --now execonnect

On macOS, or without systemd, run execonnect serve instead.

3. Enroll by pasting the command from step 1:

execonnect enroll ect_…

The connection shows as Online on the Integrations page.

4. Publish an endpoint:

execonnect endpoint add --tls-server-name api.internal api https://10.0.0.15:8443

5. Use it from a VM. Click Add HTTP proxy next to the endpoint on the Integrations page, or run:

exe.dev ▶ integrations add http-proxy --name=internal-api --external-connection=office --endpoint=api --no-auth --attach=vm:my-vm
exe.dev ▶ ssh my-vm curl https://internal-api.int.exe.xyz/health

All other HTTP Proxy options work as usual; --external-connection and --endpoint take the place of --target.

Endpoints

execonnect endpoint add    [--tls-server-name NAME] NAME URL
execonnect endpoint update [--tls-server-name NAME] NAME URL
execonnect endpoint remove NAME
execonnect endpoint list
  • NAME is a lowercase DNS label and can't be renamed.
  • URL is http:// or https:// with no path. It's resolved on the execonnect machine.
  • --tls-server-name sets the name used to verify TLS. It defaults to the URL host; set it when the URL is an IP address.

Status and troubleshooting

execonnect status shows enrollment, tunnel, and endpoint state. Logs are in journalctl -u execonnect.

Status Meaning
Awaiting enrollment execonnect enroll hasn't run yet.
Online Connected.
Degraded Partly connected; reconnecting.
Offline execonnect isn't running or can't reach exe.dev.
  • invalid enrollment token: the token was already used or the connection was deleted. Create a new connection.
  • Online, but requests fail: check that the service is reachable from the execonnect machine itself, e.g. with curl.

Managing the service

The installer adds an execonnect user and group, the binary at /usr/local/bin/execonnect, and a systemd unit. State is kept in /var/lib/execonnect. To let another user run execonnect commands, add them to the execonnect group. Anyone in it can change what's published.

To delete a connection and the integrations it backs, use the Integrations page or run integrations setup execonnect -d --name=office.

To upgrade, rerun the install script. To uninstall:

sudo systemctl disable --now execonnect
sudo rm /etc/systemd/system/execonnect.service /usr/local/bin/execonnect
sudo rm -r /var/lib/execonnect   # forgets enrollment and endpoints

Releases are on GitHub; the source is in execonnect/.