withvibe
Sign in
Reference

Local export

Some work happens better on your machine — heavier debugging, IDE integrations, plugging into local tools. Local export is withvibe's escape hatch: take any env you have access to and run it locally with one command.

The flow at a glance

  1. Open any env in the web app.
  2. Click Export in the env panel.
  3. Copy the suggested command: withvibe env <envId>.
  4. Paste it into your terminal. The CLI does the rest.

What the CLI does

  1. Authenticates you (one-time withvibe login, device-flow).
  2. Calls GET /envs/:envId/local-bundle on your withvibe API to fetch everything it needs:
    • Env metadata (id, title, description, workspace).
    • Repo list with URLs and base branches.
    • The compose file — either rendered from the env's template or a custom one.
    • Any template assets (with $${VAR} placeholders pre-resolved).
    • The list of system-port variable keys, so the CLI knows which ports to allocate locally.
  3. Clones each repo into ./envs/<title-slug>/<repo>/, checking out the env branch.
  4. Allocates free localhost ports for every system-portvariable. Allocation happens entirely on your machine — the server's port assignments aren't relevant locally.
  5. Forces PUBLIC_HOST=localhost in the rendered env, so service-url variables point at http://localhost:<port> regardless of how the server is configured.
  6. Writes the rendered docker-compose.yml + assets, then runs docker compose up -d.
  7. Opens the worktree in VS Code (or your configured editor).
No server-side mutation
Local export is read-only against the server. It never modifies the upstream env: no port re-allocation, no branch reset, no container restart. You can re-run the command any time to refresh the local copy.

What moves and what doesn't

The export bundle includes the things needed to reproduce the env shape locally:

  • ✅ Repo URLs + branches (cloned fresh on your disk)
  • ✅ The rendered docker-compose, with secrets resolved from the workspace vault
  • ✅ Template assets like .env files, fixtures, init scripts
  • ✅ The full list of variable keys so the CLI can re-render in port mode

It does not include:

  • ❌ Container disk state (Postgres data, uploaded files, caches) — fresh volumes
  • ❌ The Claude session — local exports run without a withvibe agent attached by default
  • ❌ The runner container — exports are about getting the stack running, not the AI

Routing

Local exports always run in port mode, regardless of how the server-side env was routed. Subdomain-mode envs are silently re-rendered for ports when exported, with PUBLIC_HOST=localhost. This matches the spirit of “run it on my laptop”: no DNS, no Traefik, no certs.

Authentication

withvibe login
# Browser opens; approve the device.
# Token is stored at ~/.withvibe/credentials

The CLI uses a short-lived bridge JWT minted by the web edge after validating a CLI device token. The bundle endpoint is auth-required and scoped to your workspace membership.

Coming back online

When you're done locally, you have the usual git options:

  • Push the env branch to the remote and have the server-side env pull from it.
  • Open a PR directly from your local branch — the env's server-side copy stays as a snapshot.
  • Cherry-pick commits back into the server-side env via the Git tab.
Why this exists
Local export turns withvibe into a coordination layer: envs live on the server (shared, reviewable, demo-able), and individual contributors can pull any env down to their machine without losing context. It's the same primitive, just running on different hardware.
PreviousCLINext FAQ