Upstream repo: https://github.com/warp-tech/warpgate
Warpgate is a smart SSH, HTTPS, and database bastion host that works with any standard SSH client. Use it to securely proxy and record access to your servers and services, with a modern web admin interface and per-user access control.
- Image and Container Runtime
- Volume and Data Layout
- Installation and First-Run Flow
- Configuration Management
- Network Access and Interfaces
- Actions (StartOS UI)
- Backups and Restore
- Health Checks
- Dependencies
- Limitations and Differences
- What Is Unchanged from Upstream
- Contributing
- Quick Reference for AI Consumers
| Property | Value |
|---|---|
| Image | ghcr.io/warp-tech/warpgate:0.23.4 |
| Architectures | x86_64, aarch64 |
| Command | warpgate --skip-securing-files run |
--skip-securing-files is required because Warpgate attempts to chmod 600 its config files on startup, which fails inside a StartOS container that lacks CAP_CHOWN.
| Volume | Mount Point | Purpose |
|---|---|---|
main |
/data |
SQLite database, SSH host keys, TLS certificates, generated config |
| Path | Written by | Purpose |
|---|---|---|
/data/warpgate.yaml |
main.ts |
Generated server config (ports, paths, TLS) |
/data/tls.certificate.pem |
main.ts |
StartOS CA-signed TLS cert (refreshed on start) |
/data/tls.key.pem |
main.ts |
Private key for TLS cert (refreshed on start) |
/data/db |
Warpgate | SQLite database (users, targets, roles) |
/data/ssh-keys/ |
Warpgate | SSH host keys (auto-generated on first install) |
/data/store.json |
SDK | Admin password (used by Get Admin Credentials) |
On install, StartOS automatically:
- Generates a random admin password and stores it in the package.
- Runs
warpgate unattended-setupto initialise the database, SSH host keys, and TLS certificates. - Creates the
adminuser with the generated password. - Shows a critical task: Retrieve your admin credentials — open the action to see your username and password.
No manual setup wizard is required. The service starts ready to use.
warpgate.yaml is generated by main.ts on every startup and written to the volume. It is not user-editable — all meaningful runtime configuration (targets, users, roles, policies) is managed through the Warpgate web UI and stored in the SQLite database.
The TLS certificate (tls.certificate.pem / tls.key.pem) is also regenerated on every startup using StartOS's internal CA, ensuring the cert stays valid and trusted by browsers without any manual certificate management.
Generated config excerpt:
database_url: sqlite:/data/db
http:
listen: '0.0.0.0:8888'
certificate: /data/tls.certificate.pem
key: /data/tls.key.pem
trust_x_forwarded_headers: true
ssh:
listen: '0.0.0.0:2222'
keys: /data/ssh-keys
host_key_verification: prompt| Interface | Port | Protocol | Purpose |
|---|---|---|---|
| Web UI | 8888 | HTTPS | Admin interface — manage targets and users |
| SSH Gateway | 2222 | TCP | SSH client connections through the bastion |
Warpgate serves HTTPS natively. The StartOS interface binding uses TCP passthrough so the browser connects directly to Warpgate's TLS endpoint (signed by StartOS's own CA).
Connecting via SSH:
ssh '<warpgate-username>:<target-name>@<warpgate-host>' -p 2222
Example: ssh 'admin:myserver@your-startos-node' -p 2222
You will be prompted for your Warpgate user's password (not the target server's password). Warpgate then uses the credentials you configured on the target to connect onwards.
| Action | Visibility | Purpose |
|---|---|---|
| Get Admin Credentials | Hidden | Shows the auto-generated admin username and password |
The action is surfaced automatically as a critical task on first install.
Included in backup:
mainvolume (SQLite database, SSH host keys, generated config)
Restore behavior: Volume is fully restored before the service starts. All users, targets, and roles are preserved. The TLS cert is regenerated from StartOS's CA on next startup — no manual cert management needed after restore.
| Check | Method | Messages |
|---|---|---|
| Web Interface | Port listening (8888) | Success: "The web interface is ready" / Error: "The web interface is not ready" |
None.
- TLS passthrough — Warpgate has no plain HTTP mode; it always requires TLS. This package uses TCP passthrough so Warpgate handles TLS directly, with a cert issued by StartOS's CA. The cert is refreshed on every startup.
- Recordings disabled — Session recording is disabled by default to reduce storage usage. Enable it via the Warpgate admin UI (recordings are stored in the backup volume).
- MySQL and Postgres proxies disabled — Disabled in the generated config. SSH and HTTPS proxying work out of the box. Kubernetes proxy is also disabled.
The Warpgate binary runs unmodified. All user data (targets, credentials, sessions) is managed entirely through Warpgate's own web UI and stored in its SQLite database.
See CONTRIBUTING.md for build instructions and development workflow.
package_id: warpgate
image: ghcr.io/warp-tech/warpgate:0.23.4
architectures: [x86_64, aarch64]
volumes:
main: /data
ports:
ui: 8888/https (TCP passthrough, StartOS CA-signed cert)
ssh: 2222/tcp
config_file: /data/warpgate.yaml (generated at startup, not user-editable)
tls_cert: /data/tls.certificate.pem (generated at startup from StartOS CA)
database: /data/db (SQLite)
admin_password: stored in /data/store.json, shown via Get Admin Credentials action
dependencies: none
first_run: fully automated via unattended-setup, no wizard required
ssh_format: ssh '<warpgate-user>:<target>@<host>' -p 2222