# Configuration

Configuration comes from `.env` or process environment variables.

## `.env.example`

`.env.example` is the runtime template. Keep it in source control, but never commit the copied `.env` file.

The template intentionally contains only the core values. Add advanced settings from the table below only when you need to override the defaults.

NTerminal package installs launched through `nterminal` read the runtime env file from `~/.nterminal/.env`.

```bash
nterminal onboarding
```

Onboarding writes `.env` for you, including an absolute `NTERMINAL_STATE_PATH` so password/TOTP state is read from the same file when the service starts.

## Settings

| Setting | Default | Purpose |
| --- | --- | --- |
| `NTERMINAL_ROLE` | required | `main` or `secondary`. Onboarding writes it; runtime startup fails if it is missing. |
| `NTERMINAL_HOST` | `127.0.0.1` | Bind host. Keep the main server local unless a separate access boundary is in front. |
| `NTERMINAL_PORT` | `3107` | HTTP server port. |
| `NTERMINAL_WORKSPACE_ROOT` | home directory | Startup directory for new terminal tabs. |
| `NTERMINAL_SHELL` | `$SHELL`, then `/bin/bash` | Shell path for new PTYs. |
| `NTERMINAL_STATE_PATH` | `~/.nterminal/state.json` | Local state file for password and layout data. Onboarding writes an absolute path. |
| `NTERMINAL_SESSION_SECRET` | required | Server secret for password hashing and session cookies. |
| `NTERMINAL_SESSION_TTL_SECONDS` | `43200` | Session lifetime in seconds. |
| `NTERMINAL_COOKIE_SECURE` | `false` locally | Set `true` when serving through HTTPS. |
| `NTERMINAL_ALLOWED_ORIGINS` | local origins | Comma-separated browser origins allowed for mutating requests. |
| `NTERMINAL_TRUST_PROXY` | `false` | Trust `X-Forwarded-For` for session IP binding. Use only behind a reverse proxy you control. |
| `NTERMINAL_AGENT_TOKEN` | empty | Shared token used by the main server to reach a secondary server. Generated by secondary onboarding. |
| `NTERMINAL_UPLOAD_MAX_FILES` | `1024` | Maximum files accepted in one drag-and-drop upload. |
| `NTERMINAL_UPLOAD_MAX_FILE_BYTES` | `536870912` | Maximum bytes accepted for one uploaded file. |
| `NTERMINAL_UPLOAD_MAX_BATCH_BYTES` | `2147483648` | Maximum total bytes accepted for one upload batch. |
| `NTERMINAL_FILE_LIST_MAX_ENTRIES` | `2000` | Maximum entries returned in one file explorer directory listing. |
| `NTERMINAL_FILE_TEXT_MAX_BYTES` | `1048576` | Maximum bytes loaded for text or Markdown view/edit. |
| `NTERMINAL_FILE_PREVIEW_MAX_BYTES` | `52428800` | Maximum bytes served for browser file previews. |
| `NTERMINAL_PID_PATH` | `~/.nterminal/nterminal.pid` | PID file for the control script. |
| `NTERMINAL_MONITOR_PID_PATH` | `~/.nterminal/nterminal.monitor.pid` | PID file for the lightweight restart supervisor. |
| `NTERMINAL_LOG_PATH` | `~/.nterminal/nterminal.log` | Log file for the control script. |
| `NTERMINAL_HEALTH_TIMEOUT_SECONDS` | `15` | Startup health-check timeout for the control script. |
| `NTERMINAL_STOP_TIMEOUT_SECONDS` | `20` | Graceful stop timeout for the control script. |

## Localhost Only

```env
NTERMINAL_HOST=127.0.0.1
NTERMINAL_PORT=3107
NTERMINAL_ALLOWED_ORIGINS=http://127.0.0.1:3107,http://localhost:3107
NTERMINAL_COOKIE_SECURE=false
```

## Private VPN

Run NTerminal on the private interface or behind a proxy reachable only over VPN. Keep `NTERMINAL_ALLOWED_ORIGINS` aligned with the exact browser URL.

```text
iPad or laptop
  -> private VPN address
  -> NTerminal or reverse proxy
  -> host shell PTY
```

## HTTPS Reverse Proxy

Terminate HTTPS in a reverse proxy and forward to NTerminal on localhost:

```text
Browser
  -> https://terminal.example.internal
  -> reverse proxy with access control
  -> http://127.0.0.1:3107
```

Use:

```env
NTERMINAL_HOST=127.0.0.1
NTERMINAL_PORT=3107
NTERMINAL_COOKIE_SECURE=true
NTERMINAL_ALLOWED_ORIGINS=https://terminal.example.internal
NTERMINAL_TRUST_PROXY=true
```

Only set `NTERMINAL_TRUST_PROXY` when the proxy is controlled by you and NTerminal is not directly reachable by clients that can spoof `X-Forwarded-For`.
