---
title: "Run Nexus locally"
description: "Start the PostgreSQL, Admin API, Gateway, and Console development composition on loopback."
---

> Documentation Index
> Fetch the complete documentation index at: https://nexus.microvoid.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Nexus locally

## Goal

在本机启动 Nexus PostgreSQL、Admin API、Node Gateway 和 Console，并准备好执行与部署环境相同的 Workspace 接入流程。

## Outcome

Console 位于 `http://localhost:5173`，Admin API 位于 `http://localhost:3000`，内部 Node Gateway 位于 `http://localhost:4000`。开发时 Console 的 `/providers/*` 会代理到 Gateway，因此 Console 复制的用户 Base URL 可直接使用 `5173` Origin。

## Who this is for

需要本地开发、评审部署 Adapter 或在不修改产品契约的情况下复现黄金路径的自部署工程师。

## Prerequisites

- Node.js 22.12+ 和仓库声明的 pnpm 版本。
- Docker（推荐用于 PostgreSQL），或支持 PostgreSQL wire protocol 的 PGlite 本地模式。
- 未占用的 `3000`、`4000`、`5173` 和 PostgreSQL 端口。

> **Local values are not production secrets**
>
> `.env.example` 中的数据库密码、Better Auth Secret 和 Provider 加密 Key 只用于绑定到 loopback
> 的开发环境。不得在共享、预发布或生产环境复用。

## 1. Install and configure

在仓库根目录运行：

```sh title="Terminal"
pnpm install --frozen-lockfile
cp .env.example .env
```

## 2. Start PostgreSQL

使用 Docker 只启动本地 PostgreSQL：

```sh title="Terminal"
docker compose --env-file .env -f deploy/docker-compose/compose.yaml up -d postgres
pnpm db:migrate
```

没有 Docker 时，在一个终端启动持久化 PGlite wire server，再从另一个终端迁移：

```sh title="Terminal 1"
pnpm db:local
```

```sh title="Terminal 2"
DATABASE_URL=postgresql://postgres@127.0.0.1:5432/postgres pnpm db:migrate:local
```

## 3. Start Nexus

```sh title="Terminal"
pnpm dev
```

该命令启动仓库现有的开发 Composition。不要把 Vite Console Proxy 误认为生产拓扑；生产环境仍独立部署 Console 和 Gateway。

## 4. Check readiness

```sh title="Terminal"
curl --fail http://localhost:3000/health/ready
curl --fail http://localhost:4000/health/ready
curl --fail --head http://localhost:5173/
```

Admin Swagger 位于 `http://localhost:3000/admin/docs`。它只用于查看本地契约；公开 API Reference 仍由仓库接受的 OpenAPI 文件生成。

## 5. Complete the golden path

打开 Console，按 [Add Nexus to my product](/docs/quickstarts/add-nexus-to-product) 创建 Workspace、ProviderConnection、Plan 和用户。只输入你授权用于本地测试的 Provider 凭证，并使用该 Provider 接受的原始模型名。

## Check your work

- Admin 和 Gateway readiness 返回成功，Console 根页面可访问。
- PostgreSQL 中已应用仓库迁移，而不是由应用进程临时创建表。
- Gateway Base URL 使用不可变 `providerConnectionId` UUID。
- 一次测试请求能在 Console 的 Usage 和 Activity 中按应用用户归因。

## What Nexus stored

本地 PostgreSQL 保存 Access、Quota Reservation、Usage 与管理事实；Provider Secret 使用 `.env` 指定的本地加密 Driver 保存。停止进程不会把这些事实改成内存真值。

## What the user received

通过本地 Console Provision 的用户仍只接收 Inference Key 和 Gateway Base URL，不接收 Provider 或 Management 凭证。

## Troubleshooting

- PostgreSQL 未就绪：检查 Compose health、端口占用和 `.env` 的 `DATABASE_URL`。
- Admin 可用但 Gateway 不可用：检查 `NEXUS_GATEWAY_PORT` 和 Gateway 日志，不能绕过 PostgreSQL/Quota。
- `5173` 请求失败：确认 Vite 与 Gateway 都在运行；开发 Proxy 只转发 `/providers/*`。
- 迁移错误：不要手工修改数据库结构；回到仓库迁移和错误输出定位。

## Next steps

完成本地黄金路径后，使用 [Use my Nexus access](/docs/quickstarts/use-my-nexus-access) 验证独立应用用户视角。按 `Ctrl-C` 停止开发进程；Docker PostgreSQL 可用以下命令停止：

```sh title="Terminal"
docker compose --env-file .env -f deploy/docker-compose/compose.yaml down
```

Source: https://nexus.microvoid.io/docs/quickstarts/run-nexus-locally/index.mdx