Project setup

How Computalot sets up your project. For the basic project lifecycle, see Projects.

How it works

Projects run as sandboxed OCI containers. Your tarball includes a Dockerfile and computalot.project.json manifest. On push, Computalot durably stages the tarball and build record. It then returns 202 with a status URL while the image builds. The previous revision stays active until the new image is published. Jobs then trigger runtime preparation on demand. /init is optional. Use it to prepare currently available workers before a burst.

See Project Manifest for the full manifest schema.

Init flow

When you call POST /api/v1/projects/:name/init:

1. Computalot prepares the OCI container image on eligible workers
2. Declarative manifest validation checks run (executables and files)
3. The active revision becomes ready_for_jobs after preparation succeeds

Init is asynchronous. You do not need to wait for it before you submit jobs. To see whether the active revision is only published or already warm, use GET /api/v1/projects/:name/status.

can_accept_new_jobs: true means that the latest project revision is published. You can submit jobs now. ready_for_jobs: true means that Computalot finished platform-side runtime preparation for the current content hash. Neither field proves that your application imports or credentials work. Use manifest validation checks, and run one smoke job after changes.

Project readiness is per worker, not a single global switch. One replica can already be warm while another still initializes or failed. Use GET /api/v1/projects/:name/status/details for the detailed readiness breakdown (replica counts and sanitized diagnostics — machine identities stay internal).

Project init is free. It requires at least $5 of available balance. If init returns 402 Payment Required, fund the account and retry.

Minimal project structure

my-project/
├── Dockerfile
├── computalot.project.json
└── job.py

Dockerfile

Install your dependencies and configure the runtime in your Dockerfile:

FROM python:3.11-slim
WORKDIR /workspace
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .

computalot.project.json

Minimal manifest:

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

See Project Manifest for the full schema including validation, cache mounts, data sources, and artifacts.

Worker environment

Tasks run inside your container image. Include all dependencies in your Dockerfile. GPU-capable workers have NVIDIA drivers and CUDA available.

Runtime preparation and declarative validation can run again on reused workers. Build dependencies and generated runtime assets into the image. A prepared revision is then reproducible.

User-upload projects cannot declare host-style runtime.init.commands, runtime.services, or validation.commands. Use the Dockerfile for installs and build steps, validation.executables / validation.files for preflight checks, and the task entrypoint for processes that must run inside the gVisor sandbox.

Keep the image lean. Install runtime dependencies only (skip dev extras such as uv sync --extra dev unless tasks need them). If your GPU training stack is much larger than your screening and eval jobs, give those lighter jobs their own smaller CPU runtime. Smaller images place faster.

Budget disk generously. For sandboxed OCI jobs, worker disk usage is usually much larger than your source tarball. Count the built runtime, downloaded weights and data, writable caches, checkpoints, temp files, and the per-task sandbox copy.

Updating code

Push a new tarball. The new revision is published immediately. Use invalidate only to discard old prepared runtimes. Use init only to prepare currently available workers before a burst:

tar czf code.tar.gz Dockerfile computalot.project.json job.py
curl -sS "$BASE_URL/api/v1/projects/my-project/push" \
  -X POST -H "Authorization: Bearer $TOKEN" --data-binary @code.tar.gz
curl -sS "$BASE_URL/api/v1/projects/my-project/invalidate" \
  -X POST -H "Authorization: Bearer $TOKEN"
curl -sS "$BASE_URL/api/v1/projects/my-project/init" \
  -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{}'