Where to Find the Main Server Entry Point in the Paperclip Repository

The main server entry point for Paperclip is located at server/src/index.ts, which bootstraps the environment, creates the Express application, instantiates the native Node HTTP server, and starts the listener.

If you're exploring the Paperclip codebase to understand how its backend API starts up, you'll need to locate the definitive entry point. According to the paperclip.ai/paperclip source code, the entire server lifecycle is orchestrated from a single TypeScript module that handles everything from OpenTelemetry initialization to the final server.listen() call.

Locating the Entry Point: server/src/index.ts

The file server/src/index.ts serves as the main server entry point for Paperclip. This module is responsible for four critical startup phases:

1. Bootstrapping the environment – loading OpenTelemetry instrumentation, database connections, and runtime services
2. Creating the Express application – via the createApp function exported from server/src/app.ts
3. Instantiating a native Node HTTP server – using createServer(app) from the node:http module
4. Starting the listener – binding to the configured port and emitting the ready signal for systemd integration

You can view this file directly on GitHub at server/src/index.ts.

Inside the Server Creation Flow

The server/src/index.ts file follows a precise sequence to bring the API online. Here's how the key components work together.

Imports and Initial Setup

The entry point begins by importing core dependencies including database utilities, service containers, and platform helpers:

import { createServer } from "node:http";
// ... additional imports for DB, services, config

These imports establish the foundation for the async bootstrap sequence that follows.

Express Application Construction

Rather than defining routes directly, server/src/index.ts delegates app construction to a dedicated factory:

const app = await createApp();

The createApp function (implemented in server/src/app.ts) handles middleware registration, route mounting, and service injection. This separation keeps the entry point focused on server-level concerns.

HTTP Server Instantiation

Once the Express app is ready, the entry point wraps it in a native Node HTTP server:

const server = createServer(app as unknown as Parameters<typeof createServer>[0]);

This type assertion ensures compatibility between Express's request handler signature and Node's createServer expectations.

Port Detection and Binding

Paperclip includes sophisticated port handling logic. The entry point calls detectPort to discover an available TCP port, then rewrites internal URLs accordingly using rewriteLoopbackUrlPort. Finally, it binds and signals readiness:

server.listen(listenPort, config.host, () => {
  logger.info(`Server listening on ${config.host}:${listenPort}`);
  // systemd notification emitted here
});

This last block—typically around lines 1442-1445—is where the server transitions from "starting" to "ready."

Running the Paperclip Server

Development Mode

To start the server locally during development:

# Install dependencies first

pnpm install

# Start the dev server – it will invoke server/src/index.ts under the hood

pnpm dev

The pnpm dev command handles TypeScript compilation and process management, ultimately executing the entry point.

Programmatic Usage

You can also embed Paperclip's server logic in your own Node applications:

import { createApp } from "./server/src/app.js";
import { createServer } from "node:http";

async function launch() {
  const app = await createApp();               // loads config, DB, services
  const httpServer = createServer(app);
  const port = 3100;
  httpServer.listen(port, "127.0.0.1", () => {
    console.log(`Paperclip API listening on http://127.0.0.1:${port}`);
  });
}
launch();

This pattern is useful for custom deployments or integration testing scenarios.

Key Files in the Startup Sequence

Understanding server/src/index.ts requires familiarity with several supporting modules:

File	Role
server/src/index.ts	Main entry point – creates the HTTP server and starts listening
server/src/app.ts	Constructs the Express app, registers routes and middleware
server/src/config.ts	Loads and validates runtime configuration (host, ports, auth URLs)
server/src/startup-banner.ts	Prints a friendly startup banner with the selected listen port
server/src/url-utils.ts	Helpers for URL rewriting during bootstrap (e.g., loopback handling)
server/src/services/**	Individual business-logic services (issues, runs, tools) wired into the app

These files collectively form the backbone of Paperclip's server process, with server/src/index.ts serving as the definitive startup script.

Summary

• The main server entry point is server/src/index.ts in the Paperclip repository
• This file orchestrates the complete startup sequence: environment bootstrap, Express app creation, HTTP server instantiation, and port binding
• Key functions: createApp() from server/src/app.ts, createServer() from node:http, and server.listen() for the final binding
• Supporting infrastructure: configuration (config.ts), URL utilities (url-utils.ts), and service modules are all coordinated through this entry point

Frequently Asked Questions

What is the exact file path for Paperclip's server entry point?

The exact path is server/src/index.ts from the repository root. This file is the definitive starting point for the backend API process, as implemented in paperclipai/paperclip.

Does server/src/index.ts define the API routes directly?

No. Route definitions are delegated to server/src/app.ts via the createApp() function. The entry point focuses on server-level concerns: creating the HTTP server, managing the listen port, and signaling process readiness.

How does Paperclip handle port conflicts during startup?

The entry point uses detectPort to automatically discover an available TCP port, then calls rewriteLoopbackUrlPort to update internal URLs accordingly. This allows Paperclip to start gracefully even when the default port is occupied.

Can I customize the host and port without modifying source code?

Yes. The entry point loads configuration from server/src/config.ts, which typically sources values from environment variables. Set your preferred host and port values through the configuration system rather than hardcoding them in server/src/index.ts.

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