Skip to main content
A dev instance is a full, isolated copy of a base environment that you spin up from the sw CLI to exercise a feature branch end-to-end. It builds every component from a committed ref (default: your current branch), gets its own isolated environment and public URLs, and stays alive only as long as the CLI keeps it alive — when you press Ctrl-C (or the CLI loses its connection) it’s reaped automatically. It’s the same idea as a PR preview, but on demand and bound to your terminal session rather than a pull request.

​
Spin one up

Run sw dev up from inside a repo checkout: 
cd ~/code/acme-api      # on branch feat/checkout-v2
sw dev up
# [sw] spinning up dev instance of "acme" @ feat/checkout-v2 …
# [sw] instance 3f9a1c20 (acme-dev-ben-feat-checkout)
# [sw] creating
# [sw] deploying
# [sw] healthy
#
# Services:
#   api/api    https://acme-api-3f9a1c20.apps.slipway.sh
#   api/web    https://acme-web-3f9a1c20.apps.slipway.sh
#
# Port-forwards:
#   localhost:3000 → api/web:3000
#   localhost:5432 → api/postgres:5432
#
# [sw] dev instance is live — heartbeating to keep it alive. Press Ctrl-C to tear down.
sw dev up:
  1. Detects the environment from your repo’s origin remote — it matches owner/name against each base environment’s components. Pass --env <slug> to choose explicitly; if more than one environment includes the repo you’ll be prompted to pick.
  2. Detects the ref from your current git branch. Override with --ref <branch|tag|sha>.
  3. Builds from the committed ref — exactly like every other slipway deploy, cloning from your provider. Uncommitted local changes are not uploaded; commit and re-run sw dev up to pick them up.
  4. Prints every service URL once the instance is healthy.
  5. Forwards every service to localhost automatically (see below) so you can reach them directly — including internal services like databases. Pass --no-forward to skip, or --forward to pick specific ones.
  6. Heartbeats every ~30s to keep the instance alive, until you press Ctrl-C — then it stops the forwards and tears the instance down on the way out.
The instance copies the base environment’s component shape, variables, and secrets. The component bound to your repo is re-pointed to your ref; sibling components stay on the base environment’s tracked refs.

​
Flags

FlagDefaultMeaning
--refcurrent git branchRef to build (branch, tag, or commit SHA)
--envauto-detect from repoBase environment slug to copy
--ttlserver default (5 min)Rolling heartbeat window, in seconds
--forward / -Levery serviceForward only these, e.g. --forward api:3000 --forward db:5433:5432. Repeatable. Format: <service-or-component/service>:<local>[:<remote>].
--no-forwardoffDon’t forward any ports (useful in scripts / CI)

​
Automatic port-forwarding

Once the instance is healthy, sw dev up forwards every service that declares a port to localhost and keeps the tunnels open for the life of the session — so localhost:5432 hits the instance’s database, localhost:3000 hits your web service, and so on. Internal services (no public URL) are forwarded too; that’s usually exactly what you want to connect to from your machine.
  • Local port defaults to the service’s own port. If that port is already in use on your machine, slipway picks the next free one and prints the real mapping — it never fails the bring-up over a port clash.
  • Tunnels close on Ctrl-C, right before teardown.
Override the default with flags — it’s never an interactive prompt, so sw dev up stays scriptable: 
sw dev up --no-forward                       # forward nothing (CI / scripts)
sw dev up --forward api:3000                 # only api → localhost:3000
sw dev up --forward web:8080 --forward db:5432   # pick a few
sw dev up --forward api/postgres:5433:5432   # disambiguate by component, remap the local port
Each --forward entry is <service>:<local>[:<remote>]. Use <component>/<service> when the same service name exists in more than one component. With no :<remote>, the service’s declared container port is used. Giving any --forward flags replaces the auto-forward-everything default with exactly your list. You can still open additional or ad-hoc forwards by hand against a running instance with sw port-forward.

​
Lifetime: heartbeat + TTL

Dev instances don’t live forever, and they don’t depend on a healthy network either:
  • While sw dev up runs, it sends a heartbeat every ~30s that pushes the instance’s expiry forward by the rolling TTL (5 minutes by default).
  • When you press Ctrl-C, the CLI tears the instance down immediately.
  • If the CLI crashes or loses connectivity, heartbeats stop, the TTL lapses, and the server reaps the instance within a few minutes — nothing is left running.
  • A hard maximum lifetime (8 hours) caps any instance regardless of heartbeats, so a forgotten sw dev up can’t keep one alive indefinitely.
This is the opposite of a PR preview, which lives until the PR closes. A dev instance is tied to your session.

​
List and tear down

sw dev ls                       # live dev instances across the org
sw dev ls --env acme            # limit to one environment

sw dev down 3f9a1c20            # tear one down by id (or slug, or short prefix)
sw dev ls shows the owner, ref, status, and time-to-expiry for each live instance: 
ID        ENV   REF                STATUS   OWNER  EXPIRES
3f9a1c20  acme  feat/checkout-v2   healthy  ben    4m

​
Tail logs

Stream a component’s container logs — the same stream as the dashboard log viewer: 
sw dev logs 3f9a1c20 api

​
Working against the instance

Services are already forwarded to localhost while sw dev up runs, so you can hit them directly. For an extra forward against an already-running instance, or to run commands inside a container, use sw port-forward and sw exec: 
sw port-forward 3f9a1c20 api/postgres 5432:5432   # an extra/ad-hoc forward
sw exec 3f9a1c20 api/api -- printenv               # one-shot command
sw exec 3f9a1c20 api/api                           # interactive shell

​
Where they show up

Live dev instances appear on the base environment’s detail page in the dashboard, in a Live dev instances rail alongside PR previews — showing the owner, ref, last heartbeat, and time-to-expiry, with a Tear down button. They’re scoped to the environment, so anyone with access can see what’s currently running.

​
Permissions

Starting, heartbeating, and tearing down a dev instance requires the developer role on the org. Listing them requires viewer.