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

> Explore the PicList web server architecture and configuration on port 36677. Understand its two HTTP services, the static file WebServer and REST API Server, for efficient image management. Learn how to set it up.

- Repository: [Kuingsmile/piclist](https://github.com/kuingsmile/piclist)
- Tags: architecture
- Published: 2026-03-05

---

**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`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/webServer/index.ts) and [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/webServer/index.ts) |
| **API Server** | Handles REST endpoints for uploads, deletions, and health checks | **36677** (fallback) | [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts) |

Both services are launched from [`src/main/lifeCycle/index.ts`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/webServer/index.ts). The default port 36677 is hard-coded as a fallback when no user configuration exists:

```typescript
// 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:

```typescript
// 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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/index.ts):

```typescript
// 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:

```typescript
// 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`](https://github.com/kuingsmile/piclist/blob/main/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:

```bash
open http://127.0.0.1:36677/

```

### Uploading Images via the API

Send a POST request to the upload endpoint:

```bash
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`](https://github.com/kuingsmile/piclist/blob/main/routerManager.ts) to the upload handler, which processes the image through PicList's pipeline.

### Checking Server Health

Verify the API server is responding:

```bash
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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/main/lifeCycle/index.ts) and can be configured via the settings UI at [`src/renderer/pages/PicGoSetting.vue`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/src/main/server/webServer/index.ts) and [`src/main/server/index.ts`](https://github.com/kuingsmile/piclist/blob/main/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`](https://github.com/kuingsmile/piclist/blob/main/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.