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

Computalot is a distributed compute platform. Submit typed jobs, get structured JSON results. GPU and CPU capacity, metered by the task-second at market rates.

Open access. Any wallet can authenticate (challenge → sign → verify) and fund the account with USDC via x402 or MPP — no approval needed. API keys are issued on request via the waitlist at /. Discovery endpoints are public.

Base URL: https://computalot.com

• https://computalot.com/skill.md — install this skill to get started
• 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-15)

• Open wallet access: any wallet can authenticate (challenge → sign → verify) and fund the account — no allowlist entry required. API keys remain issued on request via the waitlist.
• MPP (Machine Payments Protocol, mpp.dev) is accepted alongside x402: quote 402s carry a WWW-Authenticate: Payment challenge (EVM charge; decoded copy in the body’s mpp block), quotes settle with Authorization: Payment <base64url credential> (EIP-3009), and success 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 served at /openapi.json; a pricing page with indicative market ranges lives at /docs/pricing; public endpoints answer HEAD like GET.
• Job submission accepts preset (resource preset name from GET /api/v1/presets; explicit requirements win) and client_ref (≤255-byte grouping label, searchable via /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. Local/R2 content hashes are deduplicated within the account; quota exhaustion returns 507 artifact_quota_exceeded.
• Artifact owners can delete once every referencing job is terminal. Active jobs return 409 artifact_in_use; accepted deletion releases account quota immediately, and GET /api/v1/artifacts reports authoritative used/remaining quota.
• Worker exit status is terminal truth. result_quality / result_warnings are reserved as null / [], and non-empty result_schema returns 422.
• max_retries accepts 0 through 10, depends_on accepts at most 50 job IDs, and job/artifact admission is validated before work or billing holds are created.
• User-upload projects require OCI + gVisor and cannot declare runtime.init.commands, runtime.services, or validation.commands.

Feedback — Report Bugs & Request Features

This is beta software. Please 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"}'

Types: bug, feature_request, provisioning, job_type_request. No auth required.

The Model

Projects carry your code (tarball with Dockerfile + computalot.project.json). Jobs run against a project as one of four typed shapes — structured_runner, sweep, map_reduce, benchmark — and return structured JSON results.

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

No auth required: /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 operator-gated: local requests, admin auth, or the dedicated metrics token only.

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 is active revision truth, not machine-count truth
• After POST /api/v1/projects/:name/push, a successful response can include tarball_diff
• Use GET /api/v1/projects/:name/status for top-level readiness and GET /api/v1/projects/:name/status/details for diagnostics + recovery guidance
• can_accept_new_jobs: true means the latest revision is published and can be submitted immediately
• ready_for_jobs can stay false after push while the first job or an optional /init prepares 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 / validation.files and a smoke job instead.

Job Types

Default to structured_runner unless another type clearly fits.

Runner Protocol

Your script receives input and writes output via environment variables:

• $COMPUTALOT_TASK_PAYLOAD — path to JSON input file. Read this.
• $COMPUTALOT_TASK_RESULT — path to write JSON output. Computalot reads this after exit.
• $COMPUTALOT_ARTIFACT_DIR — directory for output files. Auto-uploaded on completion.
• $COMPUTALOT_TASK_SCRATCH_DIR — private per-task temp space.
• $COMPUTALOT_TASK_CACHE_DIR — per-project build cache shared by concurrent tasks on the node. Never stage builds under a deterministic temp name: build in a per-task unique temp dir, then atomically os.replace(temp, final) and tolerate the final path already existing. flock is supported.
• Exit 0 = success. Non-zero = failure. Exit 137 (OOM/SIGKILL) is treated as an infra failure: the task requeues automatically without consuming max_retries — repeated 137s mean the task needs more memory.
• 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

Split one job into parallel tasks:

Do not send a top-level tasks array. The public API rejects it so per-task commands and routing cannot bypass 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 are mutually exclusive. Add batch_size to group tiny items into one task. Merge strategies: collect (default), keyed, weighted_avg.

Choose exactly one fan-out shape per submit. Mixed shapes are rejected with 422.

Common Job Fields

Long ML jobs: use _artifacts.download with concrete account-accessible artifact IDs for one-off large inputs, manifest data_sources for immutable remote weights/datasets, and manifest cache_mounts for writable runtime caches. Resolve upstream IDs from GET /api/v1/results/:job_id before submitting downstream work. Submission verifies ownership and records retained artifact references atomically before creating work or placing a billing hold. hf-mount only applies to manifest-declared Hugging Face data_sources, not arbitrary 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

Process exit is terminal truth: exit 0 completes and non-zero fails. result_quality/result_warnings are reserved (null/[]), and non-empty result_schema returns 422.

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

Debug failures: GET /api/v1/jobs/:id for error and recommended_action, GET /api/v1/jobs/:id/tasks for per-task diagnostics.

During retries, GET /api/v1/jobs/:id/tasks and GET /api/v1/jobs/:id/output preserve the most recent failed attempt’s diagnostics until the current attempt emits its own output.

Public task/result payloads keep the submitted task contract visible, but redact provider IDs, raw runtime paths, and image refs/digests.

Billing

• Pricing model: metered market-rate compute per task-second. The submit response’s summary.billing_estimate is the authoritative per-job quote; indicative class ranges live at /docs/pricing. Queue time is never charged; timeout_s caps each task’s runtime cost.
• Check balance: GET /api/v1/account/balance
• Jobs reserve a bounded hold for the initial attempt plus requested max_retries, then settle to actual usage on terminal completion; infrastructure requeues do not consume the configured retry budget
• Project init is free but requires $5 available balance
• Fund via x402: POST /api/v1/account/quotes/topup → pay → POST /api/v1/account/quotes/:id/pay/x402 (base64 payment payload in PAYMENT-SIGNATURE, bearer auth)
• Fund via MPP (mpp.dev): the same 402 carries a WWW-Authenticate: Payment challenge (method evm, intent charge; decoded copy in the body’s mpp block). Sign the same EIP-3009 authorization, wrap it as an MPP credential, and POST the pay URL (or /topup) with Authorization: Payment <base64url credential> — no bearer token. Success returns a Payment-Receipt header.
• If a request returns 402, fund the account and retry the same request

Billing truth lives on GET /api/v1/account/balance, GET /api/v1/account/holds, and GET /api/v1/account/ledger.

Use GET /api/v1/account/quotes to inspect open top-up and shortfall quotes before retrying blocked work, and GET /api/v1/account/quotes/:quote_id to fetch one quote’s payment requirements (x402 attrs.x402_payment_required plus the decoded MPP challenge in mpp).

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

Artifact Lifecycle

• Relay upload: POST /api/v1/artifacts, raw body, max 2 GiB.
• External object: POST /api/v1/artifacts/external.
• Direct/multipart object-store endpoints return 410 Gone.
• Default retained-byte quota: 100 GiB per account; local/R2 content is deduplicated by account + content hash.
• Quota exhaustion: HTTP 507, code artifact_quota_exceeded.
• Deletion: 409 artifact_in_use only while a producing job or job input belongs to a non-terminal job. Terminal references are reported but do not block owner deletion.
• Accepted deletion releases account quota and hides metadata immediately; namespaced backing data is removed after the default 24-hour grace.

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)