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

> Locate the main server entry point for Paperclip at server/src/index.ts. This file bootstraps the environment, creates the Express app, and starts the listener.

- Repository: [Paperclip/paperclip](https://github.com/paperclipai/paperclip)
- Tags: internals
- Published: 2026-08-14

---

**The main server entry point for Paperclip is located at [`server/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts)

The file [`server/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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](https://github.com/paperclipai/paperclip/blob/master/server/src/index.ts).

## Inside the Server Creation Flow

The [`server/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/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:

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts) delegates app construction to a dedicated factory:

```typescript
const app = await createApp();

```

The `createApp` function (implemented in [`server/src/app.ts`](https://github.com/paperclipai/paperclip/blob/main/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:

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

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

```bash

# 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:

```typescript
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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts) requires familiarity with several supporting modules:

| File | Role |
|------|------|
| **[`server/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts)** | Main entry point – creates the HTTP server and starts listening |
| [`server/src/app.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/app.ts) | Constructs the Express app, registers routes and middleware |
| [`server/src/config.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/config.ts) | Loads and validates runtime configuration (host, ports, auth URLs) |
| [`server/src/startup-banner.ts`](https://github.com/paperclipai/paperclip/blob/main/server/src/startup-banner.ts) | Prints a friendly startup banner with the selected listen port |
| [`server/src/url-utils.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts) serving as the definitive startup script.

## Summary

- The **main server entry point** is [`server/src/index.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/app.ts), `createServer()` from `node:http`, and `server.listen()` for the final binding
- **Supporting infrastructure**: configuration ([`config.ts`](https://github.com/paperclipai/paperclip/blob/main/config.ts)), URL utilities ([`url-utils.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts) define the API routes directly?

No. Route definitions are delegated to **[`server/src/app.ts`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/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`](https://github.com/paperclipai/paperclip/blob/main/server/src/index.ts).