Skip to Content
ProjectsProject Manifest

Project manifest

computalot.project.json is the runtime contract for projects. Put it at the tarball root next to your Dockerfile and code.

Most projects only ever need the minimal manifest below. Reach for the optional fields when you have a concrete problem: cache_mounts when downloads repeat across tasks, data_sources for large immutable inputs like model weights, requirements for project-wide hardware defaults, and artifacts to declare expected outputs.

The smallest valid manifest is:

{
  "version": 1,
  "runtime": {
    "kind": "oci",
    "sandbox": "gvisor",
    "workdir": "/workspace"
  },
  "entrypoint": {
    "command": ["python", "job.py"]
  }
}

Computalot builds a container image from your tarball and runs tasks in a sandboxed environment.

File location

  • Tarball root: computalot.project.json

Required fields

version

  • Positive integer, currently 1

runtime

  • kind: oci
  • workdir: absolute in-container working directory (e.g. /workspace)
  • sandbox: gvisor (required for public execution)

entrypoint

  • command: non-empty array of strings

Common optional fields

build

Configure how Computalot builds your container image.

{
  "build": {
    "dockerfile": "Dockerfile",
    "context": ".",
    "target": "runtime",
    "args": { "PYTHON_VERSION": "3.11" }
  }
}

If build.dockerfile is omitted, Computalot defaults to a root Dockerfile. If that file is missing, the push fails.

validation

Declarative executable and file checks that can run during runtime preparation.

{
  "validation": {
    "executables": ["python"],
    "files": ["job.py"]
  }
}

User-upload projects cannot declare validation.commands. Put dependency installation and build-time checks in the Dockerfile; use validation.executables and validation.files for declarative runtime checks.

Restricted fields (rejected on push)

User-upload projects cannot declare runtime.init.commands, runtime.services, or validation.commands — host-command surfaces are reserved for the platform, and a push containing any of them is rejected.

Everything those fields might have done belongs in the image or the entrypoint instead: build dependencies and generated assets into the OCI image, and if a task needs a helper process, start and supervise it from your entrypoint inside the sandbox — the entrypoint’s final exit code still decides task success.

requirements

Project-level placement defaults merged into job routing.

{
  "requirements": {
    "profile": "gpu",
    "gpu_count": 1,
    "gpu_memory_mb": 24576,
    "cpu": 8,
    "memory_mb": 16384,
    "storage_gb": 40
  }
}

storage_gb should reflect real worker disk headroom, not only input data size. For sandboxed OCI workloads that usually means: runtime/image footprint, per-task sandbox copy overhead, writable caches, temp files, checkpoints, and any runtime downloads.

cache_mounts

Managed writable caches mounted into the runtime.

{
  "cache_mounts": [
    {
      "name": "hf-cache",
      "scope": "project_digest",
      "path": "/cache/huggingface",
      "class": "model"
    },
    {
      "name": "pip-cache",
      "scope": "project_digest",
      "path": "/cache/pip",
      "class": "pip"
    }
  ]
}

Fields: name, scope (currently project_digest), path (absolute), max_bytes, class (pip, cargo, model, data), seed_from_image (boolean).

Cache mounts persist per worker and per project version. Use COMPUTALOT_CACHE_<NAME>_DIR env vars when accessing caches outside runtime.workdir.

Use cache mounts for writable runtime state that your code populates at startup or during the task:

  • package caches such as pip
  • Hugging Face runtime caches such as HF_HOME or TRANSFORMERS_CACHE
  • model/data caches created by your own code at runtime

A cache mount replaces the image contents at that path. Use seed_from_image: true if you need the image’s baked files to survive the first mount.

data_sources

Declarative external inputs fetched before task launch.

{
  "data_sources": [
    {
      "name": "weights",
      "source": "huggingface",
      "uri": "hf://org/model-name",
      "delivery": "mount",
      "path": "/workspace/models/model-name",
      "cache": "hf-cache",
      "required": true
    }
  ]
}

Use data sources for immutable inputs that Computalot should prepare before your code starts, such as model weights or reference datasets.

For Hugging Face, delivery: "mount" uses the worker-managed hf-mount path. That only applies to Hugging Face sources declared here in the manifest. If your runner script downloads from Hugging Face on its own, hf-mount is not being used automatically; declare the source here or add a writable Hugging Face cache mount for those runtime downloads.

Long ML jobs

For long-running ML and evaluation workloads:

  • use data_sources for immutable large inputs such as model weights and reference datasets
  • use cache_mounts for writable runtime caches such as HF_HOME, TRANSFORMERS_CACHE, or package caches
  • declare realistic requirements.storage_gb; PyTorch/CUDA/Hugging Face stacks often need tens of GB of free worker disk before checkpoints or datasets
  • enable checkpointing.resume_from_latest on jobs and emit durable checkpoints throughout execution
  • write checkpoints and outputs to $COMPUTALOT_ARTIFACT_DIR, not repo-relative folders
  • do not assume runtime-downloaded models are reused unless you declared a matching cache mount or manifest data source
  • keep runtime and dev environments separate; avoid installing notebook/lint/test extras onto production workers unless the task actually needs them

artifacts

Named outputs and upload declarations.

{
  "artifacts": {
    "upload": [
      {"name": "report", "path": "report.json", "required": true}
    ],
    "outputs": [
      {"name": "checkpoint", "path": "ckpt/latest.pt", "type": "checkpoint"}
    ]
  }
}

Relative paths are resolved under $COMPUTALOT_ARTIFACT_DIR.

Filesystem rules

  • The container filesystem is read-only during task execution
  • Use $COMPUTALOT_TASK_SCRATCH_DIR or $TMPDIR for temporary files
  • Use $COMPUTALOT_ARTIFACT_DIR for checkpoints and outputs
  • Managed cache mounts are writable at their declared paths
  • Do not assume repo-relative paths like checkpoints/ are writable

Path rules

  • runtime.workdir and cache mount path values must be absolute
  • build.dockerfile, build.context, and command cwd values must be relative
  • Push-time validation rejects missing files, directories, cache names, or invalid paths

Common push errors

  • version must be a positive integer
  • runtime.kind must be tarball or oci
  • runtime.workdir must be an absolute path
  • entrypoint.command must be a non-empty string array
  • build.dockerfile does not exist in the tarball
  • build.context does not resolve to a directory
Last updated on
SetupJobs