Skip to main content

​
synth_ai.sdk.harbor.build_spec

HarborBuildSpec - User-facing abstraction for Harbor deployment uploads. This module defines the primary user-facing abstraction for uploading deployments to Harbor. Users define a HarborBuildSpec with their Dockerfile, context, and configuration, then use the SDK to package and upload it. Example: 
>>> from synth_ai.sdk.harbor import HarborBuildSpec, upload_harbor_deployment
>>>
>>> spec = HarborBuildSpec(
...     name="enginebench-v1",
...     dockerfile_path="./Dockerfile",
...     context_dir=".",
...     entrypoint="run_rollout --input /tmp/rollout.json --output /tmp/result.json",
...     limits={"timeout_s": 600, "cpu_cores": 4, "memory_mb": 8192},
...     metadata={"agent_type": "opencode", "benchmark": "engine-bench"},
... )
>>>
>>> deployment = upload_harbor_deployment(spec, api_key="...")
>>> print(deployment.deployment_id)

​
Classes

​
HarborLimits

Resource limits for Harbor deployment execution. Attributes:
  • timeout_s: Maximum execution time in seconds (30-3600, default: 300)
  • cpu_cores: Number of CPU cores (1-8, default: 2)
  • memory_mb: Memory limit in MB (512-32768, default: 4096)
  • disk_mb: Disk space limit in MB (1024-102400, default: 10240)
Methods:

​
to_dict

to_dict(self) -> dict[str, int]
Convert to dictionary for API requests.

​
HarborBuildSpec

User-facing spec for Harbor deployment upload. This is the primary abstraction users interact with. Define your deployment configuration here, then use upload_harbor_deployment() to package and upload. Attributes:
  • name: Deployment name (org-unique, 1-128 chars)
  • dockerfile_path: Path to Dockerfile (relative or absolute)
  • context_dir: Directory to package as build context
  • entrypoint: Command to run (default: standard rollout runner)
  • entrypoint_mode: “file” for JSON I/O or “stdio” for long-running commands
  • description: Optional human-readable description
  • env_vars: Environment variables (no LLM API keys allowed)
  • limits: Resource limits (timeout, CPU, memory, disk)
  • metadata: Additional metadata (agent_type, benchmark, version, etc.)
  • include_globs: File patterns to include (default: all files)
  • exclude_globs: File patterns to exclude (default: .git, pycache)
Methods:

​
validate_paths

validate_paths(self) -> None
Validate that Dockerfile and context directory exist. Call this before packaging to get early errors. Raises:
  • FileNotFoundError: If Dockerfile or context_dir doesn’t exist

​
get_dockerfile_content

get_dockerfile_content(self) -> str
Read and return the Dockerfile content. Returns:
  • Dockerfile content as string
Raises:
  • FileNotFoundError: If Dockerfile doesn’t exist

​
to_api_request

to_api_request(self, context_tar_base64: str) -> dict[str, Any]
Convert to Harbor API deployment creation request format. Args:
  • context_tar_base64: Base64-encoded tar.gz of the build context
Returns:
  • Dictionary suitable for POST /api/harbor/deployments

​
HarborDeploymentRef

Reference to an existing Harbor deployment. Used when configuring LocalAPIConfig to use Harbor as the execution backend. The deployment must already exist and be in READY state. Attributes:
  • deployment_id: UUID of the existing deployment
  • backend_url: Synth backend URL (default: from SYNTH_BACKEND_URL env)
  • api_key: Synth API key (default: from SYNTH_API_KEY env)
Methods:

​
rollout_url

rollout_url(self) -> str
Get the rollout endpoint URL for this deployment.

​
status_url

status_url(self) -> str
Get the status endpoint URL for this deployment.

​
HarborDeploymentResult

Result of a Harbor deployment upload operation. Returned by upload_harbor_deployment() after successful upload. Attributes:
  • deployment_id: UUID of the created deployment
  • build_id: UUID of the triggered build (if auto_build=True)
  • name: Deployment name
  • status: Current deployment status
  • snapshot_id: Daytona snapshot ID (set after build completes)
Methods:

​
to_ref

to_ref(self, backend_url: str | None = None, api_key: str | None = None) -> HarborDeploymentRef
Convert to a HarborDeploymentRef for use with LocalAPIConfig. Args:
  • backend_url: Override backend URL (default: from environment)
  • api_key: Override API key (default: from environment)
Returns:
  • HarborDeploymentRef for this deployment