Skip to main content

​
Overview

Markdown-OS runs a local web server to provide the editor interface. You can customize the host interface and port number using command-line options.

​
Basic Usage

1

Default Configuration

By default, Markdown-OS binds to 127.0.0.1 (localhost) on port 8000:
uv run markdown-os open ./notes.md
# Opens at http://127.0.0.1:8000
2

Custom Port

Specify a different port with the --port option:
uv run markdown-os open ./docs/ --port 9000
# Opens at http://127.0.0.1:9000
3

Custom Host

Change the host interface with the --host option:
uv run markdown-os open ./notes.md --host 0.0.0.0 --port 8000
# Opens at http://0.0.0.0:8000

​
Host Options

​
Localhost (Default)

uv run markdown-os open <path> --host 127.0.0.1
Binds to the loopback interface, making the server accessible only from your local machine. This is the recommended and secure default for local development.

​
Network Binding

uv run markdown-os open <path> --host 0.0.0.0
Binds to all network interfaces, making the server accessible from other devices on your network.
Binding to 0.0.0.0 or any non-loopback address exposes your files to the network without authentication. Only use this in trusted networks or when you specifically need remote access (e.g., cloud VMs, development servers).
When you use a non-loopback address, Markdown-OS displays a security warning: 
WARNING: Binding to non-loopback address exposes your files 
to the network without authentication.

​
Port Configuration

​
Auto-Increment Behavior

The --port option specifies the preferred starting port. If that port is already in use, Markdown-OS automatically increments to find the next available port. 
uv run markdown-os open ./notes.md --port 8000
Port Selection Logic:
  1. Tests if port 8000 is available
  2. If occupied, tries 8001, 8002, 8003…
  3. Continues up to port 65535
  4. Displays the actual port in the console output
Always check the console output to see which port was actually selected:
Opening file /home/user/notes.md at http://127.0.0.1:8001

​
Valid Port Range

Ports must be between 1 and 65535. Using an invalid port number will result in an error: 
uv run markdown-os open ./notes.md --port 70000
# Error: Start port must be between 1 and 65535.

​
Port Availability Check

Markdown-OS uses socket binding tests to determine port availability. The check:
  • Attempts to bind a TCP socket with SO_REUSEADDR option
  • Tests the specific host/port combination
  • Returns the first available port in the range

​
Cloud and Remote Development

​
Cloud VMs (Cursor Cloud, GitHub Codespaces, etc.)

When running Markdown-OS in a cloud VM or remote development environment, you need to bind to 0.0.0.0 to allow browser access: 
uv run markdown-os open <file-or-directory> --host 0.0.0.0 --port 8000
The CLI attempts to auto-open a browser. In cloud VMs, you may see harmless dbus errors in the logs. The server will still work correctly - just manually navigate to the URL shown in the console output.

​
Port Forwarding

If your cloud environment requires specific port forwarding rules, use the --port option to specify the forwarded port: 
# If your environment forwards external port 3000 to internal port 8080
uv run markdown-os open ./docs/ --host 0.0.0.0 --port 8080

​
Common Patterns

uv run markdown-os open ./notes.md
# Equivalent to:
# uv run markdown-os open ./notes.md --host 127.0.0.1 --port 8000
Use different ports for each instance:
# Terminal 1
uv run markdown-os open ./project-a/ --port 8000

# Terminal 2
uv run markdown-os open ./project-b/ --port 8001

# Terminal 3
uv run markdown-os open ./notes.md --port 8002
If you don’t specify different ports, auto-increment will handle it automatically, but explicit ports make it easier to remember which project is on which port.
# Bind to all interfaces on port 8000
uv run markdown-os open ~/workspace/ --host 0.0.0.0 --port 8000
To test that your server is accessible:
# On the server machine
uv run markdown-os open ./notes.md --host 0.0.0.0 --port 8000

# From another machine on the same network
# Open browser to: http://<server-ip>:8000

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us