一键导入
vers-networking
How Vers VM networking works — public URLs, port routing, TLS proxy, IPv6, and running services on VMs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
菜单
How Vers VM networking works — public URLs, port routing, TLS proxy, IPv6, and running services on VMs.
用 Codex 或 Claude 帮你安装 复制这段 Prompt,粘贴到 Codex、Claude 或其他助手里,让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Bootstrap a self-improving agent fleet on Vers from scratch. Walks through deploying agent-services, building a golden image, testing the loop, and running first tasks. Use when onboarding someone new to the Vers agent fleet workflow.
Bootstrap a Vers VM into a golden image with punkin-pi, Node.js, dev tools, and swarm extensions installed. Creates a committed snapshot that can be branched for self-organizing agent swarms.
Contribute a bug fix or improvement to pi-v. Use when you've found and fixed an issue in the pi-v package.
Orchestrate agent swarms across Vers VMs - spawn parallel agents on branched VMs for distributed work, parallel exploration, or multi-path problem solving. Use when you need to run multiple agents simultaneously on isolated environments.
Manage Vers VMs (vers.sh) - create, branch, commit, restore, pause/resume Firecracker VMs. Use when working with Vers platform, VM orchestration, or when you need isolated execution environments.
Deep investigation of Vers platform issues (API, orchestrator, agent, docs). Use when encountering any Vers platform problem that needs thorough debugging and issue reporting.
| name | vers-networking |
| description | How Vers VM networking works — public URLs, port routing, TLS proxy, IPv6, and running services on VMs. |
Every Vers VM gets a public URL and can serve traffic on any port. This is how you expose services, APIs, and web interfaces running on VMs.
Every VM is reachable at:
https://{vmId}.vm.vers.sh:{port}
For example:
https://45a68069-defc-4233-9865-6298d87053af.vm.vers.sh:3000/health
The Vers proxy terminates TLS and routes traffic to the specified port on the VM. This works for any protocol over TCP — HTTP, WebSocket, gRPC, etc.
https://, the proxy terminates TLS and forwards to the VM. Your service does NOT need to handle TLS.:: or ::1) for the proxy to reach them. Binding to 0.0.0.0 (IPv4 only) will not work through the proxy.Most frameworks default to IPv4 (0.0.0.0). You must configure them to listen on :: (all interfaces, IPv6 + IPv4 dual-stack).
Node.js (Hono + @hono/node-server):
import { serve } from "@hono/node-server";
serve({ fetch: app.fetch, port: 3000, hostname: "::" });
Node.js (native http):
server.listen(3000, "::");
Python:
# Flask
app.run(host="::", port=3000)
# uvicorn
uvicorn.run(app, host="::", port=3000)
From any machine (local, another VM, CI):
curl https://{vmId}.vm.vers.sh:{port}/health
If you get a connection timeout, check:
ss -tlnp on the VM)ss -tlnp | grep {port} should show :::port)vers_vms to check state)Start your service on the VM, bound to ::, on any port:
PORT=3000 node dist/server.js
Clients use:
https://{vmId}.vm.vers.sh:3000
VMs reach each other the same way — via the public URL. There is no private network between VMs. All traffic goes through the TLS proxy.
# From one VM, call another VM's API
curl https://{otherVmId}.vm.vers.sh:3000/api/data
Connect via wss://:
const ws = new WebSocket("wss://{vmId}.vm.vers.sh:8080");
Use a service registry to track which VMs are running which services:
# Register
curl -X POST https://{infraVmId}.vm.vers.sh:3000/registry/vms \
-H 'Content-Type: application/json' \
-d '{"id": "{vmId}", "name": "my-service", "role": "worker", "address": "{vmId}.vm.vers.sh", "services": [{"name": "api", "port": 3000}]}'
# Discover
curl https://{infraVmId}.vm.vers.sh:3000/registry/discover/worker
Any Vers VM can SSH directly into any other Vers VM using the TLS proxy. This works out of the box — golden image SSH keys are pre-installed on all VMs, so no key exchange or setup is needed.
ssh -o StrictHostKeyChecking=no \
-o ProxyCommand="openssl s_client -connect %h:443 -servername %h -quiet 2>/dev/null" \
root@{vmId}.vm.vers.sh
The ProxyCommand tunnels the SSH connection through the Vers TLS proxy on port 443, just like HTTPS traffic. The -o StrictHostKeyChecking=no flag avoids host key prompts when connecting to new VMs.
scp or rsync (with the same proxy command) to move files between VMs.A lieutenant building code on its own VM can deploy to a separate infra VM:
INFRA_VM="45a68069-defc-4233-9865-6298d87053af"
SSH_OPTS='-o StrictHostKeyChecking=no -o ProxyCommand="openssl s_client -connect %h:443 -servername %h -quiet 2>/dev/null"'
# Copy built artifacts to the infra VM
scp $SSH_OPTS -r ./dist root@${INFRA_VM}.vm.vers.sh:/root/workspace/my-service/dist
# Restart the service remotely
ssh $SSH_OPTS root@${INFRA_VM}.vm.vers.sh "cd /root/workspace/my-service && npm start"
REMOTE_VM="7b2c1f3e-aaaa-4000-bbbb-123456789abc"
SSH_CMD='ssh -o StrictHostKeyChecking=no -o ProxyCommand="openssl s_client -connect %h:443 -servername %h -quiet 2>/dev/null"'
rsync -avz -e "$SSH_CMD" ./logs/ root@${REMOTE_VM}.vm.vers.sh:/root/workspace/collected-logs/
root user by default.All ports are public by default. There is no firewall. Any service you start is reachable by anyone on the internet. Always protect services with authentication.
For your coordination services, set VERS_AUTH_TOKEN env var. All endpoints except /health will require Authorization: Bearer <token>. Pass the same token to worker VMs so they can authenticate.
# Start with auth
VERS_AUTH_TOKEN=$(openssl rand -hex 32) PORT=3000 node dist/server.js
# Authenticated request
curl -H "Authorization: Bearer $TOKEN" https://{vmId}.vm.vers.sh:3000/board/tasks
0.0.0.0 instead of :: — The proxy routes via IPv6. IPv4-only services won't be reachable through the public URL (but will work locally on the VM).