Public API and application SDKs¶

Applications integrate with Colossus through the public application API, not the private worker protocol and not colossus-agent internals. The initial contract is colossus.api.v1alpha1; its implemented surface provides authenticated system metadata and durable agent runs.

flowchart LR
    Web["Tauri WebView"]
    Native["Tauri Rust backend"]
    Other["Rust, TypeScript, Python, or Go application"]
    SDK["Colossus SDK"]
    TLS["Pinned TLS 1.3 and bearer authentication"]
    Worker["Colossus worker"]
    Public["Public API adapter"]
    Runtime["Runtime and Safety Kernel"]
    Journal["Hash-chained journal<br/>configured encryption"]

    Web -->|"narrow commands and ordered channels"| Native
    Native --> SDK
    Other --> SDK
    SDK --> TLS
    TLS --> Worker
    Worker --> Public
    Public --> Runtime
    Public --> Journal
    Runtime --> Journal

Reading the diagram without color: untrusted renderer code calls a narrow native interface; native or server applications use an SDK; the SDK authenticates a pinned loopback gRPC connection; the worker translates public resources into the existing runtime and durable journal.

Why gRPC is at the worker boundary¶

Protobuf and gRPC give non-Rust applications a generated, versioned contract and an ordered streaming transport. The public server belongs at the long-running worker boundary because runs must survive a UI reload, SDK disconnect, or client-process restart. colossus-agent remains an internal application service and never becomes a network authority.

The public API is distinct from the private worker IPC protocol:

The keys and credentials for these boundaries are independent. Do not derive one from another.

Runtime placement¶

The Rust SDK uses one public API across three explicit placements:

• Daemon connects to an installed shared worker. Desktop presents these connections as External targets for advanced, persistent, and fleet use; durable work can continue after the desktop application exits.
• Sidecar supervises an application-bundled isolated worker. It is appropriate when the application needs separate state and lifecycle ownership. Colossus Desktop calls this placement Managed Local and makes it the default. A sidecar gRPC host must explicitly advertise Sidecar; the host API defaults to SharedDaemon and its bounded deployment-mode type cannot advertise Embedded.
• Embedded calls an application-private runtime in process. It needs no gRPC transport, but it still uses the SDK interface so application code does not depend on runtime internals.

TypeScript, Python, and Go SDKs connect to a daemon or sidecar over gRPC. They are native/backend SDKs, not browser SDKs.

A browser-only web application needs its own authenticated backend-for-frontend. That backend may use the TypeScript, Python, or Go SDK, but the browser must not receive the local daemon descriptor or application bearer credential. The worker does not expose gRPC-Web or permissive cross-origin transport.

Tauri integration¶

Tauri can call Rust directly, so a Tauri application does not need a separate JavaScript-to-Colossus transport SDK. Colossus Desktop holds a native ConnectionManager keyed by opaque target IDs. It owns one Managed Local sidecar for the active workspace, any saved External daemon clients, per-target watch limits, and the selected Work target. The renderer receives sanitized target health and invokes only product-level Tauri commands:

• create_run
• get_run
• list_runs
• watch_run
• cancel_run
• respond_interaction

Desktop’s composer exposes public Execute, Plan, and managed-local Research run modes. Research carries an explicit bounded depth and a unique non-empty set of repository, web, or MCP evidence lanes. It reuses the authenticated durable run, interaction, watch, queue, and cancellation contracts while delegating collection and cited synthesis to the runtime research service. The initiating question and released report remain ordinary canonical conversation messages; tool traffic and unrestricted paths do not cross the renderer boundary.

Public Plan Mode means “create one new durable Draft”; the runtime constrains its tools and returns the canonical Plan identity, revision, and status in terminal result or cancellation evidence. The native bridge preserves those typed fields rather than attempting to reconstruct a Plan from assistant text.

For an actionable Draft, the main WebView can submit a typed plan_action on another public run. It supplies the caller-owned source run ID and exact visible revision, never a Plan ID. The server resolves that source run under the authenticated application, binds the action to its session and canonical Plan, and rejects stale or non-Draft revisions. Revision is structurally Plan Mode; Direct and bounded Goal execution are structurally Execute mode. They use the ordinary durable run, interaction, policy, permit, journal, audit, cancellation, and watch paths.

Managed Local can also hand the identity to the embedded TUI for the advanced interactive workflow. The main WebView supplies only bounded session and Plan identifiers to show_terminal_window. Native code accepts them only for colossus_tui; the dedicated terminal document opens the authenticated TUI and submits the fixed read-only /session resume ID and /plan use ID selections. No PTY session ID or generic terminal write command is granted to the main WebView.

The zero-input desktop_release_channel metadata command returns only the native compile-time development, stable, developer_preview, or validation_only enum. It lets the renderer label a Developer Preview even if runtime initialization fails; it accepts no renderer data and exposes no signing identity, path, credential, or runtime authority.

Every run operation carries an opaque target ID. The target manager, not the renderer, resolves it to an authenticated SDK client. Fleet may display health for all targets, but Work sends an operation to exactly one selected target.

Renderer target IDs are advisory, not routing authority. Native code accepts a run operation only when its ID matches the current Work selection, binds returned run IDs to that target, and requires the binding again for watches and mutations. Selection epochs terminate an old watch before it can deliver another target's update. Target switch, reconnect, removal, and Managed Local restart take the native selection writer, wait for in-flight mutations, and never replay a request. External import, selection, reconnect, and removal also require an operating-system dialog naming the native-sourced label, instance ID, and full certificate pin.

Use a Tauri channel for the ordered watch_run feed. The WebView receives released run DTOs only. It must never receive the bearer credential, certificate file contents, daemon descriptor path, provider key, private runtime path, raw gRPC channel, caller scopes, tool arguments, hidden reasoning, or quarantined output.

The Rust client can use either placement without changing that WebView contract: Embedded calls the trusted runtime in process and uses no gRPC, while Daemon or Sidecar keeps durable work in another process and uses authenticated gRPC behind the Rust command layer. In both cases, depend on the stable Rust SDK boundary rather than calling runtime internals from Tauri commands.

Keep Tauri capabilities deny-by-default. Grant each window only the commands it needs, and enforce resource scope again inside each command. Do not add generic “run process,” “read path,” “call URL,” or “invoke SDK method” commands; those would turn the WebView into a capability-confused deputy.

Managed Local bootstrap and lifecycle¶

Managed hosts carry an explicit ManagedExecutionBoundary independently from access profile and approval mode:

• FullAccess is the default host posture and maps to acknowledged danger_full_access;
• WorkspaceIsolated selects the supported platform-native workspace-development boundary; and
• OfflineIsolated selects platform isolation without derived workspace resources, hides the generic model-visible network.http, web.fetch, and docs.fetch tools, and retains the exact provider service and authentication/refresh destinations needed by the configured provider.

Rust builders and getters expose this choice, and the private sidecar protocol carries it as a versioned bootstrap field. Hosts must not infer it from the access profile. Full access permits ambient structured filesystem and HTTP(S) effects as well as child process resources, but it does not add undeclared tools, routes, credentials, MCP servers, integration operations, or extension trust.

OfflineIsolated is therefore not an air-gap declaration: selected provider and authentication transports can still use their retained destinations. Preserving those destinations does not reactivate general model fetch tools. Search, MCP, and integration adapters remain independently governed by their own configuration and host grants.

The signed desktop bundle contains two independent executables:

• colossus-sidecar owns runtime composition, private worker IPC, the public gRPC host, sandbox-helper dispatch, drain, checkpoint, and guardian-triggered shutdown;
• colossus is the separately verified interface binary used only for the fixed TUI launcher.

The native application verifies the sealed bundle manifest and macOS code identity immediately before a no-shell spawn. It sends bounded workspace configuration, exact application grants, one-use API material, and provider credentials over inherited anonymous pipes. Bootstrap secrets never enter argv, environment variables, files, renderer events, logs, or debug output. The sidecar binds a loopback TLS endpoint, creates an independent API authentication root, and returns the exact endpoint, certificate pin, instance identity, API version, and bearer through that private channel. Native code validates every field before activating the credential and marking the target Ready.

Executable binding is completed before either bootstrap secrets or execution are released. On macOS, the SDK hashes and parses one private snapshot, starts the selected bundle executable with the kernel's start-suspended flag, and requires its exact live CodeDirectory identity to match before SIGCONT. On Linux, it executes the verified bytes from a sealed, non-writable memfd. Platforms without an equivalent mechanism fail Managed Local startup closed.

The selected macOS workspace is also persistent object authority rather than a saved path. Desktop hashes the device, inode, and birth timestamp obtained from a securely opened directory descriptor and includes that versioned identity in its private state partition. The SDK parent and sidecar child independently reproduce it before launch or runtime composition; preview-era path-only or inode-only settings require explicit folder reselection. Unix skill discovery and resource reads then stay relative to the retained workspace or independently retained app-private root descriptors.

Desktop uses two same-application credentials delivered and activated as one bootstrap set. The primary credential has exactly runs:execute, runs:read, runs:control, and prompts:respond, plus the selected role and tool ceilings. A separate native approval broker has only approvals:respond, no tools, and roles bounded by the primary grant. The SDK routes only approval answers through that second pinned-TLS client; every other operation uses the primary client. Both credentials are revoked together during shutdown or a failed bootstrap, and neither transport replays an operation after a restart.

Provider YAML for Managed Local contains a validated host:<opaque-id> reference. The key remains in the desktop keychain and is copied into a zeroizing, in-memory sidecar resolver during bootstrap. The provider adapter can resolve it only after policy has authorized the provider action. CLI and daemon configurations remain environment-backed and do not interpret host: identifiers as values.

Same-provider model and profile edits can reuse the native keychain binding without opening another secret prompt. First enrollment, provider-kind changes, and explicit rotation never take that reuse branch. A missing reused key fails before any settings or runtime mutation and requires an explicit replacement retry. First-time non-Minimal access and every access-rank elevation, including Development-to-Allow-all, require a native confirmation describing the wider tool ceiling. Execution-boundary elevation is confirmed separately, including a move from an isolated boundary to Full access; renderer input alone cannot widen either axis.

WebView reload does not own sidecar lifetime. Provider and workspace changes request a graceful restart. An unexpected exit receives at most three backoff attempts; create and effect requests are never automatically replayed. Application exit uses the worker's existing run drain, transport force-close, checkpoint, and native process supervision. It terminates the signed sidecar, its managed process group, and still-discoverable descendants. A writer-lease conflict is reported without killing or taking over the existing owner.

Sealed macOS bundle manifest¶

macOS code signing changes executable bytes, so a digest captured by the Rust build script cannot authenticate the final signed sidecar. Release packaging therefore uses a two-phase contract:

1. A credential-free runner creates and archives the unsigned .app with both externalBin entries.
2. A fresh signing runner verifies and extracts those exact bytes, then imports the Developer ID and notarization authority.
3. Packaging signs the nested sidecar and CLI individually.
4. It hashes those final bytes into Contents/Resources/colossus-bundle-manifest.json.
5. It patches the exact manifest SHA-256 into the one fixed binding record in the already-built desktop executable, then signs that executable and the outer app without --deep.
6. It verifies every nested signature, the outer seal, the embedded manifest binding, and both nested-binary hashes before optional notarization and stapling.

The signed running desktop executable is the manifest trust anchor. Release native code ignores the compile-time unsealed_release marker, opens the resource once with NOFOLLOW, hashes and decodes that same bounded byte buffer, and rejects an unset or mismatched embedded digest. This prevents a same-user path swap or rollback to an older same-team bundle after outer verification. It also fails closed unless the bound manifest has the expected schema, target triple, release channel, fixed filenames, and exact lowercase SHA-256s. The compile-time channel and sealed-manifest channel must match.

The stable channel requires the outer app and desktop executable identifier com.obscuritylabs.colossus.desktop, the fixed .sidecar and .cli nested identifiers, and the exact 10-character Apple Team ID compiled into the release. It uses Developer ID signing and notarization. The explicitly separate developer_preview channel instead requires the ADHOC sentinel, an ad-hoc signature with no Team Identifier, the same fixed code identifiers, strict signature verification, and the same executable/manifest hash binding. It is runnable for time-bounded testing, but it does not establish Apple publisher identity and is not notarized. Native code exposes only this bounded channel name to the renderer so Desktop can keep a persistent Developer Preview warning on screen; no signing identity, filesystem path, or credential enters renderer state.

The validation_only channel also uses the ADHOC sentinel but remains non-runnable and is accepted only for CI structure checks; Managed Local rejects it. Debug builds use the development channel and compile-time manifest with canonical development paths. These channels are mutually exclusive, so enabling the preview does not relax stable-channel identity or notarization requirements.

Local terminal boundary¶

Terminal commands are available only to a dedicated local Tauri window capability. The main window may request that window be shown but cannot open or control a PTY. The terminal renderer receives random window-bound session IDs and can request only the closed colossus_tui and shell kinds for the native-selected workspace. It cannot choose a program, environment, working directory, or arguments.

Desktop does not inject managed credentials, persist transcripts, or send terminal bytes to models, remote nodes, telemetry, or run context. Output, input, and session count are bounded. First-time terminal enablement requires a fixed native confirmation that distinguishes local-user shell authority from the policy-controlled TUI.

On macOS, the shell kind revalidates the persisted Managed Local workspace and launches exactly the validated system /bin/zsh -l with a native-constructed cleared environment. The shell receives no worker authentication. It remains available while the managed runtime is offline, but its commands and effects are outside Colossus policy, remote journal, and audit. A compromised terminal renderer can therefore type commands as the logged-in user while this feature is enabled; the main renderer cannot write to a PTY.

The bundled CLI instead starts suspended in a new session so native code can verify its live code identity against the sealed manifest before resuming it. The CLI independently opens and changes directory through the selected workspace, reports the same persistent object identity to the parent, and receives worker authentication only after that attestation succeeds. Authentication crosses bounded one-use inherited anonymous pipes, never the renderer-visible PTY. Closing the window or app freezes and kills that verified CLI session.

The PTY transports only terminal input and output. Native code passes worker authentication through separate bounded one-use inherited pipes at fixed child file descriptors; those descriptors are never renderer-selectable and never share the PTY stream.

A plan handoff does not widen this boundary. Native code validates the opaque public session and plan identifiers, binds them to a colossus_tui launch request, and releases them only to the dedicated terminal document. That document may submit the two fixed selection commands after the verified TUI opens. The main document still has no open_terminal or write_terminal capability, and the selection performs no lifecycle transition by itself.

Desktop does not claim cleanup of arbitrary shell descendants after setsid, double-fork, or reparenting because macOS exposes no supported race-free job primitive for that boundary. It retains and kills the original process group on a best-effort basis. Clipboard escape writes, automatic URL opening, remote navigation, and general renderer-selected spawning stay disabled. The release terminal surface is served from a label-bound local protocol with its own CSP so xterm may create its required runtime style sheets; the main Work WebView retains the stricter style-src 'self' policy. The TUI path is different: fixed arguments require the existing worker, and its actions retain normal Colossus policy and audit behavior.

After shutdown or a failed launch, SDK cleanup waits for confirmed process-tree death, then removes only the fixed public endpoint descriptor and certificate through a held no-follow directory descriptor. Every leaf is revalidated for identity, ownership, mode, type, and single-link status immediately before unlink; unrelated or unsafe state is left intact.

Connection and enrollment¶

A daemon connection deliberately has four separate inputs:

1. an owner-only endpoint descriptor with an exact literal loopback HTTPS endpoint, instance identity, PID, API version, and lowercase leaf-certificate SHA-256;
2. an owner-only PEM containing exactly one BasicConstraints CA=false public leaf certificate whose DER digest matches the descriptor;
3. the expected instance identity and certificate SHA-256 provisioned independently during trusted enrollment; and
4. a one-application bearer credential loaded directly from a platform credential store into native memory.

The descriptor is mutable readiness metadata, not a trust anchor or authorization. It contains no token or private key. Every native convenience connector requires the independent pin and checks descriptor pin equals expected pin and presented leaf equals expected pin before loading the bearer. SDKs reject plaintext, localhost, public interfaces, URL credentials, unknown descriptor fields, certificate-pin mismatch, malformed credentials, and oversized transport messages.

The Rust gRPC connector also requires the independently provisioned instance ID and API major. Its TLS verifier hashes the leaf presented in the live handshake, rejects intermediates, and compares that digest to the expected pin. Before returning a usable backend it makes only the authenticated GetServerInfo compatibility call and verifies the exact instance ID, API package, and daemon-versus-sidecar deployment mode; no credential-bearing application RPC can run first.

Trusted enrollment code creates an exact application grant:

• application ID and placement;
• runs:execute, runs:read, runs:control, prompts:respond, approvals:respond, artifacts:read, and/or artifacts:write;
• allowed logical roles; and
• allowed tools.

Empty role and tool grants deny all. Credential issuance first persists a pending keyed verifier and the grant in the canonical journal. Managed Local uses platform-backed encryption; other hosts use their configured storage protection. Pending credentials cannot authenticate. Trusted bootstrap transfers the one-time bearer directly to an operating-system credential store, then records a separate durable activation. The bearer must not enter a file, descriptor, URL, command line, environment variable, crash report, or log. Rotation activates a new credential for the same application ID before revoking the old credential; revocation permanently invalidates either state. If old-credential revocation cannot be confirmed, the active replacement remains in the destination and administration reports both non-secret IDs for reconciliation.

A generic OS-keyring service/account pair is a lookup namespace, not portable process identity or an application sandbox. On some platforms another process running as the same OS user can read an unlocked generic store; on macOS an item created by the CLI may require an access prompt or may not be readable by a separately signed target without an appropriate access policy. Applications that must defend against hostile same-user processes must supply a platform-specific, application-bound credential provider and keep the independent pin in signed configuration or app-owned protected storage. The built-in generic provider protects against files, logs, argv, environment leaks, other OS users, and accidental credential reuse; it does not claim same-UID process isolation.

Public runs may use agent.delegate only when that exact tool appears in the application grant. The accepted run and every delegated job durably preserve the caller's exact tool ceiling. Child runs receive that ceiling but remove agent.delegate from model discovery, which keeps nested delegation fail closed and prevents a child from acquiring the worker's broader internal authority.

Authenticated server discovery reports optional capabilities such as artifacts, attachments, delegation, and typed Plan continuation. Clients must hide or disable optional UI until the server advertises it. In particular, the SDK refuses to encode a plan_action unless the target advertises plans.continue; this prevents an older protobuf server from ignoring the unknown field and treating it as an ordinary run. Artifact uploads are caller-owned, size- and digest-bound, and chunked; downloads revalidate the released length and digest. Run attachments contain only opaque artifact IDs, never client or server filesystem paths.

attachments.image_input is advertised separately from the existing text-attachment capability. SDK ContentPart::Artifact calls remain unchanged and caller ordering is preserved, but servers reject image artifacts unless the selected model profile has explicitly enabled image inputs.

Public v1alpha1 runs also cannot activate installed skills. selected_skills must be empty, and prompt text such as @skill-name does not trigger skill discovery or composition. Skill activation remains disabled until the durable application grant has an explicit allowed-skill ceiling and recovery can prove that the same ceiling is preserved. This prevents an application from discovering private installed skill metadata or expanding its instructions and tool context indirectly.

CreateRunRequest.end_user_id is optional caller-asserted correlation data. It uses the bounded public token grammar, may contain PII, and is neither an authenticated principal nor an authorization input. It is included in the idempotency fingerprint so one key cannot replay a request attributed to another asserted end user. An accepted W3C traceparent/tracestate is deliberately excluded from that fingerprint, allowing a retry from a new calling span to remain a valid replay. See Live observability.

The installed Unix worker provides the first-party bootstrap path: perform worker --public-api-dir ... --enroll-application ... while the worker is stopped, then start worker --public-api-dir .... Enrollment requires exact scope and role ceilings and writes the one-time bearer directly to the application's named OS-keyring entry. See Storage and worker for the complete command and rotation procedure.

Enrollment output includes the stable non-secret instance ID and certificate SHA-256. Provision both into trusted application configuration separately from the discovery directory. Never compute the expected pin by rereading endpoint.json or certificate.pem; doing so would make a same-directory replacement self-validating.

The initial server also bounds each TLS handshake to five seconds, accepts at most 128 simultaneous connections, permits at most 80 concurrent request setups globally and per connection, permits 128 HTTP/2 streams per connection, expires connections after 15 minutes, limits each request decode and handler setup to 30 seconds, limits HTTP/2 headers to 16 KiB, limits decoded request messages to 2 MiB, and limits encoded responses to 4 MiB. Only eight authenticated protobuf decodes may run concurrently, with at most two for one application; the permits are acquired after authentication but before message decoding. A streaming protobuf wire guard rejects the 129th top-level CreateRun.input field, the first forbidden selected_skills field, and the tenth packed or unpacked ListRuns.statuses value before Prost can allocate their decoded collections; post-decode validation remains as defense in depth. The transport independently caps active watches at 64, leaving 16 request slots that watches cannot consume for cancellation, interaction responses, and system RPCs. These effective transport limits are advertised through GetServerInfo. The Rust client verifier also rejects TLS 1.2 signatures, preserving the TLS 1.3-only contract even if a future server configuration regresses. The deterministic local leaf uses P-256 so the same pinned identity works with the Rust, Python gRPC C-core, Node.js, and Go SDK transports. Run input is limited to 128 parts and 1 MiB, and max_turns cannot exceed 100. Zero selects the configured positive default; it does not request an unlimited run.

Preview applications enrolled against the earlier Ed25519-derived leaf must perform one authenticated re-enrollment after upgrading and store the newly reported certificate fingerprint. The P-256 leaf remains byte-for-byte stable for the same stored seed after that one-time pin rotation.

Default application-resource limits are 32 active runs globally and eight per application, with fresh-create token buckets of four runs/second (burst 16) globally and one run/second (burst four) per application. Watches are limited to 64 globally and eight per application. Owner-index listings allow four concurrent requests globally and one per application, with separate global and per-application rate limits. The server advertises the effective values through GetServerInfo.

ListRuns reads only the authenticated application's durable run index, newest first; it never scans the shared global journal. CreateRun appends the idempotency claim, run creation, and owner-index entry in one transaction, retrying an owner-index head conflict without exposing a partially indexed run. A page contains at most three runs. One request reads owner-index events in batches of eight, advances through at most 64 index entries, reconstructs at most 16,396 run events, and accepts at most 4,099 events from any one valid run stream. Sparse filters can therefore return a short or empty page with a continuation token; clients continue while that token is present. Ordinary nonterminal appends stop when the durable sequence reaches 4,096; three reserved lifecycle events allow interaction closure, the cancelling transition, and one terminal event without making that valid stream unlistable.

Each run-update event carries a versioned projection of the public state immediately before that update and the cumulative released-byte count. Protected storage encrypts the payload; keyless storage keeps canonical plaintext with payload and record hashes. A mutation authenticates the creation event and two-event tail, derives the current state and byte count from the predecessor, validates the tail projection against them, then uses optimistic stream concurrency for its append; its work is independent of run history length. While an interaction is pending, only its resolution or a conservative terminal settlement may append, preventing repeated projection of its bounded prompt. Full reads still replay every transition and cross-check every embedded projection and byte count, so the fast mutation path does not replace journal-chain verification with an in-memory cache.

The opaque continuation token binds the application and canonical filters and carries the owner-index snapshot head plus an exclusive resume version. The server validates both referenced index versions before continuing. Runs created after the first page do not shift that traversal, and per-request work stays bounded independently of unrelated journal growth.

Durable run contract¶

CreateRun durably claims an idempotency key before execution. A caller can then fetch the run or call WatchRun with an exclusive after_sequence cursor. Watch delivery is at least once; SDKs deduplicate exact (run_id, sequence) replays and fail on gaps. Dropping a watch never cancels its run. SDKs reconnect only after an explicitly retryable transport failure. All SDK watch paths reconcile a clean stream close with GetRun and complete only when it proves the same run is terminal at the exact verified cursor. Daemon and sidecar streams can resume a non-terminal watch under their bounded read-only retry policy. Embedded and custom checked streams instead fail closed when reconciliation is unavailable or does not exactly match; a clean close is never accepted as silent completion.

When CreateRun omits session_id, the durable run receives a server-owned session identity. The canonical session is materialized during agent initialization if execution proceeds; cancellation before start can leave that identity associated only with the run. The initial hosted surface does not expose SessionService.

Prompts and approvals are durable, one-use interactions bound to the owning application. Prompt choices echo the exact displayed choice. Approval answers echo a fresh randomized one-use binding; the private policy request hash never crosses the native boundary. Approval DTOs expose only a fixed public action taxonomy plus a bounded display category or an HTTP(S) origin; they never disclose raw internal action or tool names, absolute paths, executable names, URL credentials, paths, queries, fragments, raw policy reasons, effect arguments, or deterministic commitments to those private values. The server revalidates responses against the private request and applies current scope checks to cancellation and response operations.

Loopback limits bound resource consumption but cannot guarantee availability against a hostile local process, including one running as another OS user: loopback TCP does not carry filesystem-style ownership. Such a process can open unauthenticated sockets and consume some finite connection or handshake slots. Deployments with that threat model need an ACL-bound local transport or operating-system process isolation in addition to application-bound credentials.

After an unclean worker stop:

• a durable queued run can resume with its accepted authority snapshot;
• a run waiting for user input becomes interrupted;
• a run that may have started an external effect becomes outcome_unknown; and
• SDKs never automatically retry an operation whose outcome is unknown.

Recovery uses the grant captured when the run was accepted. The request that notices an orphan cannot lend broader current authority to it.

Revoking a bearer prevents future requests made with that credential; it does not rewrite or silently weaken already accepted durable work. To terminate accepted work, use another credential for the same application with runs:control to cancel the run. This distinction keeps recovery deterministic and avoids treating a credential rotation as an ambiguous partial cancellation.

Source and release workflow¶

• Protobuf source: api/colossus/api/v1alpha1
• Rust SDK: crates/colossus-sdk
• TypeScript, Python, and Go packages: sdk/
• Generated binding command: ./sdk/scripts/generate
• Generated binding gate: ./sdk/scripts/check-generated

Generated sources are replaced from the local Protobuf tree. Do not upload a private schema to a hosted generator. A release runs Protobuf lint/build, generated-tree checks, each language's tests and type checks, Rust workspace checks, and a live TLS/authentication round trip.

The alpha package may make breaking corrections before a stable v1 package exists. Once v1 is published, reserve removed field numbers and names, add fields and RPCs compatibly, and support adjacent API versions during migrations.