Portless runs your development environment with
stable URLs and a single place to see what your services are doing. Start with
portless up from a checkout. Portless discovers your application, starts its
services and dependencies, and opens a browser dashboard.
An application can span one repository or several. Each environment can mix services running from local code, managed containers, remote HTTP endpoints, and mocks. No account is required.
- Keep the same URLs as services restart or switch providers.
- See requests across services, alongside logs, database queries, and cache commands.
- Reproduce problems with traffic recordings and HTTP request replay.
- Test failure cases with scoped delays, errors, and mock responses.
Portless is in active development and does not yet have a stable public release. See current support and limitations.
Install the latest alpha release from the project tap:
brew install runportless/tap/portlessUse the full runportless/tap/portless name to select this project's formula.
You can also build from source.
Portless targets macOS and systemd-based Linux on AMD64 and ARM64. Linux setup
requires systemd-resolved.
Build from source with Go 1.26 or newer, Node.js 22.12 or newer, npm, and Make:
git clone https://github.com/runportless/portless.git
cd portless
make installThe executable is installed into GOBIN, or $(go env GOPATH)/bin when
GOBIN is unset. Ensure that directory is on your PATH.
After installing, configure local networking once per machine:
portless setupSetup may request administrator approval to configure the local HTTP and DNS relay that provides clean service addresses. Your application services run under your user account.
Docker Engine or Podman is needed only when your environment uses managed container resources.
Install your application's dependencies as you normally would, then run Portless from its checkout:
cd /path/to/billing
portless upFor a checkout named billing, Portless creates the billing/local
environment, starts the discovered services, and opens its dashboard. Use the
dashboard to open a service, inspect its dependencies, or follow traffic.
Services get readable addresses that stay the same across restarts:
http://checkout.local.billing.localhost
http://orders.local.billing.localhost
orders-postgres.local.billing.portless.test:5432
A project is your application. An environment, such as billing/local,
is an instance of that application with its own choice of providers and runtime
state. Portless manages the ports and dependency connections for you.
Built-in discovery supports Spring Boot, NestJS, Express, Fastify, Next.js, Go HTTP/RPC services, and FastAPI. Managed resources include PostgreSQL, Valkey, MySQL, and NATS. Discovery reads your project files without executing code.
To try Portless with a ready-made application, start with the Chat or Store example.
Run your first application walks through starting Store, creating an order, and stopping and resuming the environment. The guides use screenshots from the running application to show each workflow.
- Debug checkout with VS Code: start debug mode in Portless, attach to the process, and inspect a live request.
- Investigate a failed request: follow a rejected checkout through its dependency trace.
- Mock a dependency: preview a response and test it through the real checkout page.
Browse all guides for service management, database and cache inspection, replay, faults, recordings, and multiple environments.
Run these from a checkout belonging to your project:
| Command | What it does |
|---|---|
portless up |
Start the environment and open its dashboard. |
portless status |
Show environment and service status. |
portless open [service] |
Open a service in the browser. |
portless url [service] |
Print a service's public address. |
portless ui |
Open the Portless dashboard. |
portless logs [service] --tail |
Follow logs for one service or the whole environment. |
portless down |
Stop the environment, preserving managed data volumes. |
Use --env billing/local to target a particular environment and --json
for structured output. portless --help and the
command reference cover all commands and options.
For debugging, use portless up --debug checkout. Running portless up from
a registered service directory also enables its discovered Node or JVM debugger.
Register related checkouts as sources of one project. For example, from your
checkout-service directory:
portless project create billing \
--source checkout=. \
--source orders=../orders-service \
--source payments=../payments-service
portless env select billing/local
portless upPortless discovers services across those sources and connects their dependencies. See projects and environments for adding sources and choosing checkouts.
Clone an environment to change how selected services run. For example, use a remote QA payment service while keeping the rest of the application local:
portless env clone qa-assisted --from local
portless --env billing/qa-assisted env bind payments \
--remote https://payments.qa.example.com \
--classification qa \
--write-policy read-only \
--health-path /health
portless --env billing/qa-assisted upThe clone's configuration is independent. When another environment is already
using the same Git checkout, Portless prepares a separate worktree automatically,
including current uncommitted files and installed dependencies. This requires
Git and an existing commit. Later edits stay in their respective checkouts;
portless --env billing/qa-assisted env checkout list shows the clone's paths.
Remote requests still appear in traffic inspection. A read-only binding
blocks mutating HTTP methods locally before they reach the remote service.
Open Traffic in the dashboard to follow requests across services, inspect HTTP headers and bodies, and view decoded PostgreSQL, Redis/Valkey, MySQL, and NATS operations. Select an HTTP exchange and choose Replay to edit a request, send it to a ready environment in the same project, and compare responses.
Use Recordings to retain a session for later inspection, or Faults to simulate latency and failures on a specific caller-to-service connection. For example, delay calls from checkout to payments for one minute:
portless fault add slow-payments checkout:payments --latency 500 --duration 1mWebSockets work through the same HTTP service addresses using ws://.
Traffic inspection captures the opening handshake; WebSocket messages are not
captured or replayed.
See the traffic reference and recording and fault commands for filters, capture options, and replay limits.
Use Mocks in the dashboard to define fixed HTTP responses. A partial mock
overrides matching requests while other requests reach the real service. For
example, make POST /payments return an error:
portless mock create payment-error --unmatched-requests forward
portless mock route set payment-error reject-payment \
--service payments --method POST --path /payments --status 503
portless mock enable payment-errorRun portless mock disable payment-error to restore normal behavior.
For a full replacement, create a scenario without --unmatched-requests forward;
unmatched requests then return 501. The dashboard's Preview lets you
check route matching without sending application traffic.
See mock commands for route matching, scenarios spanning several services, and importing recordings.
| Example | What you can try |
|---|---|
| Chat | Two Node.js services with live WebSockets. No database or container engine required. |
| Store | A single checkout with Node.js, Spring Boot, PostgreSQL, and Valkey. |
| Dispatch | An application across three repositories, with mixed frameworks, MySQL, NATS, mocks, and a remote provider. |
Each example includes setup instructions and a walkthrough.
Connect an MCP-compatible assistant through Settings → MCP in the
dashboard (portless ui). Choose the scope and permissions, then copy the
generated client configuration.
Inspection is enabled by default. Starting services, changing configuration, accessing sensitive traffic, and replaying requests require explicit capability selection. See the MCP guide for configuration examples and permissions.
Portless stores its state in ~/.portless by default. Discovery only reads
files inside the supplied checkout; starting services runs your application
code with your user permissions.
Traffic capture stays local. Common credential headers are redacted, but application payloads can still contain sensitive data. Recording payloads is opt-in; review recordings before sharing them.
Daemon upgrades retain a working build while the replacement starts. If startup
fails, Portless restores the previous daemon and its state while application
processes keep running. portless daemon status shows the outcome. Automatic
retry of the failed build pauses until you install a different build or explicitly
run portless daemon restart. Connections may briefly disconnect during recovery.
portless down keeps your managed data volumes. For removing stored state or
Portless itself, review the preview-first
reset and uninstall commands.