Skip to main content
hiloop has three kinds of principal: a user (a human identity), a service account (a machine credential not bound to a user), and a workload — a named, organization-scoped identity that a run is launched as.
Workload identity applies to runs today: hiloop run --as workload/<name> is the only verb that takes --as. hiloop sandbox create has no workload declaration, so a sandbox does not yet carry an ambient workload identity, and the sandbox-side pieces below describe the shape that lane will take rather than behavior you can use now.
Get the vocabulary straight first, because “agent” is an overloaded word: in these docs an agent is always your program — the LLM harness that calls models, runs tools, and edits files. A workload is the identity it assumes. Your agent runs as a workload identity. The agent is the subject; the workload is the security identity the platform attributes, authorizes, and bounds.

​
Why a third kind exists

A person running code directly and an autonomous agent operating unattended in the same organization are different risks. The unattended workload is the exfiltration case a lockdown exists for, not the human at the keyboard. To treat them differently, the platform needs to know who is driving the work, and a service account cannot say: it names a credential, not what that credential is currently doing. A workload identity closes that gap. It gives autonomous execution:
  • A name of its own. Work shows up attributed to codex-runner, not to the API key of whoever happened to start it.
  • A policy attach point. Because human-launched and workload-launched work carries different identities, policy can treat them differently: locking unattended workloads down while humans keep a laxer baseline (see network egress for what sandboxes enforce today).
  • A provenance trail. Every workload launch records the principal that launched it, so an action reads as a delegation: executing as workload codex-runner, on behalf of the user who launched it.
A workload is not a user: it has no login, no console session, and no organization membership. It is a registered name with an owner trail and a launch ACL.

​
Register a workload

Registration is always explicit — launching as an unregistered name is an error, never an implicit registration. Any member of the organization can register one:
Names are unique per organization: lowercase letters, digits, ., _, and -, starting and ending with a letter or digit, at most 100 characters. List and inspect the registry:
LAUNCH is the workload’s launch ACL: members (any member of the organization may launch as it — the default) or restricted (N) with the number of allowed launchers. Pass --output json for the full record.

​
Declare it at launch

The executing identity is declared, never inferred. Pass --as workload/<name> when you start a run; without --as, the work runs as your own identity:
The declaration is checked before anything starts:
  • The name must be registered — an unknown workload name is rejected, not auto-created.
  • You must hold launch rights on it (see the launch ACL).
Once declared, the identity is fixed for the lifetime of the run. It is recorded on the run’s record and cannot be changed after the fact.

​
The launch ACL

Each workload carries an ACL saying who may launch as it. A new workload starts open to every member of the organization member. To restrict launching to named principals — or open it back up — use allow-launch (requires an owner or admin in the organization). A launcher is either a user (an organization member, named by user id) or a service account (a machine credential, named by its key id — how you authorize a CI pipeline to launch a restricted workload):
The --user/--service-account flags replace the previous list together. A restricted workload is launchable only by the principals on its list: a listed user’s session or user-bound key, or a listed service-account key presented directly. Anyone else’s --as workload/<name> is rejected — including service-account credentials that are not on the list; machine launchers are never implied, only named. A service-account entry must name a live, non-revoked service-account key in your organization.

​
Delete a workload

Deleting a registration requires an owner or admin in the organization, and asks for confirmation unless you pass --yes:
Deletion is idempotent: deleting a name that is not registered — including a repeat of a delete that already completed — succeeds, so a retried delete converges instead of erroring. Two honest edges:
  • A workload with work still running under its identity is a conflict: let it finish, or stop it, then delete.
  • Past runs keep the workload’s raw id in their attribution, but once the name is gone that id no longer resolves to a name. Delete freely to clean up a typo’d registration; prefer keeping workloads that own meaningful history.

​
Attribution and delegation

A workload launch records two identities, not one:
  • As what identity is this executing — the workload. The run is workload-classed.
  • Under whose authority — the principal that launched it, recorded on that credential. This is standard delegation (“on behalf of”): the human delegates to the workload, and the record keeps both ends.
The executing identity flows through observability:
  • A workload-classed run renders the workload’s registered name in PRINCIPAL columns (hiloop runs list, hiloop runs show) — attribution names the identity the run executes as, not the credential that launched it. The record keeps both: the run’s executing_principal/executing_kind name the workload, created_by stays the launcher.
  • hiloop runs list --principal codex-runner filters to a workload’s runs (a workload name filters the runs executing as it; a key or user name filters the runs it created).
  • The event schema reserves executing-identity attributes for future runtime-native egress decision producers. The current fixed network floor does not emit destination decisions.

​
Short-lived cloud credentials

A workload is designed to reach your cloud accounts without any static key entering the sandbox. Each deployment serves an OIDC issuer for workload identity; a process running as a workload mints a short-lived, audience-bound JWT on demand and exchanges it directly with AWS, Google Cloud, or Microsoft Entra through their native workload-identity federation. No long-lived cloud credential is stored anywhere, no refresher daemon runs in the guest, and no default token file is created. Registering federation works today. Minting a token from inside a sandbox does not: it depends on the sandbox carrying an ambient workload identity, which it cannot yet be launched with. Register the trust now if you like, but do not build a flow that depends on the in-sandbox exchange yet. Federation is registered per workload and per cloud. The provider audience is derived server-side from the registered descriptor, so a workload can request tokens only for audiences an owner or admin registered:
Google Cloud registrations take the project id, project number, and workload identity pool and provider ids (with optional service-account impersonation); Microsoft Entra registrations take the application and organization ids. Removing a registration revokes the audience on the hiloop side; the trust you created in the cloud account is yours to remove separately. Inside a sandbox that carries an ambient identity, hiloop workload-identity is what wires the cloud SDKs to it:
  • token mints one short-lived federation JWT and writes only the token to stdout.
  • aws-credentials emits AWS credential_process JSON after an in-process web-identity exchange.
  • gcp-credential-source emits Google Cloud’s executable-sourced subject-token envelope.
  • azure-token-file refreshes the Microsoft Entra SDK fallback token file on boot-local tmpfs.
  • setup prints the exact SDK wiring for the workload’s registered federation descriptors.
Because the cloud-side trust policy pins the issuer and the workload’s subject, a cloud API call made this way is attributable to the workload on both sides of the boundary: in your cloud audit log and in the hiloop run record.
  • Network egress — the current fixed floor and destination-filtering gap.
  • Glossary — workload identity next to the rest of the vocabulary.
  • Event model — the egress signal’s identity attributes.
  • Security model — where network egress enforcement sits in the layered defense.