Getting Started

Portico starts the services your app is made of and puts one port in front of them. The browser only talks to that port, and Portico routes each path to the right service.

At a Glance

• Linux, on amd64 or arm64.
• Docker or Podman, only for image and compose services.

Install Portico

binary

mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/portico \
  https://github.com/kloudkit/portico/releases/latest/download/portico-amd64
chmod +x ~/.local/bin/portico

go

go install github.com/kloudkit/portico@latest

On arm64, download portico-arm64 instead.

Write a Config

Run portico init in your project. It looks for a compose file and for package.json dev scripts, and offers to add each one:

portico init

The result is a portico.yaml you can edit:

# yaml-language-server: $schema=https://raw.githubusercontent.com/kloudkit/portico/main/portico.schema.json

services:
  web:
    run: npm run dev -- --port {port} --strictPort
    route: /
  api:
    run: npm run dev
    dir: api

Check what it resolves to before starting anything:

portico routes

Start Everything

portico up

Portico starts every service, prints the route table and listens on http://localhost:4400. Output from all services lands in one stream, each line prefixed with its service. Press Ctrl-C to stop everything.

💡 TIP

Behind a gateway (Cloud Workstations, Codespaces, a remote dev box), open the forwarded URL for port 4400. Portico logs the public URL once the first request comes through it.

Without a Config File

Flags cover the simple cases:

portico up --run 'web=npm run dev -- --port {port}' --route /=web --route /api=3200

--run starts a command as a service, and --route mounts a path on a service or a port.

Next Steps

• Configuration: every kind of service, and what portico init detects.
• Routing: how paths reach your services.
• Running Services: output, the dashboard and controlling a running Portico.