GitHub - Sessa93/remote-df: Run a remote Dwarf Fortress instance and connect to it using your browser! · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Sessa93
remote-df
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>8 Commits<br>8 Commits
.github/workflows
.github/workflows
docker
docker
scripts
scripts
.dockerignore
.dockerignore
.gitignore
.gitignore
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
remote-df — Dwarf Fortress in the Browser
Play the classic (ASCII/2D) Linux build of Dwarf Fortress<br>in a web browser. DF runs as a Docker container on a remote x86-64 Linux host at<br>full native speed and is streamed to your browser over noVNC.
Architecture
┌──────────────────┐ ┌─────────────────────────────────────────────┐<br>│ Browser │ │ Docker container remote-df:native │<br>│ noVNC ─┼── SSH tunnel ──▶│ websockify :6080 ─ Xvnc :5900 │<br>│ localhost:6080 │ (loopback) │ └─ Xvnc :99 ◀─ dwarfort (PRINT_MODE:2D) │<br>└──────────────────┘ │ saves → docker volume df_saves │<br>└─────────────────────────────────────────────┘">Your machine Remote x86-64 Linux host (ssh )<br>┌──────────────────┐ ┌─────────────────────────────────────────────┐<br>│ Browser │ │ Docker container remote-df:native │<br>│ noVNC ─┼── SSH tunnel ──▶│ websockify :6080 ─ Xvnc :5900 │<br>│ localhost:6080 │ (loopback) │ └─ Xvnc :99 ◀─ dwarfort (PRINT_MODE:2D) │<br>└──────────────────┘ │ saves → docker volume df_saves │<br>└─────────────────────────────────────────────┘
Nothing is exposed publicly: the container binds to 127.0.0.1, and you reach it<br>through an SSH tunnel.
Prerequisites
A remote x86-64 Linux host you can SSH into (e.g. a VPS or cloud instance)
Docker installed on that host
SSH client on your local machine
A modern web browser
Quickstart
# 2. Open an SSH tunnel and launch it in your browser<br>./scripts/connect.sh<br># → http://localhost:6080/vnc.html?autoconnect=1&resize=scale"># 1. Build the image on the remote and start the container (idempotent)<br>./scripts/deploy.sh ssh-host>
# 2. Open an SSH tunnel and launch it in your browser<br>./scripts/connect.sh ssh-host><br># → http://localhost:6080/vnc.html?autoconnect=1&resize=scale
deploy.sh downloads the DF tarball on the remote on first run (so it doesn't<br>upload ~80 MB), syncs the build files, builds the Docker image, and runs the<br>container. Re-run it anytime to redeploy.
Project Layout
Path<br>Purpose
docker/Dockerfile<br>Multi-stage amd64 image: custom SDL2 + DF + Xvnc + noVNC
docker/start.sh<br>Container entrypoint: boots display stack, runs DF with auto-restart
scripts/deploy.sh<br>Build + run on the remote host (run from your machine)
scripts/remote-run.sh<br>docker run with saves volume + restart policy (runs on the remote)
scripts/connect.sh<br>SSH tunnel + open browser (run from your machine)
df/g_src/<br>Open-source platform/render wrapper (from Bay 12)
df/prefs/init.txt<br>Runtime overrides: 2D software render, no sound, FPS caps
How It Works
dwarfort is a graphical SDL2 program, so the container gives it a headless<br>display: Xvnc (virtual X server + VNC, 1280×800) → DF renders into it using<br>PRINT_MODE:2D software rendering (no GPU needed) → websockify/noVNC serves<br>the VNC stream to the browser as a . Keyboard and mouse flow back the<br>same way. Sound is disabled.
DF is wrapped in a restart loop so quitting or crashing returns to the title<br>instead of killing the container.
Custom SDL2 Build
DF's bundled SDL2 reads mouse input via XInput2 raw events, which VNC-injected<br>input does not produce — the cursor would never register. The Dockerfile builds<br>SDL2 with SDL_X11_XINPUT=OFF so DF uses core X input instead, which VNC input<br>generates correctly.
Persistent Saves
Saves persist in the df_saves Docker volume (mounted at /opt/df/data/save),<br>so worlds and fortresses survive redeploys.
Configuration
Environment variables for customization:
Variable<br>Default<br>Description
GEOM<br>1280x800<br>Virtual display resolution
VNC_PORT<br>5900<br>VNC server port
WEB_PORT<br>6080<br>noVNC web...