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 need the minimal manifest below. Use the optional fields when you have a concrete problem: cache_mounts when downloads repeat across tasks, data_sources for large immutable inputs such as 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 (for example /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. The API rejects a push that contains any of them.

Everything that those fields did belongs in the image or the entrypoint instead. Build dependencies and generated assets into the OCI image. If a task needs a helper process, start and supervise it from your entrypoint inside the sandbox. The final exit code of the entrypoint 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 must reflect real worker disk headroom, not only the input data size. For sandboxed OCI workloads, count the runtime and image footprint, the 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 you access 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. If the baked files of the image must survive the first mount, use seed_from_image: true.

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 must prepare before your code starts, such as model weights or reference datasets.

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

Long ML jobs

For long 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, and 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 through the run.
  • Write checkpoints and outputs to $COMPUTALOT_ARTIFACT_DIR, not to repo-relative folders.
  • Do not assume that runtime-downloaded models are reused, unless you declared a matching cache mount or manifest data source.
  • Keep runtime and dev environments separate. Do not install notebook, lint, or test extras onto production workers unless the task 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