Local previews
for full-stack apps.

Start your frontend, API, and databases on your machine. Previewhost assigns local URLs, starts services in dependency order, and separates each environment’s ports and managed data. Use the CLI, or connect your coding agent over MCP.

npm install -g previewhost

Choose your interface

Open sourceRuns on your machine

inventory

Ready

main

Project folder: ~/code/inventory
Hostname: inventory--frontend.localhost:49837
Localhost: 127.0.0.1:49837

Services · Serving

Service	Runtime	Status	Connection
frontend	Next.js	Ready	`inventory--frontend.localhost:49837`
api	FastAPI	Ready	`inventory--api.localhost:49837`
database	PostgreSQL	Ready	`Managed · this environment`
cache	Redis	Ready	`Managed · this environment`

Setup jobs

migrateSucceeded

Interactive demo · simulated data

Start services in dependency order.

One preview.yaml connects your frontend, API, setup jobs, and databases. Previewhost starts each service after its dependencies are ready.

preview.yamlAPI excerpt

api:
  type: command
  cwd: ./api
  command: [python, -m, uvicorn, app:app,
    --host, 127.0.0.1, --port, "{port}"]
  readyPath: /health
  dependsOn: [migrate]
  env:
    DATABASE_URL: {service: database}
    REDIS_URL: {service: cache}

The API starts after its migration and databases are ready.

Services and setup jobs

Startup order

Run worktrees side by side

Run environments for different worktrees, each with separate ports, local URLs, and managed database data.

Worktree isolation

Connect different repositories

Point the frontend and APIs at their existing source directories. Combine them in one environment, even when their branch names differ.

Multi-repository example

Inspect service logs in one place

Read frontend, API, and setup-job output in one view. Filter by source or attempt, then refresh for new output.

Service and job logs

Logs capture command and job output. Database container logs are not collected. Browser-console messages appear only when your framework forwards them to a captured process.

Configuration and private setup

Use named connections.
Keep secrets out of config.

Bind environment variables to services, selected host inputs, or stored secret references.

1
Your agent declares the secret references and services that need them.
2
You approve access and enter missing values in a private form, outside your agent chat.
3
Services receive approved values at startup. Stored-secret bindings stay as references in saved configuration.

Private setup and secret access

Application code can still expose values. Log redaction is best effort.

preview.yamlAPI service excerpt

api:
  type: command
  cwd: ./api
  command: [python, -m, uvicorn, app:app,
    --host, 127.0.0.1, --port, "{port}"]
  env:
    DATABASE_URL: {service: database}
    REDIS_URL: {service: cache}
    API_TOKEN: {secret: "inventory/dev/api-token"}
    REGION: {fromEnv: REGION}

service: A connection URL, plus a readiness dependency.
secret: A stored reference, shared wherever that exact name is approved.
fromEnv: A host variable selected with --env at startup.

For browser requests, {browserUrl: api} supplies an HTTP alias without a startup dependency.

Describe the app you have.

Save preview.yaml, pass JSON to the CLI, or let your agent supply a configuration. You choose the commands and readiness checks.

Configuration guide

Static files: Prepared HTML, assets, and build output.
HTTP applications: Your installed development server or application command.
Existing local servers: Connect by HTTP URL. The existing server’s process, port, and data stay under its original owner.
Services and setup jobs: HTTP services, managed or existing local PostgreSQL and Redis, and setup jobs that run to completion.

Install your app’s dependencies before startup. Managed databases require local Docker and downloaded images. Non-HTTP background workers are not supported.

CLI and coding agents

Choose your interface.

Node.js 22.23 or later.
macOS, Linux, and Windows.
Installation requirements

01Install Previewhost

npm install -g previewhost

Run it from your terminal, or connect your coding agent through MCP.

Start from your project directory.

Install your app’s dependencies and create preview.yaml with its start commands and connections.

For managed databases or stored secrets, first complete private setup:

previewhost secrets setup --allow-exec

Follow the CLI quickstart

Inspect the configuration, then start:

previewhost inspect
previewhost start --allow-exec

Open the returned URL. In another terminal, inspect your environments:

previewhost dashboard

Keep the dashboard terminal open while using it.

--allow-exec permits trusted commands with your user permissions. It does not sandbox code or approve secrets.

Local previews for full-stack apps.