Synced from docs/llm-agent-reference-compact.md in the Computalot monorepo.

Computalot is a distributed compute platform. You submit typed jobs, and you get structured JSON results. The platform supplies GPU and CPU capacity. Computalot meters each task by the second, at the market rate plus a 35% service markup. The minimum billed time per task-attempt is 60 seconds.

Open access. Any wallet can authenticate (challenge → sign → verify) and fund the account with USDC through x402 or MPP. No approval is necessary. Computalot issues API keys on request through the waitlist at /. The discovery endpoints are public.

Base URL: https://computalot.com

• https://computalot.com/skill.md — agent skill file. Install this first.
• https://computalot.com/llms.txt — this compact reference
• https://computalot.com/llms-full.txt — full reference with tutorials
• https://computalot.com/api/v1/docs — machine-readable JSON index
• https://computalot.com/openapi.json — OpenAPI 3.1 schema of the public API
• https://computalot.com/docs — human docs
• https://computalot.com/docs/pricing — indicative rates and worked cost examples

Recent Contract Changes (2026-07-22)

• Controller-side OCI builds for projects are durable and asynchronous. POST /push returns 202 with push_ref and status_url. The previous revision stays active during the build. The build status shows published or failed with bounded diagnostics.
• Open wallet access: any wallet can authenticate (challenge → sign → verify) and fund the account. An allowlist entry is not necessary. Computalot continues to issue API keys on request through the waitlist.
• Computalot accepts MPP (Machine Payments Protocol, mpp.dev) and x402. Quote 402 responses carry a WWW-Authenticate: Payment challenge (EVM charge, with a decoded copy in the mpp block of the body). To settle a quote, send Authorization: Payment <base64url credential> (EIP-3009). A successful payment returns a Payment-Receipt header.
• GET /api/v1/account/quotes/:quote_id returns one quote with its x402 payment requirements. The OpenAPI 3.1 schema is at /openapi.json. A pricing page with indicative market ranges is at /docs/pricing. Public endpoints answer HEAD like GET.
• Job submission accepts preset (a resource preset name from GET /api/v1/presets, where explicit requirements win). It also accepts client_ref (a grouping label of 255 bytes or less, searchable with /api/v1/results?client_ref=...).
• Artifact uploads use the authenticated controller relay (up to 2 GiB) or external URL registration. Direct and multipart object-store upload endpoints return 410 Gone.
• The default retained-byte quota is 100 GiB per account. Computalot deduplicates local and R2 content hashes within the account. When the quota is full, the API returns 507 artifact_quota_exceeded.
• Artifact owners can delete an artifact when every referencing job is terminal. Active jobs cause 409 artifact_in_use. An accepted deletion releases account quota immediately. GET /api/v1/artifacts reports the authoritative used and remaining quota.
• Worker exit status is the terminal truth. result_quality and result_warnings are reserved as null and []. The API accepts and ignores legacy object-shaped result_schema metadata. Non-object result_schema values return 422.
• max_retries accepts 0 through 10. depends_on accepts a maximum of 50 job IDs. The API validates job and artifact admission before it creates work or billing holds.
• User-upload projects require OCI + gVisor. They cannot declare runtime.init.commands, runtime.services, or validation.commands.

Feedback — Report Bugs & Request Features

This is beta software. Report bugs, request features, and share ideas:

curl -sS -X POST https://computalot.com/api/v1/feedback \
  -H "Content-Type: application/json" \
  -d '{"type": "bug", "title": "Brief summary", "description": "What happened, what you expected"}'

The types are bug, feature_request, provisioning, and job_type_request. This endpoint does not need auth.

The Model

Projects carry your code as a tarball with a Dockerfile and computalot.project.json. Jobs run against a project and return structured JSON results. A job has one of four types: structured_runner, sweep, map_reduce, or benchmark.

Auth

# API key (issued on request via the waitlist)
export TOKEN="flk_..."
 
# Wallet session (any wallet)
# 1. POST /api/v1/auth/wallet/challenge
# 2. Sign challenge.message with your wallet
# 3. POST /api/v1/auth/wallet/verify → returns fls_... token
 
# All protected endpoints:
Authorization: Bearer $TOKEN

These endpoints do not need auth: /health, /docs, /llms.txt, /llms-full.txt, /api/v1/docs/*, POST /api/v1/feedback, POST /api/v1/auth/wallet/challenge, POST /api/v1/auth/wallet/verify.

GET /metrics is for operators only. It accepts local requests, admin auth, or the dedicated metrics token.

Project Quickstart

# 1. Create project
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://computalot.com/api/v1/projects \
  -d '{"name": "my-proj", "remote_dir": "/root/projects/my-proj"}'
 
# 2. Upload tarball (raw binary, NOT multipart)
tar czf code.tar.gz Dockerfile computalot.project.json script.py
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  --data-binary @code.tar.gz \
  https://computalot.com/api/v1/projects/my-proj/push
 
# 3. Submit job immediately after push
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://computalot.com/api/v1/jobs \
  -d '{"type": "structured_runner", "runner_command": ["python3", "script.py"], "payload": {"test": true}, "project": "my-proj", "timeout_s": 120}'
 
# 4. Optional: prepare currently available workers ahead of time
curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  https://computalot.com/api/v1/projects/my-proj/init
 
# 5. Inspect published vs warm state
curl -sS -H "Authorization: Bearer $TOKEN" \
  https://computalot.com/api/v1/projects/my-proj/status
 
# 6. Results
curl -sS -H "Authorization: Bearer $TOKEN" https://computalot.com/api/v1/results/<job_id>

Project Lifecycle & Readiness

• Readiness comes from the active revision, not from the machine count.
• Controller-side OCI builds return 202 from POST /api/v1/projects/:name/push with push_ref and status_url. Poll the status URL until it shows published or failed. The prior revision stays active during the build. On failure, read error and the bounded log_tail.
• Push responses and build status can include tarball_diff.
• Use GET /api/v1/projects/:name/status for top-level readiness. Use GET /api/v1/projects/:name/status/details for diagnostics and recovery guidance.
• can_accept_new_jobs: true means that the latest revision is published. You can submit jobs immediately.
• ready_for_jobs can stay false after a push while the first job or an optional /init prepares the runtime.
• Install dependencies and build assets in the Dockerfile. User uploads cannot declare host-style runtime.init.commands, runtime.services, or validation.commands. Use declarative validation.executables and validation.files, and run a smoke job.

Job Types

When no other type is a clear match, use structured_runner.

Runner Protocol

Your script receives input and writes output through environment variables:

• $COMPUTALOT_TASK_PAYLOAD — the path to the JSON input file. Read this file.
• $COMPUTALOT_TASK_RESULT — the path for the JSON output file. Computalot reads this file after the process exits.
• $COMPUTALOT_ARTIFACT_DIR — the directory for output files. Computalot uploads these files when the task completes.
• $COMPUTALOT_TASK_SCRATCH_DIR — a private temporary directory for each task.
• $COMPUTALOT_TASK_CACHE_DIR — the build cache for the project. Concurrent tasks on the node share this cache. Do not stage builds at a fixed temporary path. Build in a unique temporary directory for each task. Then move the result with one atomic os.replace(temp, final). Your code must accept that the final path can already exist. The cache supports flock.
• Exit code 0 means success. A non-zero exit code means failure. Exit code 137 (OOM or SIGKILL) counts as an infrastructure failure. The task requeues automatically, and the requeue does not consume max_retries. Repeated 137 exits mean that the task needs more memory.
• If the machine is broken, the runner can write "failure_class": "infra" in the result JSON and exit non-zero. The requeue is then free of the retry budget, at most 3 times for each task.
• To report progress, print COMPUTALOT_PROGRESS:{"epoch":5,"loss":0.23} to stdout.

import json, os
payload = json.load(open(os.environ['COMPUTALOT_TASK_PAYLOAD']))
result = {'score': 0.95, 'model': payload['model']}
json.dump(result, open(os.environ['COMPUTALOT_TASK_RESULT'], 'w'))

Fan-Out

Fan-out splits one job into parallel tasks.

Do not send a top-level tasks array. The public API rejects it. This rule prevents per-task commands and routing from bypassing submission validation. Use one of the supported fan-out shapes below.

By list values — one task per item:

{"fan_out": {"by": "models"}, "payload": {"models": ["gpt4", "claude", "llama"]}}

By explicit items — custom payload per task:

{"fan_out": {"items": [{"params": [0.1, 0.5]}, {"params": [0.2, 0.4]}]}}

By chunks — split a numeric range:

{"fan_out": {"chunks": 20, "range_field": "total_seeds", "total": 10000}}

These three shapes are mutually exclusive. To group small items into one task, add batch_size. The merge strategies are collect (the default), keyed, and weighted_avg.

Select exactly one fan-out shape for each submit. The API rejects mixed shapes with 422.

Common Job Fields

For long ML jobs:

• For one-off large inputs, use _artifacts.download with concrete account-accessible artifact IDs.
• For immutable remote weights and datasets, use manifest data_sources.
• For writable runtime caches, use manifest cache_mounts.

Before you submit downstream work, resolve upstream artifact IDs from GET /api/v1/results/:job_id. Submission validates ownership and records retained artifact references atomically, before Computalot creates work or places a billing hold. hf-mount applies only to Hugging Face data_sources declared in the manifest, not to runner-side downloads.

Results & Streaming

# Terminal results
curl -sS -H "Authorization: Bearer $TOKEN" https://computalot.com/api/v1/results/<job_id>
 
# Per-task details and progress
curl -sS -H "Authorization: Bearer $TOKEN" https://computalot.com/api/v1/jobs/<job_id>/tasks
 
# Stdout/stderr
curl -sS -H "Authorization: Bearer $TOKEN" https://computalot.com/api/v1/jobs/<job_id>/output
 
# SSE stream (one job)
curl -sS -N -H "Authorization: Bearer $TOKEN" https://computalot.com/api/v1/jobs/<job_id>/stream
 
# SSE stream (multiple jobs)
curl -sS -N -H "Authorization: Bearer $TOKEN" "https://computalot.com/api/v1/jobs/watch?ids=<id1>,<id2>"

Job lifecycle: planning → queued → running → completed | partial | failed | cancelled

The process exit code is the terminal truth. Exit 0 completes the task. A non-zero exit fails it. result_quality and result_warnings are reserved (null and []). The API accepts and ignores legacy object-shaped result_schema metadata. Non-object values return 422.

completed means that every task succeeded. partial means that at least one task succeeded and at least one failed or was cancelled. failed means that no task succeeded and execution ended in failure.

To debug a failure, read error and recommended_action from GET /api/v1/jobs/:id. Then read per-task diagnostics from GET /api/v1/jobs/:id/tasks.

During retries, GET /api/v1/jobs/:id/tasks and GET /api/v1/jobs/:id/output keep the diagnostics of the most recent failed attempt. They keep them until the current attempt emits its own output.

Each task carries an attempts array: attempt number, status, timestamps, duration_s, terminal_kind, the retry decision, a stable pseudonymous worker handle (wkr_...), and the worker resource_profile (cpu_model, cpu_clock_ghz, single_core_score, cpu_count, memory_total_mb, gpu_count).

Public task and result payloads keep the submitted task contract visible. They redact node names, provider IDs, raw runtime paths, and image refs and digests. Worker identity appears only as the pseudonymous handle.

Billing

• Computalot meters each task per second at the market rate plus a 35% service markup. The minimum billed time per task-attempt is 60 seconds. The summary.billing_estimate field in the submit response is the authoritative quote for the job. Indicative class ranges are at /docs/pricing. Computalot never charges for queue time. timeout_s caps the runtime cost of each task.
• Read your balance with GET /api/v1/account/balance.
• A job reserves a bounded hold for the initial attempt plus the requested max_retries. The hold settles to actual usage when the job is terminal. Infrastructure requeues do not consume the retry budget.
• Project init is free. It requires an available balance of $5.
• To fund with x402: create a quote with POST /api/v1/account/quotes/topup. Then settle it with POST /api/v1/account/quotes/:id/pay/x402. Send the base64 payment payload in the PAYMENT-SIGNATURE header with bearer auth.
• To fund with MPP (mpp.dev): the same 402 carries a WWW-Authenticate: Payment challenge (method evm, intent charge, decoded copy in the mpp block of the body). Sign the same EIP-3009 authorization and wrap it as an MPP credential. Then POST the pay URL (or /topup) with Authorization: Payment <base64url credential> and no bearer token. A successful payment returns a Payment-Receipt header.
• If a request returns 402, fund the account. Then retry the same request.

The billing truth is on GET /api/v1/account/balance, GET /api/v1/account/holds, and GET /api/v1/account/ledger.

Before you retry blocked work, inspect open top-up and shortfall quotes with GET /api/v1/account/quotes. To fetch one quote with its payment requirements, use GET /api/v1/account/quotes/:quote_id (x402 attrs.x402_payment_required plus the decoded MPP challenge in mpp).

If project init or a job submit returns a shortfall quote, fund the account. Then retry POST /api/v1/projects/:name/init or send the same submit to POST /api/v1/jobs again.

Artifact Lifecycle

• Relay upload: POST /api/v1/artifacts with a raw body, maximum 2 GiB.
• External object: POST /api/v1/artifacts/external.
• Direct and multipart object-store endpoints return 410 Gone.
• The default retained-byte quota is 100 GiB per account. Computalot deduplicates local and R2 content by account and content hash.
• When the quota is full, the API returns HTTP 507 with code artifact_quota_exceeded.
• Deletion returns 409 artifact_in_use only while a non-terminal job produces or consumes the artifact. The API reports terminal references, but they do not block owner deletion.
• An accepted deletion releases account quota and hides metadata immediately. Computalot removes the namespaced backing data after the default 24-hour grace period.

Python SDK & CLI

python3 -m pip install --user --break-system-packages \
  https://computalot.com/docs/downloads/computalot-0.2.1-py3-none-any.whl
export PATH="$HOME/.local/bin:$PATH"

from computalot import ComputalotClient
client = ComputalotClient(controller_url="https://computalot.com", token="YOUR_TOKEN")
docs = client.docs_index()
jobs = client.list_jobs(limit=5)
print(docs["status"])
print(len(jobs.get("jobs", [])))

computalot docs --llm
computalot jobs --limit 5
computalot job <job_id>

Endpoint Reference

Jobs

Billing

Results & Artifacts

Projects

Public (no auth)

Ops (operator-facing)