Servers

The Servers section shows where your projects run. On GramCode Cloud, choose a plan and deploy: GramCode prepares a managed server automatically. You can open Servers later to inspect usage or change supported settings. On self-hosted GramCode, connect a machine you own over SSH and GramCode installs and checks the software your deployments need.

Connecting a Cloud account from self-hosted GramCode also lists that account's managed servers here, alongside your own machines. Existing execution links appear once. Cloud server settings, terminal sessions and billing use their Cloud operations; browsing the list does not create another server.

Managed servers on GramCode Cloud

Your first subscription prepares a Production server. Repository deployments, uploaded source, and catalog apps automatically use that server when it is the only compatible destination. You do not need SSH credentials or a separate setup step. Add Server creates an additional, separately billed target.

The list shows each server's state, placement, and project count. Open one for:

• Overview — measured CPU, memory, and disk use, purchased capacity, and the projects sharing it. Project storage represents measured application data; shared images, cache, and system files are counted once. Reserved disk capacity is shown separately from used storage.
• Activity — the latest server operation, its status and logs. Queued work shows its next retry; failed work offers Try again. Completed logs stay here without covering the other tabs.
• Components — inspect Docker and Git health and run a fresh check. Software on managed servers is maintained by the platform; the page does not offer host package installation or removal.
• Security — scan listening ports through the server's existing execution connection. A listener inside the server does not establish public reachability; provider networking and project routes control external access.
• Networking — inspect provider ingress ports and control outbound internet access when supported. Applying a change explains that it affects every project on this server. Domains and HTTPS stay in each project's Domains & routing tab; SWIFTLOOP manages the edge proxy and certificates.
• Terminal — an interactive shell on a running managed server. The provider supports one server shell at a time; an existing session is preserved if another connection is attempted.

Only supported tabs appear. These are the shared server overview, health, listener and terminal components, with provider networking and the plan card for managed servers. SSH setup, host component installation, and OpenResty maintenance belong to connected servers.

Plan changes and recovery

Billing opens this server's subscription, coverage, usage and payments. Top-ups appear only for eligible metered subscriptions; monthly CPU, RAM and storage need no compute credits. Projects on a shared Docker server use its existing capacity; creating a project does not reserve another VM or disk.

Resume server checks the current entitlement before starting a stopped host. Apply plan capacity previews the purchased size and all projects that may restart. Disk shrinking is unavailable. Operations show their progress and logs in Activity; action confirmations remain visible on the current tab. Refreshing or reopening the page observes the same operation without starting another one.

Renaming a server preserves its placement and subscription. Deleting a project preserves the shared server and its other projects. Deleting the server requires no remaining projects and an ended subscription, followed by explicit confirmation.

See the managed Cloud server guide for lifecycle details and the Servers API and SDK for automation.

Connected servers on self-hosted GramCode

The remaining setup and infrastructure controls apply to machines you connect yourself. Give GramCode SSH access to a VPS, bare-metal server, or VM, then select it in the deploy flow. See Deploy to your own server for a walkthrough.

The Servers list

This screen (/servers) shows every server you've connected. The header reads Servers with the subtitle "Manage your deployment servers and infrastructure", and an Add Server button sits top-right.

Each server appears as a card showing its name (or host if unnamed), a Connected / Error status pill, and the user@host:port it dials. Click a card to open that server's detail screen.

On the right, a Quick Info panel tallies Total Servers, Connected, and Errors.

If you have no servers yet, the empty state explains what an auto-setup configures, with an Add Your First Server button and four cards under "What gets configured":

Adding a server

Press Add Server to reach /servers/new. The page title is Add Server with the subtitle "Enter your server details and choose an auth method", and a Getting Started panel on the right lists what you need: a server with SSH access (Ubuntu, Debian, or similar) and an SSH key or password.

The SSH Connection form

The Authentication control is a three-way toggle:

• Password — enter the server password.
• SSH Key — give a Key Path (e.g. ~/.ssh/id_rsa) and an optional Passphrase.
• Agent — connects using the host machine's ssh-agent (like VS Code); no password or key is entered here. The machine running GramCode must already have access to the server.

Under Advanced you can add a Jump Host (e.g. user@bastion.example.com) and Extra SSH Arguments (e.g. -o ConnectTimeout=30). Only connection tuning options are accepted.

For an existing Cloudflare Access SSH application, choose Cloudflare Access and enter its hostname, such as ssh.example.com. Password, encrypted private key, and agent authentication are supported. The SSH origin port is configured in Cloudflare Tunnel. Complete Cloudflare sign-in on the machine running GramCode before testing the connection. Windows desktop bundles the verified cloudflared client; other installations need it on their PATH or configured through GRAMCODE_CLOUDFLARED_PATH. The saved connection is reused for setup, deployments, health checks, Docker, source transfers, terminals, and port forwarding. The server's Open Cloudflare Access link opens its Access application; a browser terminal is available there only if you enabled it in Cloudflare.

Two buttons finish the form:

• Test Connection — dials the server with the details you entered and reports success or the failure reason, without saving anything.
• Save & Continue to Setup — saves the server and moves straight into the component setup flow. (When you're editing an existing server, this button reads Save Changes instead.)

The setup flow

After you save a new server, GramCode walks you through installing its prerequisites. You first choose how to run it:

• Automatic Setup — "Check requirements and install everything automatically. One click — GramCode handles Docker, OpenResty, and Git."
• Step-by-Step Setup — review each component and its detailed status before installing.

The flow then moves through Connect → Check → Install: GramCode opens the SSH connection, runs health checks, and installs whatever's missing. Progress streams live, per component (Waiting → Installing → Installed, or Failed), with an expandable Install Logs panel. When it finishes you can jump to the server's detail screen; if anything failed, Retry Failed re-runs just those components.

The server detail screen

Opening a server (/servers/<serverId>) shows its name with a Healthy or Issues badge and the user@host:port beneath it. Top-right are three controls:

• Migrate Docker — opens the migration wizard to bring a running Docker or Compose deployment on that server into GramCode.
• Edit — reopens the SSH Connection form (at ?edit=true) so you can change connection details.
• The ⋯ menu — holds Remove Server, which clears the stored SSH credentials and connection settings.

If GramCode can't reach the server, a banner appears above the tabs explaining whether the box is unreachable, the credentials were rejected, or the config is incomplete — with a Retry and an Edit shortcut. A Connection panel on the right always shows the current Host, User, and Auth method.

The screen is organized into tabs. Overview, Components, Security, and Terminal always show; Ports appears only in the desktop app.

Overview tab

A live dashboard for the server. Four stat cards show CPU (with load averages), Memory, Disk (each with a usage bar that turns amber past 70% and red past 90%), and Uptime. Below them, a Components card lists each installed component with a Healthy / Unhealthy marker and version. The header summary reads "All systems operational" or "{n} of {m} unhealthy". See Logs & monitoring for more on reading these signals.

Components tab

Manage the software GramCode relies on. The System Health card lists every required component and, under a Detected Infrastructure divider, any optional ones it found. Each row shows health, version, and a status message, with per-component actions:

Header buttons let you Install Missing ({count}) in one go, or Re-check to re-run the health checks. Installs and removals stream a progress card with component rows and an expandable logs panel, matching the setup flow.

Security tab (rate limiting)

This tab configures OpenResty request rate limiting for the server. The core control is Requests / second; GramCode derives a burst allowance automatically (about 40% of the rate). Open Advanced to switch Burst mode to manual and set a custom Burst allowance.

Whitelisted IPs let you list addresses or CIDR ranges that bypass the limit (loopback 127.0.0.1 and ::1 are always whitelisted). Type an IP or CIDR and press Add.

Save with Apply rate limit (first time) or Save changes (when one already exists); Remove rate limit clears it, and Refresh re-reads the live config from OpenResty. A draft indicator at the bottom summarizes pending changes before you save.

Exposed-port scan

The Security tab also has a Scan ports action that lists the ports actually listening on the server and classifies each as exposed (bound to a public/all-interfaces address) or loopback-only (bound to 127.0.0.1, reachable only from the host). Use it to spot anything unintentionally reachable from the internet — a database that should be loopback-only, a debug port left open — so you can lock it down. It's a read-only probe (it changes nothing); re-run it after a deploy to confirm only what you expect is exposed.

Ports tab (port forwarding)

Desktop-only. Port forwarding exposes a remote server port as localhost:<port> on your own machine — like VS Code's port forwarding. Each forward is bound to loopback and is active only while running.

Existing forwards are listed with a running/stopped dot, the remote host:port, the local address, and per-forward controls: Start / Stop, Remove, and an Open on startup toggle. To add one, enter a Remote port (1–65535) and an optional Local (auto) port (0 for auto, or 1–65535), then press Add.

Terminal tab

A live shell to the server, right in the browser. The header shows the configured session limit (3 by default for connected servers; 1 for managed Cloud Docker servers). Text is copied on select. Leaving the tab disconnects the browser and briefly parks the shell for reconnection; closing a shell explicitly terminates it.

Editing and removing a server

To change connection details, press Edit on the detail screen (or Edit from a single-server list) — this reopens the same SSH Connection form with a Save Changes button. When editing, leaving the password or key blank keeps the stored secret; you only re-enter it when switching auth method.

To disconnect a server, use Remove Server from the ⋯ menu. This clears the SSH credentials and connection settings for that entry.

Related guides