How PicList Web Server Works on Port 36677: Architecture and Configuration Guide

PicList runs two distinct HTTP services—the static file WebServer and the REST API Server—both defaulting to port 36677, with configuration managed in src/main/server/webServer/index.ts and src/main/server/index.ts respectively.

The PicList web server port 36677 serves as the default listening port for both the file browser interface and the upload API in the kuingsmile/piclist open-source image hosting tool. Understanding how this port is configured and utilized helps developers customize deployments and troubleshoot connection issues.

PicList Web Server Architecture Overview

When the PicList application starts, it initializes two separate HTTP services that can operate simultaneously on port 36677:

Service	Purpose	Default Port	Source File
WebServer	Serves static files and directory listings for the image browser UI	36677	src/main/server/webServer/index.ts
API Server	Handles REST endpoints for uploads, deletions, and health checks	36677 (fallback)	src/main/server/index.ts

Both services are launched from src/main/lifeCycle/index.ts during the application ready phase.

How the Static File WebServer Works on Port 36677

Configuration and Default Port Logic

The WebServer configuration is defined in src/main/server/webServer/index.ts. The default port 36677 is hard-coded as a fallback when no user configuration exists:

// src/main/server/webServer/index.ts
this.#config = {
  enableWebServer: allConfig.settings?.enableWebServer || false,
  webServerHost:   allConfig.settings?.webServerHost   || '0.0.0.0',
  webServerPort:   allConfig.settings?.webServerPort   || 36677,   // ← default
  webServerPath:   allConfig.settings?.webServerPath   || defaultPath,
};

The code contains special handling for port 36699: if configured to 36699, it silently falls back to 37777 to avoid conflicts.

File Serving Implementation

When enableWebServer is true, the WebServer creates an HTTP server that performs two primary functions:

1. Directory Listings: If the requested path maps to a directory under webServerPath, it generates HTML directory listings via generateDirectoryListingHtml
2. File Streaming: If the path maps to a file, it streams the content with appropriate MIME types via serveFile

Starting the WebServer

The WebServer starts during the application lifecycle:

// src/main/lifeCycle/index.ts (simplified)
async readyFunction() {
  // ... other initialization ...
  webServer.start();  // Starts on port 36677 (or configured port)
}

Once running, you can access the file browser at http://127.0.0.1:36677/.

How the API Server Uses Port 36677

API Endpoints and Routing

The API Server handles image hosting operations through endpoints defined in src/main/server/routerManager.ts:

• POST /upload - Receives image data (multipart or JSON) and processes uploads through PicList's pipeline
• POST /delete - Removes previously uploaded images from storage
• GET /heartbeat - Returns health status for monitoring

Port Configuration and Fallback Logic

The API Server also defaults to port 36677, defined in src/main/server/index.ts:

// src/main/server/index.ts
const DEFAULT_PORT = 36677;

getConfigWithDefaults() {
  let config = picgo.getConfig<IServerConfig>(configPaths.settings.server);
  if (!this.#isValidConfig(config)) {
    config = { port: DEFAULT_PORT, host: DEFAULT_HOST, enable: true };
    picgo.saveConfig({ [configPaths.settings.server]: config });
  }
  return config;
}

If port 36677 is occupied, the server implements retry logic: it attempts to contact an existing PicList instance via /heartbeat, and if none responds, it increments the port number and retries binding.

Startup Sequence

Like the WebServer, the API Server starts from the lifecycle manager:

// src/main/lifeCycle/index.ts
server.startup();  // API server on port 36677 (or configured)

Running Both Services on Port 36677

Both the WebServer and API Server can operate simultaneously on port 36677 because they bind to different network interfaces or run in separate processes:

• The WebServer binds to webServerHost (default 0.0.0.0)
• The API Server binds to the configured host, but only activates when enableWebServer is false, or can be configured to use a different port via the PicList settings UI (src/renderer/pages/PicGoSetting.vue)

In typical deployments, users enable only one service; the settings interface allows toggling "Enable Web Server" and editing the port value to avoid conflicts.

Practical Examples for Port 36677

Accessing the File Browser

Open your browser to the default WebServer address:

open http://127.0.0.1:36677/

Uploading Images via the API

Send a POST request to the upload endpoint:

curl -X POST "http://127.0.0.1:36677/upload?key=YOUR_SERVER_KEY" \
  -F "file=@/path/to/image.png"

The request routes through routerManager.ts to the upload handler, which processes the image through PicList's pipeline.

Checking Server Health

Verify the API server is responding:

curl http://127.0.0.1:36677/heartbeat

# → {"success":true,"result":"alive"}

Summary

• PicList operates two distinct HTTP services that both default to port 36677: the static file WebServer and the REST API Server.
• The WebServer (src/main/server/webServer/index.ts) serves the image browser UI with hard-coded default port 36677, falling back to 37777 if configured to 36699.
• The API Server (src/main/server/index.ts) handles uploads, deletions, and health checks, using port 36677 as its fallback default with automatic port incrementing on conflicts.
• Both services launch from src/main/lifeCycle/index.ts and can be configured via the settings UI at src/renderer/pages/PicGoSetting.vue.

Frequently Asked Questions

Can I change PicList web server port 36677 to a custom value?

Yes. While 36677 is the hard-coded default in both src/main/server/webServer/index.ts and src/main/server/index.ts, you can override it through the PicList settings interface. The WebServer reads from webServerPort in the config, and the API Server uses the settings.server.port value. If you set the WebServer port to 36699, it automatically falls back to 37777 to avoid conflicts.

What happens if port 36677 is already in use when PicList starts?

The API Server implements retry logic in src/main/server/index.ts. If it cannot bind to the configured port (default 36677), it attempts to contact an existing PicList instance via the /heartbeat endpoint. If no response is received, it increments the port number and retries binding until it finds an available port. The WebServer does not implement automatic port incrementing and will fail to start if its configured port is occupied.

How do I access the file browser on port 36677?

Once the WebServer is enabled in settings (enableWebServer: true), open your web browser and navigate to http://127.0.0.1:36677/ (or replace 127.0.0.1 with your configured webServerHost). The server generates HTML directory listings for folders and streams image files with appropriate MIME types, allowing you to browse your PicList storage directory without using the desktop application.

Is the PicList API server on port 36677 secure by default?

The API Server on port 36677 does not implement authentication by default for most endpoints, though you can configure a server key that must be passed as a query parameter (e.g., ?key=YOUR_SERVER_KEY) for upload operations. For production deployments, you should place PicList behind a reverse proxy (like Nginx) with HTTPS and access control, as the built-in server is designed for local network use rather than direct internet exposure.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}