Remote access
Reach your self-hosted Qoc desk from any device using a secure tunnel authenticated by your auth token — without exposing the local API directly.
Qoc's remote access model keeps your desk local-first: a lightweight tunnel forwards authenticated requests from any device to your local API, with TLS in transit and a bearer token as the only credential.
How the tunnel works
The Qoc runtime optionally starts a tunnel client that establishes an outbound TLS connection to a relay. The relay assigns a stable subdomain URL. Requests arriving at that URL must carry your auth token as a bearer header — the relay forwards them to the container, which validates the token before processing.
No inbound ports need to be opened on your firewall or router. The tunnel connection is outbound-only from the container's perspective.
If the tunnel client loses connection, it reconnects automatically with exponential back-off. During the reconnect window, the local API on 127.0.0.1:7070 continues to serve CLI requests on the host.
Enabling the tunnel in desk.toml
[tunnel]
enabled = true
# subdomain is optional; omit to get an auto-generated one
subdomain = "my-desk"
# relay is the tunnel relay endpoint — defaults to the Qoc relay
relay = "tunnel.qoc.app:443"Authenticating a remote CLI session
export QOC_API_URL=https://my-desk.tunnel.qoc.app
export QOC_AUTH_TOKEN=$(cat /path/to/auth_token.txt)
qoc status # reads UTA book over the tunnel
qoc run approve # approves a pending order remotelySecurity properties
| Property | Detail |
|---|---|
| Transport | TLS 1.3 end-to-end from remote client to tunnel relay |
| Authentication | 256-bit bearer token; no username/password |
| Token storage | Token lives only in your secret store and the container — never in desk.toml |
| Local fallback | Local API on 127.0.0.1:7070 works independently of tunnel state |
| Tunnel relay | Relay is a dumb forwarder; it sees ciphertext headers only |
Rotating the auth token
To rotate the token, generate a new one with qoc init --rotate-token and restart the container. All remote sessions using the old token will immediately stop working. Update the token in any remote environment variable store where you have it saved.
Treat the auth token like a private key
Anyone who holds your auth token can submit and approve orders on your desk. Store it in a secret manager, not in plain-text files or shell history. The token grants full access — there are no read-only or limited-scope tokens in V0.73.0.
Self-host the tunnel relay
Advanced operators can run their own tunnel relay by pointing the relay field at a self-hosted instance. The relay protocol is open and documented in the Qoc GitHub repository.