Publishing Cargos

How to build, submit, and certify your own cargos on the Archipelag.io network

Publishing Cargos

This guide covers the full lifecycle of publishing a Cargo on Archipelag.io — from building a container image to getting it certified and live on the network.

Cargo Tiers

Every Cargo on Archipelag.io falls into one of three publishing tiers. The tier determines visibility, trust level, and what resources the Cargo can access on Islands.

Community Cargos

Community Cargos are the entry point for any publisher. They run in a restricted sandbox with no network or GPU access, making them safe for the network while publishers establish trust.

• Trust level 0 (Untrusted): Initial submission. Minimal sandbox — 256 MB memory, 60s timeout, 1 CPU, ~10 allowed syscalls.
• Trust level 1 (Basic): After passing security scanning and code review. Standard sandbox — 1 GB memory, 300s timeout, 2 CPUs, ~140 allowed syscalls.

Community publishers can submit up to 3 active Cargos.

Certified Cargos

Certified Cargos have been verified by the Archipelag.io review team and are signed using cosign. The signature is recorded in the Rekor transparency log, providing a public audit trail.

Certification requirements:

• Clean security scan (zero critical/high vulnerabilities)
• Verified publisher identity
• Container image signed with cosign
• At least 100 successful job completions at Community tier
• Reputation score above 0.8

Official Cargos

Official Cargos are first-party or fully audited workloads that run in the elevated sandbox tier. They can access GPU hardware and network resources on Islands. Official status is reserved for Cargos that have undergone a comprehensive audit by the Archipelag.io security team.

Official Cargos get elevated resources: 8 GB memory, 600s timeout, 4 CPUs, and GPU/Network seccomp profiles.

Submitting a Community Cargo

Test locally

Run your container with a test input to verify correctness under production-like constraints:

# Basic test
echo '{"prompt": "Hello"}' | docker run -i --rm your-cargo:latest

# Test with sandbox-equivalent resource limits
echo '{"prompt": "Hello"}' | docker run -i --rm \
  --memory=256m --cpus=1 --network=none \
  --read-only --tmpfs /tmp:size=64m \
  your-cargo:latest

Verify that:

• The container reads JSON from stdin correctly
• Each stdout line is valid JSON with a type field
• A done or error message is emitted as the final line
• The container exits with code 0 on success
• The container runs within the restricted sandbox limits (256 MB, 1 CPU, no network)

Pre-scan for vulnerabilities

Run vulnerability scanners locally before submitting to avoid rejection:

# Trivy
trivy image your-cargo:latest

# Grype
grype your-cargo:latest

Fix all critical and high severity vulnerabilities. Medium severity findings should be justified or resolved.

Push to an approved registry

Push your container image to one of the approved registries:

# Tag with a semantic version
docker tag your-cargo:latest ghcr.io/archipelag-io/your-cargo:v1.0.0

# Push
docker push ghcr.io/archipelag-io/your-cargo:v1.0.0

Approved registries:

Submit for review

Create a Cargo submission through the API or the web dashboard. Provide all required fields (see Cargo Definition Requirements below), then transition the submission from draft to pending_review.

# Example API submission
curl -X POST https://archipelag.io/api/v1/workloads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Text Processor",
    "slug": "my-text-processor",
    "description": "Processes text input and returns structured output",
    "runtime_type": "container",
    "container_image": "ghcr.io/archipelag-io/my-text-processor:v1.0.0",
    "input_schema": {"type": "object", "properties": {"text": {"type": "string"}}},
    "output_schema": {"type": "object", "properties": {"result": {"type": "string"}}},
    "price_per_job": 1,
    "required_cpu_cores": 1,
    "required_ram_mb": 256
  }'

Wait for review

Once submitted, your Cargo enters the review pipeline:

1. Automated security scan — Trivy and Grype analyze your container image
2. SBOM generation — A Software Bill of Materials is created
3. Manual review — A platform reviewer evaluates compliance, schemas, and resource requirements
4. Trust level assignment — The reviewer assigns trust level 0 or 1

You will be notified of the outcome. If rejected, the rejection reason is provided so you can fix issues and resubmit.

{% end %}

Cargo Definition Requirements

Every Cargo submission must include the following metadata:

Required Fields

Pricing (at least one required)

Resource Requirements (optional)

Optional Metadata

I/O Protocol

All Cargos communicate using a simple stdin/stdout JSON protocol, regardless of runtime type. This section is a brief overview — see the full I/O protocol reference for complete details.

Input: The Island sends a JSON object on stdin when the Cargo starts. The schema depends on the Cargo type (e.g., prompt + max_tokens for LLM Cargos).

Output: The Cargo emits JSON Lines on stdout. Each line must include a type field:

stdin (JSON) ──► Cargo ──► stdout (JSON Lines)
                            │
                            ├── {"type": "status", "message": "Loading model..."}
                            ├── {"type": "token", "content": "Hello"}
                            ├── {"type": "token", "content": " world"}
                            └── {"type": "done", "usage": {"tokens": 2}}

Output is streamed in real time through the Island software to the coordinator and then to the Consumer via WebSocket.

Security Review Process

Every Cargo submission goes through a multi-stage security review before it can run on the Archipelag.io network.

Automated Scanning

Two vulnerability scanners run automatically when a submission enters pending_review:

Scan results are categorized by severity:

A Software Bill of Materials (SBOM) is generated as part of the scan.

Manual Review

After automated scanning, a platform reviewer evaluates:

• Vulnerability scan results — all critical/high findings must be resolved
• I/O protocol compliance — input/output schemas are well-defined
• Resource requirements — requested resources are reasonable for the workload
• Description and metadata — clear, accurate, and complete
• Policy compliance — no prohibited content or functionality

Ongoing Monitoring

Published Cargos are not “set and forget”:

• Weekly rescans — automated vulnerability scanning runs on all published Cargos
• Reputation tracking — success rate, execution time, and complaint volume are monitored
• Auto-suspension — Cargos with reputation below 0.5 or success rate below 90% (after 100+ jobs) are automatically suspended
• Complaint flagging — Cargos with excessive consumer complaints are flagged for manual review

Trust Levels

Trust levels control what resources a Cargo can access when executing on Islands. Higher trust levels unlock more capabilities but require stronger verification.

Level 0 — Untrusted

The starting point for all new Cargos.

What it unlocks: Basic compute tasks that fit within tight resource constraints. Good for text processing, simple transformations, and lightweight inference.

How to get here: Submit a Cargo. All new submissions start at level 0.

Level 1 — Basic

Reviewed Cargos with a clean security scan.

What it unlocks: More memory and time for heavier compute — quantized model inference, batch text processing, data transformation pipelines.

How to get here: Pass automated security scanning (zero critical/high vulnerabilities) and manual review.

Level 2 — Verified

Signed Cargos from verified publishers.

What it unlocks: Same resource limits as level 1, but the cosign signature provides integrity guarantees. Islands verify the signature before execution, ensuring the Cargo has not been tampered with. Certified Cargos get a verified badge in the Cargo Registry.

How to get here:

1. Maintain a reputation score above 0.8 at level 1
2. Complete 100+ successful jobs
3. Verify your publisher identity
4. Sign your container image with cosign

Level 3 — Official

First-party or fully audited Cargos with elevated access.

What it unlocks: Full GPU access for large model inference (LLMs, image generation, video processing). Network access for Cargos that need to fetch models or call external APIs. This is the tier for production AI workloads.

How to get here: Official status requires a comprehensive security audit by the Archipelag.io team. This tier is currently reserved for first-party Cargos and select partners.

Submission States

A Cargo submission progresses through these states:

draft ──► pending_review ──► approved ──► published
                │
                ▼
            rejected ──► (fix and resubmit as new draft)

Updating Published Cargos

To update a published Cargo:

1. Build and push a new container image version (use semantic versioning)
2. Create a new submission referencing the updated image
3. The new version goes through the same scan and review process
4. Once approved, the new version replaces the previous one in the catalog

Best Practices

• Minimal base images — use alpine, distroless, or -slim variants to reduce vulnerability surface
• Pin all dependencies — lock versions in requirements.txt, package-lock.json, Cargo.lock, etc.
• Multi-stage builds — keep compilers and build tools out of the final image layer
• No secrets in images — never embed API keys, tokens, or credentials in container layers
• Test with constraints — always test with --memory, --cpus, and --network=none flags locally
• Pre-scan before submitting — run Trivy and Grype locally to catch vulnerabilities early
• Handle stdin EOF — your Cargo must handle the case where stdin is empty or malformed gracefully
• Emit clear errors — use the error output type with a descriptive message field when something goes wrong

Next Steps

{% end %}