gitterm
Get started

Previews

Expose a port from a cloud workspace as a URL, and choose whether it is private to you or public to anyone with the link.

View as markdown

Any port in a running cloud workspace can get its own URL. Use it to open the app your agent is working on, or to point a webhook at the workspace. This page covers opening ports and choosing who can reach them.

For previews from a local agent's sandbox, see Jobs and previews instead.

Private and public ports

VisibilityWho can reach the URLUse it for
private (default)Only you, in a browser signed in to GittermWatching a dev server while the agent works on it
publicAnyone with the URL, no Gitterm loginAPIs, webhook receivers, demos

Gitterm removes its own session cookies before a request reaches your app.

Port URLs

The URL depends on how the deployment routes workspaces:

Text
https://<port>-<workspace>.<domain>      # subdomain routing
https://<domain>/ws/<port>-<workspace>   # path routing

<port> is the port number, <workspace> the workspace's subdomain, and <domain> the deployment's domain. Apps that load assets from absolute paths such as /assets/app.js work best with subdomain routing.

Open a port from the dashboard

  1. Click the running workspace's row to open its details, then click Open port under Ports.
  2. Enter the Port (1 to 65535) and, optionally, a Name.
  3. Turn on Public URL only if the port must be reachable without a Gitterm login.
  4. Click Open port in the dialog.

You should see the port, such as :3000, under Ports. Click it to open the URL. Click Private or Public next to the port to switch its visibility, or close the port from the same line.

Open a port from inside the workspace

The gitterm CLI is installed in supported workspace images and signs in as the workspace itself. The agent can use it too.

Shell
gitterm ports open 3000 --name app
gitterm ports open 8080 --name api --public
gitterm ports list
gitterm ports visibility 3000 public
gitterm ports close 3000

Inside a workspace, the CLI can only see that workspace. All flags are in the CLI reference.

Open a port from code

Inside a workspace, createGittermWorkspaceClient() reads the identity Gitterm injects (WORKSPACE_API_URL, WORKSPACE_AUTH_TOKEN, WORKSPACE_ID):

TypeScript
import { createGittermWorkspaceClient } from "@gitterm/sdk";

const workspace = createGittermWorkspaceClient();
const app = await workspace.ports.open(3000, { name: "app" });
const api = await workspace.ports.open(8080, { name: "api", visibility: "public" });
await workspace.ports.setVisibility(3000, "public");
console.log(app.url, api.url);

A port opens as private unless you set visibility. Opening a port that is already open keeps its current visibility.

Related