Servers

Servers identify where GramCode builds and runs applications. The same serverId is used for Cloud-managed instances and connected SSH/local hosts. Responses include capabilities; offer only the actions supported by that server. The terminalSessionLimit field reports the supported concurrent host shell count.

Server administration requires a server grant. Shared host access can affect all projects on that host. SSH setup, components and edge administration are available only for self-hosted connections. GramCode Cloud manages those automatically.

Managed Cloud servers

The normal Cloud flow creates the first shared server automatically when a customer chooses a plan or creates a project. To create an additional server:

const managed = await ship.servers.createManaged({ name: "Production" });
const checkout = await ship.billing.createSubscription({
  workspaceId: managed.id,
  planTierId: "pro",
  interval: "monthly",
  idempotencyKey: crypto.randomUUID(),
});

Complete checkout through the billing workflow. Verified payment queues server setup. Use managed.serverId for project placement, server usage, terminal access and lifecycle operations. managed.id is the subscription owner identifier used only for billing.

Self-hosted and desktop installations can use these same managed servers after connecting an GramCode Cloud account. Create a new server with createManaged, or list and link an existing server:

const available = await ship.servers.availableManaged();
const selected = available.servers[0];
if (selected) {
  const linked = await ship.servers.connectManaged({ serverId: selected.id });
  console.log(linked.serverId); // This installation's deployment destination.
}

Linking requires administration of the server in Cloud and permission to add a server locally. The link pins the Cloud API, account and organization. Changing the connected account cannot silently redirect existing projects. Project configuration stays on the installation that created it; the managed server's subscription and host lifecycle remain controlled by Cloud.

servers.ensure(id), resize(id, input), retry(id) and removeManaged(id, input) queue durable work. Poll servers.get(id) and read managed.operation for logs, errors and retry timing. An HTTP 202 means accepted; inspect operation completion before claiming readiness. Reads never create or resume a server.

servers.usage(id) returns measured host usage and accessible projects. Missing measurements are null; purchased disk capacity is never substituted for bytes used. servers.previewResize(id) returns the current and purchased sizes, affected projects and a revision. After approval, send that revision with confirmRestart: true and an idempotency key to servers.resize.

Reuse the same resize key after an uncertain response. A changed plan or project membership requires a fresh preview. Disk shrinking requires migration. Deleting a managed server also requires billing administration, no projects, no unsettled checkout and an ended subscription. Deleting one project never deletes a shared server or its siblings.

Cloud includes projects registered by linked installations when checking whether a server is empty or safe to resize. A linked installation must finish or recover its active operation before another controller can change that server. Cloud cannot report complete service counts or build minutes for projects whose records live on another installation; those billing counters are null rather than a partial total. Host measurements and provider billing remain available.

servers.getNetworkSettings(id) reads the supported provider network fields. updateNetworkSettings(id, { internetAccess, expectedInternetAccess, confirm: true }) changes outbound internet only. Disabling it affects external APIs and builds for every project. Ingress, domains and private connectivity remain managed by project routing. Host terminals use the normal authenticated terminal endpoint; the provider supports one host terminal session per managed server at a time.

Use these same operations through MCP, checking permissions, capabilities and operation results. See the managed server guide for deployment, capacity and recovery behavior.

Register a server

On self-hosted GramCode, register a machine you own as an SSH deployment target. 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 "$GRAMCODE_URL/api/system/servers" \
  -H "Authorization: Bearer $GRAMCODE_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.

Server health check & install

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

curl -X POST "$GRAMCODE_URL/api/system/check" \
  -H "Authorization: Bearer $GRAMCODE_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 — openship 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-only. Forward a remote server port to localhost on the operator's machine, VS Code style. Every handler additionally asserts desktop mode; on a non-desktop instance they refuse.

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 GramCode 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. SWIFTLOOP-managed Cloud 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 private network; 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.

Network reads require fleet-wide server read access. Management requires fleet-wide server admin access, with each member also authorized. Removing an adopted private network removes GramCode's inventory records; servers and the externally managed network remain. Managed networks use the reviewed cleanup flow below. Membership and active operations must be settled before removing a server. A private network connects hosts; a compute cluster with a ready runtime can run application replicas and databases. Shared storage is enabled separately. Provider API/VLAN provisioning remains outside the managed-network setup.

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. GramCode 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; GramCode 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. GramCode 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.

Once setup is ready, select the cluster from a project's topology to run the application across its servers, or add managed PostgreSQL and Redis databases. Existing project deployments move only when you select the new target and deploy.

Share files across servers

Use Share storage on the cluster to prepare independent copies on at least two servers. The setup installs required tools, checks the selected empty directories, configures shared storage and verifies a write/read across servers. It never formats disks. Its technical implementation is shown in collapsed details.

setupClusterStorage accepts the reviewed disks, copy count and a stable request ID. Read getClusterStorage or subscribe to clusterStorageEvents until setup is ready. After an interruption, inspect the saved error and explicitly retry with the latest sequence. Use observe: true when reading status for current capacity and disk health.

Choose an external backup destination to enable recoverable file archives. Projects can then create, mount, expand, back up and restore their own shared volumes. Replicated copies keep files available inside the cluster; an external backup provides a recovery point after deletion or data corruption.

Disconnect and remove project volumes before removing shared storage. Empty-storage cleanup preserves external archives and the cluster's other storage classes. Remove shared storage before removing the cluster runtime.

Operations

Managed containers

Components and installation

Server lifecycle

Private networks

Compute clusters

Cluster runtime

Shared storage

Legacy network methods

Git credentials

Networking

Managed servers

Observe

Legacy network URLs