tos-ai

module
v0.0.0-...-bc589bd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: GPL-3.0

README

TOS AI Execution Foundation

This repository has moved. Its contents now live in the execution/ directory of tosnetwork/ai, imported at 9e0728c8e53bcd4c4c71eb02d676021e4d4d9d1b with every original commit and SHA preserved. This repository is archived and read-only; open issues and pull requests in tosnetwork/ai.

Go code imports github.com/tosnetwork/ai/execution/… instead of github.com/tosnetwork/tos-ai/…; existing versions of github.com/tosnetwork/tos-ai stay resolvable through the module proxy.

tos-ai contains the reusable local execution substrate for the Native TOS Service Protocol software-work market. It is not a second registry, an authority over payments, or a public network authority. Finalized TOS state remains canonical; this module executes work bound by an Accepted Quote and produces off-chain outputs and evidence for a TOS-committed Receipt.

The normative product direction lives in tosnetwork/tos-service-spec.

Current scope

This repository intentionally exposes a library foundation, not a public worker protocol. The retained code provides:

  • a fail-closed container execution policy with digest-pinned images, non-root execution, read-only roots, no-new-privileges, bounded CPU/RAM/disk, PID, time and output limits, and network-none or exact host allowlists;
  • a bounded supervisor that rejects duplicate execution identities, contains backend panics, propagates cancellation, and synchronously drains on close;
  • a containerd backend with private socket/FIFO validation, cgroup v2 metrics, OCI hardening and cleanup checks;
  • operator-fixed CDI GPU mappings behind exclusive local leases;
  • a reusable black-box backend conformance harness and optional live containerd/NVIDIA tests;
  • a source-archive workspace boundary that rejects links and traversal, mounts source read-only, and runs the manifest's exact working directory;
  • an at-most-once software-work runner with a crash-safe execution journal;
  • bounded, tamper-detecting content-addressed report and artifact storage;
  • a local commerce Gate and private ingress store that admit an execution or upload only under an ML-DSA-44 Action Authority Writer Fence and AuthorizedActionV1 resolved by key ID;
  • privacy-minimized host/GPU probes and a resource-liveness guard;
  • metrics export, signed update/rollback, and bounded systemd helper libraries used by operator-composed worker processes;
  • a dedicated private-containerd provider deployment template with explicit root-runtime and separate-signing-custody boundaries.

The previous text-generation Worker RPC, model adapters, old Edge gateway, Managed payment path, legacy discovery integration and generalized third-party execution adapters were removed. They encoded the retired protocol and must not be treated as compatibility requirements for the new software-work schema. The escrow-gated A2A, MCP and Agent Packet adapters, their public HTTP boundary and the Messenger event worker were removed with stablecoin escrow: software work settles on the Service Actor rail. pkg/railgate is the replacement gate: it admits a finalized pending Service Actor request at most once. software-work-execute paid admits through it before executing; the command's default mode is for work whose admission its caller already proved.

Build and test

The module uses Go 1.26.11.

go test ./...

The provider-local software-work-execute command composes the frozen V1 job with the bounded executor. The execution contract is frozen in tos-service-spec/docs/SOFTWARE_WORK_EXECUTION_V1.md; settlement follows tos-service-spec/docs/SERVICE_ACTOR_TVM_V1.md. It does not resurrect the deleted inference RPC. Its paid subcommand is the standalone paid path: it admits a finalized pending Service Actor request through pkg/railgate before executing it at most once. The default mode runs a job whose admission its caller already proved, and artifacts-gc deletes artifacts whose retention ended. See the provider runbook.

Tests that check real ML-DSA-44 bytes run the pinned tosctl helper named by TOS_SERVICE_TOSCTL and TOS_SERVICE_TOSCTL_SHA256; they fail, rather than skip, without it.

The provider-local command is a privileged runtime boundary when it connects to root-owned containerd. Do not grant a gateway user, buyer, or remote client access to that raw socket: containerd access is equivalent to host-root authority. The command therefore requires its source archive, source parent, and pre-created state root to be private and owned by the executor identity, and it refuses symlinks, non-canonical paths, broad permissions, and oversized source files. The containerd socket and FIFO tree remain owner-private. Receipt signing stays in the separate tosctl custody boundary; no mnemonic or private key belongs in executor state.

A provider runtime that should not run as root reaches the same executor through software-work-executord: a root-run service that alone opens the private containerd socket and serves the frozen job to exactly one explicitly allowed uid over a Unix socket (pkg/executorservice holds the server and the client). A request carries digests, limits that can only tighten the preset, and the source bytes; never a path, image or command. See the provider runbook.

Repository layout

pkg/executor/                    policy, supervision and backend contract
pkg/executor/containerdbackend/ containerd implementation
pkg/executor/backendtest/       reusable lifecycle conformance suite
executor/gpuisolation/          exclusive operator-named GPU leases
pkg/softwarework/               bound jobs and at-most-once outcome journal
pkg/executorservice/            root-run executor service and its client for unprivileged callers
pkg/railgate/                   finalized pending-request admission for paid Service Actor work
pkg/artifactstore/              immutable content-addressed output storage with bounded retention
pkg/commercegate/               Action Authority gated local execution admission
pkg/privateingress/             Action Authority gated private content ingress
pkg/probe/                      privacy-minimized local resource probes
internal/resourceguard/         continuous fail-closed resource gating
pkg/metricsexport/              bounded metrics delivery
pkg/update/                     signed artifact manifests
pkg/softwareupdate/             crash-safe two-slot update state machine
pkg/servicemanager/             fixed-unit bounded systemd operations
deploy/provider/                private containerd provider template and runbook

See isolated backend conformance for the security and live-test gates. Passing unit or lifecycle tests is not a hardware-isolation attestation.

Licensed under the GNU General Public License v3.0.

Directories

Path Synopsis
cmd
software-work-execute command
Command software-work-execute runs one V1 software-work job through the production bounded executor and prints its content-addressed outcome.
Command software-work-execute runs one V1 software-work job through the production bounded executor and prints its content-addressed outcome.
software-work-executord command
Command software-work-executord is the root-run executor service of a provider host.
Command software-work-executord is the root-run executor service of a provider host.
executor
gpuisolation
Package gpuisolation provides the exclusive GPU-device lease boundary used in front of a reviewed container backend.
Package gpuisolation provides the exclusive GPU-device lease boundary used in front of a reviewed container backend.
internal
actionauthoritytest
Package actionauthoritytest supports tests of the ML-DSA-44 Action Authority boundary: an authority-scoped resolver, a private tosctl vault whose controllers can sign one message under any signature use (so a test can present a signature made under another context), and the refusal variants every Action Authority consumer must reject.
Package actionauthoritytest supports tests of the ML-DSA-44 Action Authority boundary: an authority-scoped resolver, a private tosctl vault whose controllers can sign one message under any signature use (so a test can present a signature made under another context), and the refusal variants every Action Authority consumer must reject.
dirlock
Package dirlock provides non-blocking process ownership for private local state directories.
Package dirlock provides non-blocking process ownership for private local state directories.
nilcheck
Package nilcheck provides the construction-time interface validation used at operator-controlled dependency injection boundaries.
Package nilcheck provides the construction-time interface validation used at operator-controlled dependency injection boundaries.
resourceguard
Package resourceguard continuously verifies that the host class which backed startup admission still exists.
Package resourceguard continuously verifies that the host class which backed startup admission still exists.
pkg
artifacthttp
Package artifacthttp publishes verified artifactstore objects through a stable HTTPS content-addressed URL.
Package artifacthttp publishes verified artifactstore objects through a stable HTTPS content-addressed URL.
artifactstore
Package artifactstore provides a bounded, immutable local content-addressed store for software-work outputs.
Package artifactstore provides a bounded, immutable local content-addressed store for software-work outputs.
capabilitygate
Package capabilitygate enforces Trusted Capability V1 at the executor sink.
Package capabilitygate enforces Trusted Capability V1 at the executor sink.
commercegate
Package commercegate implements the local, Agreement-bound execution start boundary.
Package commercegate implements the local, Agreement-bound execution start boundary.
executor
Package executor defines the isolation contract for containerd-backed execution.
Package executor defines the isolation contract for containerd-backed execution.
executor/backendtest
Package backendtest provides a reusable black-box lifecycle suite for audited isolated-execution backend implementations.
Package backendtest provides a reusable black-box lifecycle suite for audited isolated-execution backend implementations.
executorservice
Package executorservice is the privilege boundary between an unprivileged provider node and the root-only private containerd: a server that runs the frozen software-work job on behalf of an allowed local uid, and the client that node uses to reach it over a Unix socket.
Package executorservice is the privilege boundary between an unprivileged provider node and the root-only private containerd: a server that runs the frozen software-work job on behalf of an allowed local uid, and the client that node uses to reach it over a Unix socket.
metricsexport
Package metricsexport provides an explicitly configured, bounded remote export path for the worker's privacy-minimized Prometheus snapshot.
Package metricsexport provides an explicitly configured, bounded remote export path for the worker's privacy-minimized Prometheus snapshot.
privateingress
Package privateingress implements the receiver-selected, Agreement-bound private byte ingress used before a commerce execution starts.
Package privateingress implements the receiver-selected, Agreement-bound private byte ingress used before a commerce execution starts.
probe
Package probe reports coarse host capabilities without exposing serial numbers, exact topology, customer data, or a stable hardware fingerprint.
Package probe reports coarse host capabilities without exposing serial numbers, exact topology, customer data, or a stable hardware fingerprint.
railgate
Package railgate admits the execution of a paid Service Actor request at most once, and only while finalized TOS state shows the request pending with enough time left to answer it.
Package railgate admits the execution of a paid Service Actor request at most once, and only while finalized TOS state shows the request pending with enough time left to answer it.
servicemanager
Package servicemanager provides a fixed-unit systemd adapter for operator composition.
Package servicemanager provides a fixed-unit systemd adapter for operator composition.
softwareupdate
Package softwareupdate manages two crash-safe software release slots.
Package softwareupdate manages two crash-safe software release slots.
softwarework
Package softwarework binds the frozen software-work contract to the bounded executor and immutable artifact store.
Package softwarework binds the frozen software-work contract to the bounded executor and immutable artifact store.
update
Package update verifies content-addressed release manifests.
Package update verifies content-addressed release manifests.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL