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 first:

const session = await ship.sources.open({ name: "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 '{"name":"my-site"}'

The response includes sessionId, expiresAt, and upload instructions:

Send a gzip-compressed tar archive to the returned URL. Use the supplied instructions because the upload destination can differ by deployment mode. The self-hosted relay is POST /api/projects/folder/upload/:sessionId and limits uploads to 300 MB.

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

const staged = await ship.sources.stage({
  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