Servers

Servers are the hosts where Synq builds and runs applications. Register SSH connection details, check required components, and install what the target needs. Server administration requires the relevant permissions and host execution policy. These operations are self-hosted only.

Register a server

A server is an SSH target you deploy onto. Responses never include SSH secrets — passwords and key passphrases are encrypted at rest and only decrypted inside the SSH client. See the custom servers guide.

const result = await ship.servers.create({
  sshHost: "203.0.113.10",
  sshUser: "root",
  sshAuthMethod: "agent",
});
console.log(result);

curl -X POST "$SYNQ_URL/api/system/servers" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sshHost":"203.0.113.10","sshUser":"root","sshAuthMethod":"agent"}'

PATCH /api/system/servers/:id takes the same fields, all optional — only the keys you send are changed. It also takes buildServer (boolean): "Can build for other servers", which lets projects deployed on other servers build their images here (see Build on another server). Every server returned by the API carries buildServer.

It also takes publicHostname (string, or null / "" to clear): the server's connection hostname, the DNS name database URLs, published-port addresses and SSH tunnel commands use instead of its IP address. Only an owner or admin can change it. It must be a DNS name with a dot in it, with no scheme, port, path or IP address; anything else answers 400 with code: "INVALID_PUBLIC_HOSTNAME" and a message saying why. Synq stores it lowercased and does not check where it points. Every server returned by the API carries publicHostname (null when not set). See Which host the address uses.

await ship.servers.update("srv_123", { publicHostname: "db.example.com" });

Server health check & install

const health = await ship.servers.check("srv_123", { components: ["docker"] });
console.log(health.ready, health.missing);

curl -X POST "$SYNQ_URL/api/system/check" \
  -H "Authorization: Bearer $SYNQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"serverId":"srv_123","components":["docker"]}'

Test a connection before saving, check what a saved server has installed, then install or remove components. These routes identify the server by serverId in the body (not a URL param), and each handler runs its own per-server server:admin (or server:read) check.

POST /api/system/test-connection opens an ephemeral SSH connection from body credentials and returns { ok, message } — nothing is persisted. It requires the caller be an org owner/admin.

Returns { components, ready, missing }.

POST /api/system/remove mirrors install for a single removable component. POST /api/system/install/stream takes { serverId, components: string[], config? } and returns a Server-Sent Events stream (progress, log, complete, end); it returns 409 install_in_progress if a session is already running.

GET /api/system/monitor/stream?serverId=<id> emits a stats event every few seconds with CPU %, memory, disk, uptime, and load average gathered over SSH — synq server monitor <serverId>.

Per-server rate limiting

Read or update the OpenResty request rate limit for a server. OpenResty on the target server is the source of truth; the API parses and rewrites its ratelimit.conf.

PATCH /api/system/servers/:id/rate-limit

Port-forward tunnels

Desktop mode only. Forward a remote server port to localhost on the operator's machine, VS Code style. Every handler additionally asserts desktop mode (an API started with DEPLOY_MODE=desktop, as desktop app versions up to 1.2.5 ran on your computer); on any other instance they refuse. The current desktop app only opens a panel, so it offers no port forwarding.

POST /api/system/servers/:id/tunnels

Start / stop / delete a saved tunnel with POST .../tunnels/:tunnelId/start, .../stop, and DELETE .../tunnels/:tunnelId. A started tunnel returns the actually-bound localPort and a http://localhost:<port> URL.

Server clusters and private networking

On a self-hosted Synq instance, private networks connect 2–16 registered Linux servers over an existing private IPv4 network or a managed WireGuard mesh. Read ship.servers.networkCapabilities() for the available provider profiles and your management permissions. Local and desktop self-hosted controllers support network inventory and manual network checks. A hosted cloud (switched off in Synq) does not offer this infrastructure management.

Compute clusters are separate records that group selected servers on an existing private network. Use the *Network methods and /api/system/networks for networking, and *ComputeCluster methods and /api/system/compute-clusters for those groups. The older *Cluster methods and /api/system/clusters URLs remain compatibility aliases for private networks.

For existing networks, create saves configuration; verify starts a separate, persisted operation. Reuse the same requestId when retrying an unchanged creation request. Update, verify, and remove require the network's current revision. Concurrent edits return a conflict, and active verification blocks configuration changes.

const network = await ship.servers.createNetwork({
  requestId: crypto.randomUUID(),
  name: "Production EU",
  network: {
    mode: "native",
    cidrs: ["10.20.0.0/24"],
    mtu: 1400,
    probePort: 51821,
  },
  members: [
    { serverId: "srv_a", providerId: "hetzner-dedicated", privateIp: "10.20.0.2" },
    { serverId: "srv_b", providerId: "hetzner-dedicated", privateIp: "10.20.0.3" },
  ],
});
const verification = await ship.servers.verifyNetwork({
  networkId: network.id,
  revision: network.revision,
});
console.log(verification.id, verification.status);

Subscribe to the read-only SSE endpoint GET /api/system/networks/stream for verification progress, including after reconnecting. Use ship.servers.getNetwork({ networkId }) to read a saved snapshot. Reports contain per-direction TCP, UDP, MTU, UDP round-trip latency, packet loss, and jitter results. Managed WireGuard reports also contain per-peer handshake observations. Hosts need Linux, Python 3, iproute2, a persistent machine identity, and working private interfaces and routes. The chosen probe port must permit TCP and UDP between members. The inspector ship.servers.inspectNetwork(serverId) reads interfaces without configuring them.

Temporary authenticated listeners bind to the selected private addresses and expire locally if cleanup loses contact. Runs expire after four minutes; successful observations are considered stale after fifteen minutes. The probe tests its selected port and packet size. Encryption and application-port access are not verified.

After a verification has finished, optionally measure a selected connection in both directions using the same endpoint:

const network = await ship.servers.getNetwork({ networkId: "network_id" });
const speedTest = await ship.servers.verifyNetwork({
  networkId: network.id,
  revision: network.revision,
  speedTest: { sourceServerId: "srv_a", targetServerId: "srv_b" },
});

Speed tests first check connectivity, then transfer at most 32 MiB or for three seconds per direction. report.throughput records receiver-confirmed bytes, elapsed time, and Mbps, or a specific transfer error. Ordinary verification does not send bulk traffic. Both servers must belong to the cluster; a different test cannot start while a verification is active. Repeating an active request for the same pair reuses its run. Progress and final results use the same SSE stream.

Cluster reads require fleet-wide server read access. Management requires fleet-wide server admin access, with each member also authorized. Removing a native cluster removes its inventory records; servers and externally managed networks remain. Managed networks use the reviewed cleanup flow below. A member must leave its cluster and settle any operation before its server entry can be removed. Clusters are not yet deployment targets. Provider API/VLAN provisioning, private service endpoints, placement/replicas, and shared storage remain separate capabilities.

Managed private networks

Managed networking creates an encrypted WireGuard mesh with automatically allocated private addresses. Start server preparation to check infrastructure, install missing tools, and create a reviewable plan:

const preparation = await ship.servers.prepareManagedNetwork({
  requestId: crypto.randomUUID(),
  name: "Production mesh",
  members: [
    { serverId: "srv_a", providerId: "hetzner-dedicated" },
    { serverId: "srv_b", providerId: "custom" },
  ],
});
console.log(preparation.id, preparation.status, preparation.hosts);

for await (const event of ship.servers.managedNetworkPreparationEvents(preparation.id)) {
  if (event.event === "snapshot") {
    const { run } = JSON.parse(event.data);
    console.log(run.sequence, run.status, run.hosts);
  }
}

The subscription sends a complete saved snapshot on connect and whenever progress changes, then complete before closing for a settled attempt. The dashboard reconnects with backoff after a dropped connection. SDK callers can reattach using the same method; a reconnect never starts work. Replace local state with each snapshot instead of appending its logs. The monotonic sequence also protects against late responses.

ship.servers.getManagedNetworkPreparation({ preparationId }) remains available for a single saved-state read. When its status is ready, use its operationId to read the network plan. Retry a failed or interrupted preparation by calling prepareManagedNetwork with the same input and request ID. Already healthy tools are checked and reused. listManagedNetworkPreparations() lists recent work that still needs attention or review. No tunnel changes start during preparation.

To discard a stopped preparation, call discardManagedNetworkPreparation({ preparationId, sequence }) with its latest progress sequence. An unapplied plan can be discarded with discardManagedNetworkPlan({ operationId, planHash }). Both require fleet administration. The preparation and any unapplied plan close in one transaction and disappear from pending setup; existing servers, services, and installed tools are retained. Cancelled records remain readable for diagnostics and prevent late retries from reviving discarded work. Active preparation must finish first.

To remove one server from an unfinished initial cluster setup, call removeManagedNetworkPreparationMember({ preparationId, serverId, sequence, requestId }). For an initial network operation, use removeManagedNetworkOperationMember({ operationId, serverId, sequence, planHash, requestId }). At least two servers must remain. Use a new UUID for requestId, then reuse it if the response is lost. A different selection requires a different request. Both methods require fleet administration and return { preparation, operation }. The original records link to the replacement through replacementPreparationId; settings and diagnostics remain available, and the original request cannot resume.

Before network apply, removal cancels the old selection and saves the remaining servers in a paused (pending) preparation. After a partial apply, it also has a cleanupOperationId. Synq reuses rollback to restore this attempt's network changes on all original hosts, including peer entries for the removed server. The server, its workloads, disks, other networks, and shared installed tools remain. The pending preparation stream stays open while cleanup runs; subscribe to the cleanup operation for per-host progress. An unreachable or externally modified host keeps cleanup and reservations open. Retry that operation with action: "rollback" after resolving the problem. Once all hosts acknowledge rollback, preparation remains paused. Explicitly call prepareManagedNetwork with the replacement's saved input to retry; it rejects the request until cleanup is complete. Removal, cleanup retries, and stream reconnection do not start preparation. The resulting network plan always requires a fresh review and apply. Established clusters use their existing reviewed membership-change workflow.

For hosts that already meet the prerequisites, planManagedNetwork accepts the same input and performs read-only inspection without installing packages.

After review, pass that operation ID and hash to ship.servers.applyManagedNetwork({ operationId, planHash, action: "apply" }). Plans expire after fifteen minutes and reject changes to the cluster revision, host identities, or inspected networking. Subscribe with ship.servers.managedNetworkOperationEvents(operationId) for durable progress; getManagedNetworkOperation({ operationId }) provides a single state read. The same operation supports action: "resume" or action: "rollback" after an interruption. Active work is idempotent and cannot be started twice. Once network changes have started, discard is blocked. Use action: "rollback" to clean up an unfinished new cluster or restore an existing cluster's previous network. Every host must acknowledge cleanup before inventory and reservations are released. An unreachable host keeps recovery open; retry rollback when access is restored. A restored existing cluster can then use the reviewed removal flow.

ship.servers.clusterEvents() streams overview snapshots containing clusters and preparations. All three subscription methods accept { signal } to disconnect a viewer without cancelling setup. Streams use saved database state, validate fleet read permission again during the subscription, and reconcile every fifteen seconds to detect another controller's updates and expired worker leases.

Hosts require Linux with WireGuard kernel support, Python 3.8+, iproute2, systemd, and root or passwordless sudo. Preparation automatically installs missing Python 3.8+, iproute2 (4.15+), and WireGuard tools (1.0+) through the shared toolchain. It verifies installation before inspection. Kernel, init-system, and privilege problems stop at a named step; Synq does not replace kernels or reboot hosts. Installed tools remain installed if the later network operation rolls back. Supported firewalls are no active host firewall, raw iptables, or nftables with standard inet filter input/output chains and no additional filtering IPv4 input/output base chains. UFW, firewalld, and unsupported nftables layouts fail inspection. Provider firewalls must allow the reviewed transport ports (default 51820/UDP). Transport uses reachable IPv4 endpoints with no relay or automatic NAT traversal. IPv6 SSH management works when explicit IPv4 transport endpoints are supplied. Preparation checks local prerequisites and routes; it does not prove UDP access between hosts. After Apply, the transport step stages WireGuard endpoints and owned host firewall rules. The handshake step tests every peer before configure assigns private addresses and routes. Failures retain per-peer endpoints and ports and restore the previous configuration. Provider firewall or NAT changes require administrator action before an explicit retry.

Private keys stay on their hosts. Each host has a persistent twenty-minute rollback timer, so incomplete setup can restore even if the controller disconnects or the host reboots. Synq changes only its own interface, peer routes, and firewall rules. The transport stage uses the same receipt and rollback timer; successful promotion preserves the verified interface and keys. Handshakes and every directed TCP/UDP/MTU check must succeed before commit. Committed networking restarts locally without the controller. Unreachable or externally edited hosts retain their claims until recovery is confirmed.

For managed edits, include clusterId and revision in a new plan. Membership, transport endpoints/ports, MTU, and rotateKeys can change; existing addresses and the allocated subnet remain stable. To remove a managed cluster, plan with intent: "remove" and review its host cleanup before applying. These network operations do not drain workloads or migrate their data.

Compute clusters

Create a compute cluster by selecting servers already attached to a private network. The network and compute-cluster memberships are independent. Reuse the same requestId to retry an unchanged create request; updates and removals require the compute cluster's current revision.

const cluster = await ship.servers.createComputeCluster({
  requestId: crypto.randomUUID(),
  name: "Production EU",
  networkId: "network_id",
  serverIds: ["srv_a", "srv_b"],
});
console.log(cluster.id, cluster.networkId, cluster.serverIds);

removeComputeCluster({ clusterId, revision }) removes this grouping and retains its servers and private network. ship.servers.infrastructure(serverId) reports the networks and compute cluster associated with a server.

Managed K3s setup

Creating a pool does not install software. Start its separate runtime operation after connecting the selected servers to their private network:

const runtime = await ship.servers.setupClusterRuntime({
  clusterId: "cluster_id",
  revision: 1,
  requestId: crypto.randomUUID(),
});
console.log(runtime.status);

const abort = new AbortController();
for await (const event of ship.servers.clusterRuntimeEvents("cluster_id", { signal: abort.signal })) {
  console.log(event.data);
  abort.abort(); // Close the subscription when leaving the setup view.
  break;
}

Setup installs missing tools, pins and checksum-verifies K3s, configures private host firewall rules, joins the servers, and checks actual pod traffic, Services and DNS. One control server is used for one/two-member pools; larger pools use three controls and additional workers. Initial support requires Linux amd64/arm64, systemd, root or passwordless sudo, disabled swap, and unfiltered or raw iptables host firewalls. Provider private-network ACLs remain the operator's responsibility; the dashboard lists exact private peer ports. These ports should not be exposed publicly.

Read saved progress with getClusterRuntime({ clusterId }); it returns null before setup. Retry an interrupted or failed operation explicitly using retryClusterRuntime({ clusterId, sequence }). The retry retains the pinned version/configuration and reconciles host state. Reconnecting to SSE never starts or retries installation. Runtime streams remain open to observe later changes; cancel them when leaving the page. Snapshots contain dated verification, not continuous workload monitoring.

removeClusterRuntime({ clusterId, sequence }) starts owned cleanup. Application workloads, persistent volumes and additional operators must be removed first. Cleanup preserves the private network and existing Docker applications, and can resume after a partial removal. Removing the pool or changing its members/network is blocked while a runtime remains installed or unfinished.

This prepares Kubernetes infrastructure. Cluster deployment targets, database operators, persistent storage and Edge routing are subsequent integrations; existing project deployments continue using their current runtime.

Operations

Managed containers

Components and installation

Server lifecycle

Private networks

Compute clusters

Cluster runtime

Legacy network methods

Git credentials

Networking

Docker maintenance

Legacy network URLs