Cloud development and remote development

There are two ways to keep working when you are away from the machine that runs your Agents. Pick the one you need:

What you want	What this path is called	Where the Agent runs	Who connects
One environment on a server that your work laptop, home computer, and phone all share	Cloud development: run the headless runtime, `vibex-server`	The server	Desktop and mobile connect as clients
Your phone or tablet reaching the computer on your desk	Remote development: desktop + mobile	Your own computer	Only the mobile devices you paired

What is a headless runtime? Think of it as Vibex without a window. It owns Agent sessions, workspaces, Git, terminals, and provider profiles, and behaves exactly like the desktop app — it just runs on a server, and you operate it through a desktop or mobile client. Its program name is vibex-server.

Both paths establish trust with a one-time pairing: the first time, you need the pairing code or QR code from the machine itself. After that, long-lived credentials live on both sides and clients reconnect on their own. The steps below assume the desktop app is already installed. The Android client can be sideloaded from GitHub Releases; iOS currently ships only a simulator build. See Install and platforms for both.

1. Cloud development: run Vibex on a server

Agents read and write code on the server and run commands there, so prepare the server first and connect clients afterwards.

Before you start

A Linux server with Docker. For a single user, 1 vCPU and 2 GB of RAM is enough to start; running several Agents benefits from 2 vCPU and 4 GB or more.
Your code must be reachable on the server: either clone it there, or mount a host directory into the container (the example below mounts one).
Agent accounts and API keys are configured later, from the desktop client: add them under Config Center (see Config Center). Never put them in the compose file or commit them.

Step 1: start the runtime

The project repository already contains a complete docker-compose.yml deployment file — open it directly: deploy/server/docker-compose.yml. The version below is a minimal example trimmed for this walkthrough; save it as docker-compose.yml in any directory on the server:

services:
  vibex-server:
    # Use a moving channel tag: rc follows the newest release candidate,
    # latest follows the newest stable release; pin a version only if you need to
    image: ghcr.io/vibex-ai/vibex-server:rc
    container_name: vibex-server
    # Restart the runtime after a reboot; the healthcheck below decides when it is up
    restart: unless-stopped
    # Share the host network namespace: the container's loopback is the host's loopback,
    # which avoids publishing ports on a bridge network with a non-loopback bind
    # (loopback mode refuses that bind by design)
    network_mode: host
    environment:
      # Runtime data directory: database, server identity, and Agent installs live here
      VIBEX_HOME: /data
      VIBEX_DB_PATH: /data/vibex.db
      # With 127.0.0.1 here, phones and other computers cannot connect
      VIBEX_BIND_ADDR: 0.0.0.0:8765
      # lan allows local-network access; a public deployment needs public plus HTTPS
      VIBEX_DEPLOYMENT_MODE: lan
      # The runtime signs its own certificate; clients receive the fingerprint
      # inside the pairing connection string, so no certificate authority is needed
      VIBEX_TLS_MODE: pinned_certificate
      # The address clients dial; the port must match VIBEX_BIND_ADDR
      VIBEX_PUBLIC_HOST: 192.168.1.10:8765
      # Directories a client may browse when picking a project (used in step 4)
      VIBEX_WORKSPACE_ROOTS: /data:/data/repos
    volumes:
      # The only volume you have to back up: database plus server identity
      - vibex-data:/data
      # Your code directory; after mounting it, list its path in VIBEX_WORKSPACE_ROOTS
      - /srv/repos:/data/repos        # change to the code directory Agents should open
volumes:
  vibex-data:

This example only uses the variables you cannot avoid; the full list, including rate limits, event capacity, and secret storage, is in the environment reference.

Use rc to follow the newest release candidate or latest for the newest stable release; pin a specific version only if you need to. If you already cloned the repository, you can also build from source with its deployment files: docker compose -f deploy/server/docker-compose.yml up --build -d vibex-server.

Start it and read the pairing material:

docker compose up -d
docker logs vibex-server | grep -E 'pairing_(code|link)'

The log prints two things:

pairing_code=123-456-789 — a one-time code that expires after five minutes by default.
pairing_link=vibex://pair#/code/... — a connection string that already carries the server address, the one-time code, and the server certificate (DER). Copy the whole string; the client pins that certificate before its first request, so a server with a self-signed certificate needs no system CA.

A pairing code or connection string is as sensitive as a password and works once. Do not post it in chat, an issue, or a screenshot. When it expires, mint a new one on the server.

docker exec vibex-server vibex-server pairing-code

If the server is on the public internet

A public deployment adds exactly one requirement: HTTPS. Let Caddy obtain the certificate while the runtime only listens on loopback:

services:
  vibex-server:
    image: ghcr.io/vibex-ai/vibex-server:latest
    container_name: vibex-server
    restart: unless-stopped
    network_mode: host
    environment:
      # Loopback only; public traffic goes through Caddy and 8765 stays closed
      VIBEX_BIND_ADDR: 127.0.0.1:8765
      # A public deployment refuses to start without trusted HTTPS
      VIBEX_DEPLOYMENT_MODE: public
      VIBEX_TLS_MODE: trusted_https_proxy
      # Let rate limits use the real client address; only true behind a TLS proxy
      VIBEX_TRUST_FORWARDED_HEADERS: "true"
      # The domain clients use, and the address printed in the pairing string
      VIBEX_PUBLIC_HOST: vibex.example.com
      # Accept only these hosts and origins; they must match the domain above
      VIBEX_ALLOWED_HOSTS: vibex.example.com
      VIBEX_ALLOWED_ORIGINS: https://vibex.example.com
      # Directories a client may browse when picking a project
      VIBEX_WORKSPACE_ROOTS: /data:/data/repos
    volumes:
      # The only volume you have to back up: database plus server identity
      - vibex-data:/data
      - /srv/repos:/data/repos

  # Reverse proxy: obtains and renews the certificate, forwards 443 to the runtime's loopback port
  caddy:
    image: caddy:2-alpine
    container_name: vibex-caddy
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy-data:/data
      - caddy-config:/config

volumes:
  vibex-data:
  caddy-data:
  caddy-config:

Add a Caddyfile next to it:

vibex.example.com {
    reverse_proxy 127.0.0.1:8765
}

docker compose up -d
docker logs vibex-server | grep -E 'pairing_(code|link)'

Your firewall only needs 80, 443, and SSH. Keep 8765 on loopback and out of the public internet. After you replace the domain and address with your own, VIBEX_ALLOWED_HOSTS and VIBEX_ALLOWED_ORIGINS must match the domain clients actually use, or requests are rejected.

If you would rather not expose anything to the public internet, install Tailscale on the server and publish the runtime with tailscale serve --bg http://127.0.0.1:8765. Set VIBEX_DEPLOYMENT_MODE to public, VIBEX_TLS_MODE to trusted_https_proxy, and use the Tailscale hostname for both VIBEX_PUBLIC_HOST and VIBEX_ALLOWED_HOSTS.

Step 2: connect the desktop

Select the Runtime button in the title bar to open the runtime manager.
Select Add runtime…, choose the Connection string tab, paste the whole vibex://pair#/code/... value, and select Pair. This also works when the server uses a self-signed certificate, because the fingerprint travels inside the string.
Alternatively, choose the Pairing code tab and enter the Server address and One-time pairing code.
After pairing, the runtime’s Certificate row shows a sha256: fingerprint. Compare it with tls_fingerprint in the server log.
Select Switch to this runtime to make it current. From now on, sessions, files, Git, and terminals in the desktop come from the server. To go back to your own machine, select This device in the list and switch to it. To remove the runtime, select Remove in its details — that deletes only the local device credential; the server-side authorization stays until it is revoked on the server.

Step 3: connect the mobile client

Open the mobile app and choose Pair with a Cloud Server.
Enter the server address (for example 192.168.1.10:8765) and the pairing code, then select Pair with Code.
When the server uses a self-signed certificate, paste the vibex://pair#/code/... string into the connection string field instead; it carries the certificate too.
Confirm the pairing; what this device may do comes from the server when it mints the pairing code, and defaults to Full control. To grant less, mint a new code on the server with docker exec vibex-server vibex-server pairing-code --permission read-only (choices: read-only, approve-only, full-control).

Step 4: let Agents see your code

Agents run on the server, so they only see directories inside the server (container). Your code therefore has to live there:

Clone it on the server into /data/repos/your-project, or
Mount a host directory into the container (the - /srv/repos:/data/repos line above).

Then make sure the container path is listed in VIBEX_WORKSPACE_ROOTS (the /data:/data/repos value above). In any client, open a new session, select the project directory picker, choose Choose another directory, and pick your project under /data or /data/repos.

Mounting a directory without listing it in VIBEX_WORKSPACE_ROOTS leaves it unbrowsable for clients; listing a path without mounting it leaves the directory nonexistent inside the runtime.

Step 5: day-two operations

Task	How
Upgrade to a new version	Change the version in `image`, then `docker compose pull && docker compose up -d --no-build`. With moving tags such as `rc` or `latest`, the `pull` is required or the container stays on the old image
Back up	Back up the `/data` volume. It holds the database and the server identity; losing the identity forces every device to pair again
Revoke a device	On a headless authority, run `docker exec vibex-server vibex-server revoke DEVICE_ID` on the server. When the desktop is the authority, open Pair mobile → Paired devices (N) and select Revoke there. Selecting Remove on a client runtime deletes only the local credential; it does not revoke the server-side authorization
Check the runtime	`docker exec vibex-server vibex-server status`; after changing environment variables, run `docker exec vibex-server vibex-server config-check` first
Remove the runtime	`docker compose down`. Never add `-v`, which deletes `/data` as well

2. Remote development: your phone reaching your desktop

Your computer stays the authority: Agents, files, Git, and terminals all run on the desktop, and the phone only gets a window to view and operate them. Use this when you are away and want to check progress, answer a question, or approve a request.

Before you start

The desktop app is running and the computer stays awake; sleep drops the connection.
The phone and the computer can reach each other: the same Wi-Fi is easiest, and Tailnet or a self-hosted Relay cover the rest.

Step 1: publish remote access from the desktop

Select the pair mobile device icon in the top toolbar. The dialog has two tabs: Pair publishes a new pairing, and Paired devices (N) manages the devices that already hold a grant.
Choose how the phone will connect:
- Tailnet (recommended) — private access through Tailscale or another private network; good when you are not on the same Wi-Fi.
- Direct HTTPS — you have your own HTTPS address that points at this computer.
- Self-hosted Relay — the phone and computer cannot reach each other directly, so your own Relay forwards encrypted traffic.
Fill in the address the dialog asks for (Direct expects https://your-address, Relay expects https://your-relay), choose what this phone may do (the default is Read only; see Permission levels), and select Publish.
A QR code and a pairing link appear: scan to pair, or select Copy link and send it to the phone. The link expires quickly; select Regenerate when it does.

A pairing link or QR code is a one-time secret. Do not publish it. When the phone pairs, the desktop asks for confirmation, and pairing only succeeds if you approve it.

Step 2: pair the phone

On the same Wi-Fi: the mobile app discovers nearby desktops; select yours and confirm.
On another network: scan the QR code or open the copied vibex:// link.
Manually: choose Pair with Code in the mobile app and enter the address and pairing code shown on the desktop.

The permission level is chosen on the desktop when it publishes the pairing offer, and the desktop asks you to confirm the device when the phone claims it. The phone then shows the desktop’s session list.

Step 3: what the phone can do

Capability	Notes
Sessions	Read the timeline, send follow-up messages, rename, delete, fork, and multi-select.
Approvals and elicitation	Approve or reject permission requests and fill in elicitation forms.
Files	Browse the file tree, search by name or content, and edit and save files.
Git	View status and diffs, stage / unstage / revert / commit, view history, fetch / push, and create worktrees.
Terminal	Create, attach, resize, and send input.
Usage	Shows only the session count, with the note “Usage details are available on the desktop host.”

Mobile has no Config Center, so it cannot manage Agents, providers, MCP, or Skills. Its Settings contain only Connection, Session timeline, Appearance, Notifications, and About. Every write is ultimately produced by the authoritative runtime; mobile shows its projection.

When direct access fails: self-hosted Relay

Phones and computers are often behind corporate networks or carrier NAT, so they cannot reach each other. Run the Relay on a server both sides can reach; it only forwards encrypted frames and cannot read them:

services:
  relay-server:
    image: ghcr.io/vibex-ai/vibex-relay-server:rc
    container_name: vibex-relay-server
    restart: unless-stopped
    # Publish the port on the host's loopback only; the public entry point is an HTTPS proxy
    ports:
      - "127.0.0.1:9700:9700"
    environment:
      # Listen on every interface inside the container, or the published port cannot reach it
      VIBEX_RELAY_BIND_ADDR: 0.0.0.0:9700
      # Room, connection, and rate limits all have defaults; add the variables from the
      # Relay section of the environment reference only when you need to change them

docker compose up -d
curl -fsS http://127.0.0.1:9700/health

To reach it over the public internet, give it an HTTPS/WSS entry point (for example Caddy reverse-proxying to 127.0.0.1:9700), then publish remote access on the desktop with Self-hosted Relay and enter https://your-relay-domain. The Relay is pure forwarding: it does not store sessions, files, or provider profiles, and it does not decrypt content. Rooms and connections live in memory, so a restart clears them and devices rebuild them on reconnect.

Disconnects and reconnects

After a network change, screen lock, or app resume, clients re-authenticate and catch up on missing history: they show authoritative session and timeline state first, then resume live updates.

State	What to do
`stale`	Wait for the authority to refresh; do not repeat commands with side effects from an old snapshot.
`revoked`	The device was revoked and must pair again.
`resync_required`	The client detected a sequence or cursor gap and is resyncing; treat the authority’s state as current.

Permission levels

Choose a permission when you pair a mobile device, and grant the smallest one that works. The level is decided by the initiating side when it creates the pairing, and a client cannot raise it on its own:

Level	What it can do	Use it when
Read only (`read_only`)	Read sessions, file summaries, Git status and diffs, provider summaries; every write is rejected and recorded in the audit trail	You only want to follow progress
Approve only (`approve_only`)	Everything above, plus resolving Agent permission requests and elicitation forms	You want to approve requests while away
Full control (`full_control`)	Send messages, write files, type into terminals, and perform Git writes, still capped by desktop capabilities	You really want to work from the phone

Revoke devices on the authoritative side:

When the desktop is the authority, open Pair mobile, switch to the Paired devices (N) tab, and select Revoke on the device, then confirm. Each row shows the device’s status, permission, and last activity, and Refresh devices reloads the list; more than six devices are paged.
When a headless runtime is the authority, run docker exec vibex-server vibex-server revoke DEVICE_ID (or vibex-server revoke DEVICE_ID on the server).

Revocation closes the device’s active connections immediately, and it has to pair again afterwards. Selecting Remove on a client runtime deletes only the local credential; the server-side device authorization stays.

Security checklist

Keep the runtime’s 8765 port on loopback or your private network, and always use HTTPS on the public internet. The authority listens on loopback by default; never run an unauthenticated public listener.
Grant the smallest permission level; use Full control only when you need it.
Never post pairing codes, QR codes, or connection strings publicly; each one works once, and none is a long-lived credential.
Revoke devices you no longer use.
A Relay only forwards encrypted traffic. It is not a permission boundary, and business data does not belong in its logs.

Troubleshooting first steps

Symptom	Likely cause	What to do
The phone reports an expired pairing	Pairing codes and QR codes are short-lived	Select Regenerate on the desktop and scan again
The phone cannot reach the desktop	Different networks, or the router/NAT blocks the route	Use Tailnet, or deploy a self-hosted Relay
The desktop cannot reach the server	Wrong address or port, or a closed firewall	Reach the address from the pairing string on the server itself, and check that `VIBEX_BIND_ADDR` is not loopback
A client reports a rejected certificate or host	`VIBEX_PUBLIC_HOST`, `VIBEX_ALLOWED_HOSTS`, and the address clients use do not agree	Align them with the real domain or address and restart the container
A project directory is missing from the picker	The code is not on the server, or the path is not in `VIBEX_WORKSPACE_ROOTS`	Mount it and add it as described in step 4
The session list stops updating	The client is still catching up after a network change	Let it finish or refresh manually; if it stays stuck, check that the desktop or server still runs
The phone reports a revoked device	The authority revoked that device	Pair it again
The desktop keeps using the server and you want the local runtime	The stored pairing credential restores automatically	Open the Runtime panel, select This device, and switch to it

Environment variables

The examples above use only the variables you cannot avoid. The full list of vibex-server, Relay, and desktop variables, with defaults and purposes, is in the environment reference. Deployment forms, commands, and health checks are in Self-hosted headless runtime, and the Relay’s endpoints, limits, and push configuration are in Self-hosted Relay. For deeper details on the pairing handshake, encryption, and sync contracts, read Remote v2 and Relay in the developer guide.

Get started

Daily work

Extensions and configuration

Remote development and self-hosting

Reference

Help

Cloud development and remote development

1. Cloud development: run Vibex on a server

Before you start

Step 1: start the runtime

If the server is on the public internet

Step 2: connect the desktop

Step 3: connect the mobile client

Step 4: let Agents see your code

Step 5: day-two operations

2. Remote development: your phone reaching your desktop

Before you start

Step 1: publish remote access from the desktop

Step 2: pair the phone

Step 3: what the phone can do

When direct access fails: self-hosted Relay

Disconnects and reconnects

Permission levels

Security checklist

Troubleshooting first steps

Environment variables

​1. Cloud development: run Vibex on a server

​Before you start

​Step 1: start the runtime

​If the server is on the public internet

​Step 2: connect the desktop

​Step 3: connect the mobile client

​Step 4: let Agents see your code

​Step 5: day-two operations

​2. Remote development: your phone reaching your desktop

​Before you start

​Step 1: publish remote access from the desktop

​Step 2: pair the phone

​Step 3: what the phone can do

​When direct access fails: self-hosted Relay

​Disconnects and reconnects

​Permission levels

​Security checklist

​Troubleshooting first steps

​Environment variables

1. Cloud development: run Vibex on a server

Before you start

Step 1: start the runtime

If the server is on the public internet

Step 2: connect the desktop

Step 3: connect the mobile client

Step 4: let Agents see your code

Step 5: day-two operations

2. Remote development: your phone reaching your desktop

Before you start

Step 1: publish remote access from the desktop

Step 2: pair the phone

Step 3: what the phone can do

When direct access fails: self-hosted Relay

Disconnects and reconnects

Permission levels

Security checklist

Troubleshooting first steps

Environment variables