Compute Workspace
Tunnel
Expose a local port through a self-hosted frp so an instance or sandbox becomes reachable over a deterministic HTTPS URL.
Overview
A tunnel runs frpc against Stimulir's own self-hosted frps server — one per environment, no third-party provider. Starting a tunnel is always a CLI action; the URL is deterministic: https://<label>.<domain>. This mirrors the shape of prime tunnel start.
frps has no server-side “create a tunnel” API. A tunnel exists only while an frpc client holds the connection open, so it lives on the machine that ran stimulir tunnel start.
Configure
Point the CLI at your environment’s frps once. The settings persist so start doesn’t need them on every run.
| Parameter | Type | Description |
|---|---|---|
--control-hostrequired | string | frps control host for this environment. |
--control-port | integer | frps control port. Defaults to 7000. |
--domainrequired | string | Tunnel wildcard domain, e.g. tunnel.stimulir.com. |
--tokenrequired | string | frps auth token for this environment. |
stimulir tunnel configure \
--control-host tunnel-control.stimulir.com \
--control-port 7000 \
--domain tunnel.stimulir.com \
--token $FRP_TOKENEach value can also come from an environment variable instead of configure: STIMULIR_TUNNEL_CONTROL_HOST, STIMULIR_TUNNEL_CONTROL_PORT, STIMULIR_TUNNEL_DOMAIN, and STIMULIR_TUNNEL_TOKEN. The env var wins over the persisted setting.
Start
Expose a local port. The --label becomes both the subdomain and the name that stop and list use to find the tunnel again. Requires the frpc binary on PATH and configure already run for this environment.
| Parameter | Type | Description |
|---|---|---|
--port, -prequired | integer | Local port to expose. |
--label, -lrequired | string | Name for this tunnel, also used as the subdomain. |
stimulir tunnel start --port 8080 --label demo
# Tunnel demo live: https://demo.tunnel.stimulir.com -> localhost:8080The command writes a generated frpc config, spawns a background frpc process, and waits for the proxy to register before reporting the URL. It tracks the tunnel (pid, url, port) under ~/.stimulir/tunnels/ so it can be found again later.
List
Show tracked tunnels, running or stale, with their label, port, URL, status, and start time.
stimulir tunnel listStop
Stop a running tunnel by label. This terminates the owned frpc process and removes its tracked state and generated config.
stimulir tunnel stop demoDesktop vs web in the console
The Compute workspace surfaces tunnels through two different data paths. The difference is about who owns the frpc process.
| Desktop | Web | |
|---|---|---|
| Data source | Reads local ~/.stimulir/tunnels/*.json via Electron IPC | Backend proxies the environment’s frps admin API |
| Local port shown | Yes | No, the browser can’t see the local port |
| Stop button | Yes, it owns the frpc process | No, stop from the machine running frpc |
The web view is read-only. The frps admin API can only clear offline proxies, not kick a live one, so stopping a tunnel always requires the CLI or desktop app that holds the frpc connection.
Web tunnel status API
/api/v1/tunnelsRead-only. Lists live tunnels for the web build by proxying the environment’s frps admin API, so a browser with no local state can still see what is running. Returns available: false (not an error) when no frps admin API is configured for the environment.
There is no start or stop endpoint. Tunnel lifecycle stays entirely on the CLI and desktop app.