Projects

A project combines source code, build configuration, environment variables, domains, and deployment history. Create a project record first, then submit a deployment.

Local filesystem and edge administration operations require self-hosted capabilities. For Cloud, connect to the Cloud API directly. Fixed scopes do not forward through an owner's Cloud link.

Create a project

Create a project from a git repo or a local path, baking the build config into the project row. For an uploaded folder, use the source upload flow instead. Only name is required — everything else is auto-detected or defaulted.

const result = await ship.projects.create({
  name: "marketing-site",
  gitOwner: "acme",
  gitRepo: "site",
  gitBranch: "main",
  framework: "nextjs",
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/projects" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"marketing-site","gitOwner":"acme","gitRepo":"site","gitBranch":"main","framework":"nextjs"}'

Scale a stateless application on a cluster

Self-hosted projects can target a ready server cluster. Saving the target requires fleet administration. Choose a registry repository for source builds; cluster nodes pull immutable release images using the saved registry credentials. This supports a single application or worker whose instances can start on any selected server. Project-owned shared volumes can persist files across instances; node-local bind mounts and Compose conversion require a separate migration. PostgreSQL and Redis use their own managed database lifecycle and replication.

const current = await ship.projects.getClusterWorkload("proj_123");
await ship.projects.setClusterTarget("proj_123", {
  clusterId: "cluster_123",
  config: { replicas: 3, imageRepository: "ghcr.io/acme/api" },
  expectedUpdatedAt: current.updatedAt,
  stateless: true,
});
// Deploy the project through the existing Deployments API.
// After that release is active, change its replicas without rebuilding:
const live = await ship.projects.getClusterWorkload("proj_123");
if (live.activeDeploymentId && live.activeClusterId === live.clusterId) {
  const scale = await ship.projects.scaleClusterWorkload("proj_123", {
    replicas: 4,
    expectedDeploymentId: live.activeDeploymentId,
    expectedUpdatedAt: live.updatedAt,
  });
  console.log(scale.deploymentId); // Follow the normal deployment progress stream.
}

Replica changes are configuration releases. They reuse the active image, wait for ready pods and use the existing update/rollback history. Allow capacity for the old and new releases together. status and observedAt describe the last observation; saved config describes future intent. OpenShip Edge currently enters through the first cluster control server. Automatic gateway failover and policy-driven autoscaling are not implemented.

Share application files

Enable shared storage on the server cluster first. Use createClusterVolume to create a project volume, then add its name and mount path to the cluster configuration and deploy. Each release retains its reviewed volume identities. listClusterVolumes and streamClusterVolumeEvents report attachment health, independent copies, expansion and backups.

Shared-file backups use the cluster's configured external destination. Schedules can run hourly or daily. listClusterVolumeBackups includes archives whose original volume was deleted; restore into a new volume and verify its contents before attaching it to the application. Disconnect and deploy before deleting a volume. External backups survive volume removal.

Add, import or recover a database

Create PostgreSQL or Redis through createClusterDatabase, then inspect progress until ready. Database instances and Redis shards scale independently of application replicas. A Redis shard change requires a verified backup and explicit review.

listClusterDatabaseImports returns eligible backups of this project's existing PostgreSQL or Redis services. Use a selected backup with importFrom, or recover a managed database archive with restoreFrom. A PostgreSQL 17-to-18 upgrade uses copyFrom to build a separate database. Each path preserves the source. You can prepare imported databases before changing the app's cluster target; it must later select the same cluster.

Verify the recovered data, then explicitly save or replace the managed application connection with both databases' current sequences. Redeploy to use it. For a final cutover, pause source writes and take a fresh recovery point; writes after capture are not copied automatically. See the database workflow.

Update a project

The update body is a partial of the create body — send only the fields you want to change. Every field above is accepted and optional here.

const result = await ship.projects.update("proj_123", {
  buildCommand: "pnpm build",
  gitBranch: "release",
});
console.log(result);

curl -X PATCH "$OPENSHIP_URL/api/projects/proj_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"buildCommand":"pnpm build","gitBranch":"release"}'

Link a git repo

Attach (or re-point) a GitHub repository to an existing project. When branch is omitted, the repo's default branch is used.

const result = await ship.projects.linkRepo("proj_123", {
  owner: "acme",
  repo: "site",
  branch: "main",
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/projects/proj_123/git/link" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"owner":"acme","repo":"site","branch":"main"}'

Related git routes: POST /api/projects/:id/branch (change the deploy branch), POST /api/projects/:id/auto-deploy (toggle deploy-on-push), GET /api/projects/:id/branches, and GET /api/projects/:id/commit-status (is the deployed commit behind remote HEAD?). See the GitHub API for connecting the GitHub App itself.

Connect a custom domain

A shortcut that adds a domain to the project and marks it primary in one call. For the full domain lifecycle (DNS preview, verification, SSL), use the Domains API.

const result = await ship.projects.connectDomain("proj_123", {
  domain: "app.example.com",
});
console.log(result);

curl -X POST "$OPENSHIP_URL/api/projects/proj_123/connect" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"app.example.com"}'

Environment variables

GET   /api/projects/:id/env
PATCH /api/projects/:id/env

GET lists variables for the project with secret values masked. Writes go through a merge: only the keys you name are touched — upserts are inserted/updated, deletes are removed, and every other variable (including untouched masked secrets) is left intact.

const result = await ship.projects.mergeEnvVars("proj_123", {
  environment: "production",
  upserts: [
    {
      key: "DATABASE_URL",
      value: "postgres://…",
      isSecret: true,
    },
  ],
  deletes: ["OLD_FLAG"],
});
console.log(result);

curl -X PATCH "$OPENSHIP_URL/api/projects/proj_123/env" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "upserts": [{"key":"DATABASE_URL","value":"postgres://…","isSecret":true}],
    "deletes": ["OLD_FLAG"]
  }'

Resources

GET   /api/projects/:id/resources
PATCH /api/projects/:id/resources
POST  /api/projects/:id/resources

Read or update the CPU/RAM/disk allotment (separately for production and build), sleep behavior, and listen port. POST is an alias of PATCH. All fields are optional; send only what you want to change.

const result = await ship.projects.updateResources("proj_123", {
  production: {
    cpuCores: 1,
    memoryMb: 1024,
  },
  sleepMode: "always_on",
});
console.log(result);

curl -X PATCH "$OPENSHIP_URL/api/projects/proj_123/resources" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"production":{"cpuCores":1,"memoryMb":1024},"sleepMode":"always_on"}'

Sleep mode also has its own shortcut route: POST /api/projects/:id/sleep-mode.

Create an environment

POST /api/projects/:id/environments

Folder uploads

See Source files to upload a folder or deploy generated code.

Transfer to / from cloud

POST /api/projects/:id/transfer/to-cloud         † self-hosted only
POST /api/projects/:id/transfer/to-self-hosted   † self-hosted only

Promote a local project to Openship Cloud, or pull a cloud project back to this instance. These are meaningless on the SaaS (it is the cloud) and return 404 there. Both require project:admin.

const result = await ship.projects.transferToCloud("proj_123");
console.log(result);

curl -X POST "$OPENSHIP_URL/api/projects/proj_123/transfer/to-cloud" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN"

Retry routing with logs

Routing repair can include SSH and certificate issuance. Use the streaming operation to follow its progress without the ordinary request timeout:

for await (const event of ship.projects.retryRoutingStream("proj_123")) {
  console.log(event.event, event.data);
}

The HTTP equivalent is POST /api/projects/:id/routing/retry/stream with an SSE response. Log events contain the server's messages. A terminal complete event carries status: "completed" or status: "failed"; a disconnected stream alone does not establish success. Cancelling the stream stops log delivery while an accepted repair continues under the project's runtime lock.

The first session event includes a sessionId. Pass it to ship.projects.retryRoutingStream(id, { sessionId }), or use GET /api/projects/:id/routing/retry/stream?sessionId=..., to replay retained logs and follow the same repair. Reconnecting requires project:read and never starts another repair. The project info response includes the latest session as project.routingRetry so the dashboard can restore the log after a refresh. Completed logs are retained in the running engine for up to 30 minutes, subject to the retention limit; they do not survive an API restart.

Starting requires project:write. Concurrent start requests join the project's active repair. For an uncertain start response, reuse options.idempotencyKey (the idempotencyKey query parameter over HTTP) so a repeated request also rejoins a completed, retained session. Use a new key only when intentionally starting another repair.

Errors

Operations

Lifecycle

Source and deployment

Cluster scaling

Cluster databases

Shared files

Environments and settings

Routing and monitoring

Connections, storage, and apps

Cloud transfer

HTTP endpoints