# How to Configure Custom Port and Host in JSON Server: Complete Guide

> Learn how to configure custom port and host in JSON Server. Easily set your port and host using CLI flags, environment variables, or programmatic configuration. Master your mock API setup.

- Repository: [typicode/json-server](https://github.com/typicode/json-server)
- Tags: how-to-guide
- Published: 2026-03-01

---

**You can configure custom port and host in JSON Server using CLI flags (`--port` and `--host`), environment variables (`PORT` and `HOST`), or programmatic configuration when embedding the server.**

JSON Server provides flexible networking options to adapt to different development environments, from local testing to Docker containers. Whether you need to avoid port conflicts or expose your mock API to external devices, understanding the configuration hierarchy in `typicode/json-server` ensures reliable deployment.

## CLI Configuration Options

The command-line interface defined in [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) accepts explicit flags for network configuration. These options take precedence over all other configuration methods.

### Using Command-Line Flags

Pass `-p` (or `--port`) and `-h` (or `--host`) directly when starting the server:

```bash
json-server --port 4000 --host 0.0.0.0 db.json

```

According to the source code in [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) lines 25-28, the flag definitions specify:
- `-p, --port <port>` defaults to **3000**
- `-h, --host <host>` defaults to **localhost**

### Using Environment Variables

For containerized environments or CI pipelines, set `PORT` and `HOST` variables before invoking the command:

```bash
PORT=4000 HOST=0.0.0.0 json-server db.json

```

The CLI merges these values in [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) lines 48-52, checking for environment variables when flags are not provided.

## Configuration Precedence and Defaults

JSON Server resolves port and host settings through a specific hierarchy:

1. **CLI flags** (`--port`, `--host`) — Highest priority
2. **Environment variables** (`PORT`, `HOST`) — Fallback when CLI flags absent
3. **Hard-coded defaults** (`3000`, `localhost`) — Applied when no other values exist

When the server starts, [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) constructs the display URL using the resolved host and port values (lines 152-176). Setting host to `0.0.0.0` binds the server to all network interfaces, making the mock API accessible from external machines and mobile devices on the same network.

## Programmatic Configuration

When embedding JSON Server in a Node.js application rather than using the CLI, pass custom values directly to the `listen` method:

```javascript
import { createApp } from './src/app.ts';
import { Low, JSONFile } from 'lowdb';

const adapter = new JSONFile('db.json');
const db = new Low(adapter);
await db.read();

const app = createApp(db, {});

const PORT = 8080;
const HOST = '0.0.0.0';

app.listen(PORT, HOST, () => {
  console.log(`JSON Server running at http://${HOST}:${PORT}`);
});

```

This approach bypasses the CLI argument parsing in [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) and allows dynamic configuration based on runtime conditions or external configuration files.

## Summary

- **CLI flags** `--port` and `--host` provide the most explicit control over JSON Server networking configuration.
- **Environment variables** `PORT` and `HOST` offer flexibility for Docker containers and deployment pipelines.
- **Default values** of `3000` and `localhost` apply when no overrides are specified.
- **Programmatic usage** allows direct configuration when embedding the server in custom applications.

## Frequently Asked Questions

### What is the default port for JSON Server?

The default port is **3000**, defined in [`src/bin.ts`](https://github.com/typicode/json-server/blob/main/src/bin.ts) as the fallback value for the `--port` option. If port 3000 is already in use, the server will fail to start unless you specify an alternative via CLI flag or environment variable.

### How do I expose JSON Server to external networks?

Set the host to `0.0.0.0` using either `json-server --host 0.0.0.0` or the `HOST` environment variable. This binds the server to all available network interfaces, allowing other devices on your local network to access the mock API at your machine's IP address.

### Can I use environment variables with Docker?

Yes, environment variables are ideal for Docker deployments. Pass `-e PORT=4000 -e HOST=0.0.0.0` to your `docker run` command, or define them in a [`docker-compose.yml`](https://github.com/typicode/json-server/blob/main/docker-compose.yml) file. The JSON Server CLI automatically reads these variables when starting the container.

### How do I set port and host in package.json scripts?

Add the flags to your npm scripts for consistent development environments:

```json
{
  "scripts": {
    "api": "json-server --watch db.json --port 5000 --host 127.0.0.1",
    "api:public": "json-server --watch db.json --port 4000 --host 0.0.0.0"
  }
}

```

Run with `npm run api` or `npm run api:public` to start the server with your predefined network configuration.