Source files

Source sessions hold uploaded application files until deployment. The SDK accepts a directory or an in-memory file map. REST accepts a compressed archive through a short-lived upload session.

Deploy generated files

The SDK's deploy() helper combines staging, detection, project selection, and deployment submission. Use it when your application or AI workflow produces files:

const submitted = await ship.deploy({
  name: "generated-site",
  source: {
    type: "files",
    files: { "index.html": "<h1>Hello from Openship</h1>" },
  },
});

const outcome = await ship.deployment(submitted.deployment_id).wait({ timeoutMs: 120_000 });
if (!outcome.success) throw new Error(outcome.message ?? outcome.status);

File keys are relative paths; values may be strings or Uint8Array data. Use { type: "directory", path: "/absolute/path/to/site" } for a directory. With a remote client, files are packed on the calling machine. A native directory must be inside an allowed policy.sourceRoots entry.

The result contains deployment_id, project_id, and optional configDiagnostics. Submission and readiness are separate. See deployment outcomes.

Upload a source folder

For a custom uploader, open a session bound to an existing authorized project:

const session = await ship.sources.open({ projectId: "proj_my_site" });
console.log(session.sessionId, session.upload);

curl -X POST "$OPENSHIP_URL/api/projects/folder/session" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"proj_my_site"}'

For a credential restricted to projects it creates, create the project first with gitProvider: "upload" and its destination serverId. Pass the resulting projectId to the session and subsequent projects.ensure() call. Omitting projectId opens an unbound session and requires wildcard project write permission. A desktop MCP connection can use a controller-local path instead; see deploy a desktop folder on Cloud.

The response includes sessionId, expiresAt, and upload instructions:

Send a gzip-compressed tar archive to the returned URL with the supplied headers and authentication. Cloud and self-hosted instances share POST /api/projects/folder/upload/:sessionId, with a 300 MB limit. Source files are staged privately and prepared on the selected execution server for deployment.

The SDK can perform both session creation and upload for you:

const staged = await ship.sources.stage({
  projectId: "proj_my_site",
  name: "my-site",
  source: { type: "directory", path: "/absolute/path/to/site" },
});
console.log(staged.sessionId, staged.expiresAt);

Directory packing excludes .git, node_modules, and .DS_Store. It enforces path, entry, and size limits and rejects escaping symlinks and special files. A system tar executable is not required by the SDK.

Inspect an uploaded source

const scan = await ship.sources.scan("session_123", { includeEnv: true });
console.log(scan.stack, scan.buildCommand, scan.configDiagnostics);

curl -X POST "$OPENSHIP_URL/api/projects/folder/scan/session_123" \
  -H "Authorization: Bearer $OPENSHIP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"includeEnv":true}'

Detection returns the stack, package manager, commands, output paths, service definitions, and any configuration diagnostics. Inspect errors before submitting a deployment. Environment values are masked by default. The example requests editable values in the scan response with includeEnv: true; see Reveal environment values.

To finish a custom flow, use projects.ensure() to record the chosen configuration, then deployments.buildAccess() with projectId and uploadSessionId. The shared fields are documented in projects and deployments.

Operations

Resource methods

HTTP endpoints