Updated · 2026-06-23

Project networking

Every project gets a private network. VMs in the same project reach each other by name (e.g. db) over their service ports — no public exposure. VMs in different projects are isolated. Public ports (open_port, custom domains) are only for traffic from outside Superjolt.

Every project gets its own private network. VMs you create in the same project can talk to each other directly and privately — no public ports, no firewall rules to manage. VMs in different projects are isolated from each other.

Reach a VM by name

Each VM gets a stable private address, and an internal DNS name from its name. From inside any VM in the project, another VM resolves by its name:

# from the backend VM, reach the VM you named "db"
psql -h db -U postgres
curl http://api:3000/health

So you don’t pass IPs around — name your database VM db, your API api, and connect by those names. (Names are scoped to the project; the same name in another project won’t collide. If two VMs in one project share a name, the older one wins the alias — keep names unique.)

Need the raw private IP instead? It’s in the create_vm and list_vms responses.

Worked example: backend + Postgres

The canonical two-VM setup — an app server talking to a database, both private:

create a postgres VM called "db" and a nodejs VM called "api" in the shop project,
and point the api at the db

Your agent chains:

  1. create_vm image: postgres-18, name: db, project: shop — Postgres on :5432, credentials at /root/.postgres-credentials.
  2. create_vm image: nodejs-24, name: api, project: shop — your app on :3000.
  3. Set the API’s database URL to postgresql://postgres:<pw>@db:5432/postgres (the password from the db VM’s credentials file). The db name resolves over the project’s private network.
  4. add_domain (or rely on the auto-exposed :3000 URL) to put the API on the public internet — while the database stays private, reachable only from within the project.

That’s the pattern: public surface on the front-end VM, everything else private. It’s why the database images aren’t auto-exposed — they’re built to be reached from a sibling VM, not the open internet.

Public vs private — when to open a port

  • Private (default): VM-to-VM within a project. Use the service port directly (db:5432, queue:6379). Nothing to configure.
  • Public: traffic from outside Superjolt (browsers, webhooks, your laptop). Expose it explicitly with open_port (raw TCP/HTTP) or attach a custom domain. Databases should stay private unless you genuinely need external access.

Notes