# Remote Access

Trit executes coding agents and interactive shells as its service user. Remote access therefore needs a stronger boundary than simply opening port `9420` on a firewall.

Keep Trit bound to loopback in every supported deployment. Put an authenticated transport in front of it, use an exact browser origin, and retain Trit's project-root and operating-system boundaries.

## Supported access models

| Access model | Trit mode | Status | Best for |
| --- | --- | --- | --- |
| Browser on the Trit host | `local` | Supported | A workstation used directly |
| SSH local port forwarding | `local` | Supported | Occasional private access without another service |
| Cloudflare Tunnel and Access | `cloudflare-access` | Supported | Stable browser access for one or more approved users |
| Tailscale Serve | Dedicated mode required | Planned | Tailnet-native private access |
| Direct public port or generic reverse proxy | None | Unsupported | Do not use |

Trit currently accepts only `local` and `cloudflare-access` authentication modes. Do not place Tailscale Serve, a VPN address, or an arbitrary reverse proxy in front of local mode and assume it is authenticated: local mode intentionally requires loopback host and browser origins. Tailscale support will require a dedicated identity-verification path in Trit.

## Local and SSH-forwarded access

The installer defaults to:

```bash
TRIT_AUTH_MODE=local
HOST=127.0.0.1
PORT=9420
```

Open `http://127.0.0.1:9420` on the Trit host. From another machine, create an SSH local forward:

```bash
ssh -N -L 9420:127.0.0.1:9420 user@trit-host
```

Then open `http://127.0.0.1:9420` on the client machine. The browser still uses a loopback origin, and SSH carries the connection to Trit's loopback listener.

## Cloudflare Access

Cloudflare Tunnel provides an outbound connection from the Trit host, while Cloudflare Access authenticates the browser. Trit independently verifies the signed Access JWT, its issuer, audience, expiry, and email claim. It also enforces the configured HTTPS browser origin.

Follow the [Cloudflare remote-access guide](remote-access/CLOUDFLARE.md) for the complete setup, verification, troubleshooting, and rollback procedure.

## Non-negotiable controls

- Keep `HOST=127.0.0.1`. Never bind Trit to `0.0.0.0` for remote access.
- Do not add router port forwarding, a public security-group rule, or a direct reverse-proxy route to port `9420`.
- Authenticate the public hostname before making the tunnel continuously available.
- Use a dedicated hostname and configure its exact HTTPS origin in Trit.
- Restrict both the access provider and Trit's email allowlist to the intended users.
- Keep `~/.config/trit/env` and `~/.config/trit/config.yaml` mode `0600`.
- Continue to use narrow project roots. Remote authentication does not broaden the directories Trit should access.
- Verify authenticated HTTP and WebSocket behavior after every access-layer change.

## Choosing an option

Use local mode when the browser runs on the Trit host. Use SSH forwarding when remote access is occasional or already governed by SSH. Use Cloudflare Tunnel and Access when Trit needs a stable browser hostname or access for multiple approved identities.

Do not select Tailscale for Trit until the application has a supported Tailscale authentication mode. When implemented, its guide should preserve the same loopback origin, exact-origin checks, explicit identity allowlist, and defense-in-depth verification used by the Cloudflare integration.

## Common verification

On the Trit host:

```bash
trit doctor
systemctl --user is-active trit.service
curl -fsS http://127.0.0.1:9420/health
ss -ltn | grep ':9420'
```

The listener must be loopback-only. From the client, verify that the expected identity reaches `/api/whoami`, agent output streams normally, and a terminal can connect and reconnect. Also verify that an unapproved identity is denied.

See the [security policy](https://trit.wtf/security/) and [threat model](https://trit.wtf/threat-model/) before exposing a Trit instance beyond one machine.