Workload identity — local preview

A workload is the stable identity of an application, service, or bot, such as production/support-bot. Its model access policy lives in AI Gateway. Replicas enroll as separate instances of that workload and inherit the same policy, while keeping their own runtime credentials.

The recommended enrollment path works through HTTPS without a cloud-specific identity service, a human CLI login, or network-device enrollment. It is designed for VMs, containers, bare-metal hosts, and on-premises deployments. The current runtime supports local evaluation on Linux and macOS; Windows workload runtime is unavailable. Central MCP execution and trusted-issuer/OIDC federation remain pending work.

An administrator first configures model access and provisions protected files. Then the application entrypoint is:

tunnex workload run --config /run/secrets/tunnex/workload.json -- python agent.py

Replace python agent.py with your application command. The preview wrapper enrolls an instance when needed, obtains a short-lived gateway token, and checks the permitted model list before starting the application. That check does not send a paid inference request or prove that an upstream model is reachable.

For compatible clients, the child receives OPENAI_BASE_URL and OPENAI_API_KEY pointing to an authenticated loopback endpoint. It also receives ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY for native messages. The remote token stays in the wrapper’s memory. Applications with hardcoded endpoints must be configured to use these settings; compatibility with every SDK is not established.

In the control-plane dashboard:

1. Configure provider credentials and models in AI Gateway → Models & endpoints.
2. Open Access → Workloads and create a workload.
3. Select exact configured models and their supported modes. Optionally set a daily USD soft threshold.
4. Wait for access state Applied, then select the workload and use Connect application for its configuration and permitted model IDs.
5. Create an enrollment key and deliver its one-time secret through your deployment’s protected secret-provisioning mechanism.

An empty model selection grants no inference access. Pending or failed provisioning is not usable access. The gateway checks the current workload, instance, policy, and provider state on new model requests. AI viewers can inspect the configuration; changing access requires AI administration permission.

The soft threshold uses observed daily spend across the workload’s instances. Concurrent requests and delayed accounting can exceed it, so it is not a hard spending cap. Replacing a replica does not reset workload spend. Usage reports attribute combined replica usage to the stable workload.

The preview UI offers a Single instance key with one successful enrollment and 24-hour validity, or an Autoscaling deployment reusable key with a 30-day default and a maximum of 90 days. Its optional use cap counts total successful enrollments, not concurrent replicas. The autoscaling label describes the key type; it does not mean the deployment lifecycle is production-ready.

An enrollment key fixes the workload on the server. A caller cannot select a different organization or policy during enrollment. A reusable key holder can introduce new instances, so protect it even though enrolled instances subsequently authenticate with independent signing keys. The key is not proof of a particular physical host’s identity.

The configuration contains paths, not the raw enrollment secret:

{
  "server": "https://tunnex.example.com",
  "enrollment_key_file": "/run/secrets/tunnex/enrollment-key",
  "state_directory": "/var/lib/tunnex-workload"
}

Use your reachable Tunnex HTTPS origin for server, without an API path or URL credentials. HTTP is accepted only for loopback development. Check the downloaded server value if the dashboard is running at a local preview address.

Provision all paths as absolute paths accessible to the unprivileged application user. The configuration and enrollment key must be regular, non-symlink files with permissions 0600 or stricter. The state directory must be private, non-symlink, writable by that user, and mode 0700. Linux paths above are examples; choose equivalent private paths for macOS.

Each replica needs independent state storage. Containers can use the same path text with separate volumes; processes sharing a filesystem need different paths. Never copy an instance state directory into another replica or a container image. The CLI holds a process lock on that directory while running.

Kubernetes projected secrets commonly use symlinks. Copy them into private regular files through trusted deployment setup, such as an init container, before starting this preview. Keep raw keys out of command arguments, shell history, images, source control, and logs.

The downloaded configuration uses example Linux/container paths. Downloading it into Downloads does not create /run/secrets/tunnex. For a new local instance, save the one-time enrollment-key download as ~/Downloads/enrollment-key.txt and keep the configuration at ~/Downloads/workload.json.

Provision a private configuration using your actual home directory:

install -d -m 700 "$HOME/.config/tunnex/workloads/local-test"
install -m 600 "$HOME/Downloads/enrollment-key.txt" \
  "$HOME/.config/tunnex/workloads/local-test/enrollment-key"
python3 - <<'PYTHON'
import json, os
from pathlib import Path
base = Path.home() / ".config/tunnex/workloads/local-test"
assert (base / "enrollment-key").is_file(), "Download and install the enrollment key first"
config = json.loads((Path.home() / "Downloads/workload.json").read_text())
config["enrollment_key_file"] = str(base / "enrollment-key")
config["state_directory"] = str(base / "state")
with os.fdopen(os.open(base / "workload.json", os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600), "w") as output:
    output.write(json.dumps(config, indent=2) + "\n")
os.chmod(base / "workload.json", 0o600)
PYTHON
tunnex workload enroll --config "$HOME/.config/tunnex/workloads/local-test/workload.json"

Check the downloaded filename: if the browser saved it without .txt or with a numbered suffix, use that filename as the source of install. The installed filename must match enrollment_key_file. A lost one-time key cannot be read back; create a replacement through Enrollment keys.

After enrollment, run from the directory containing your application:

tunnex workload run --config "$HOME/.config/tunnex/workloads/local-test/workload.json" -- python3 agent.py

agent.py is an example application command, not a file generated by the download. Keep the same state directory for ordinary restarts. An offline instance means no recent authenticated contact; it does not mean its credential was revoked. Use Revoke in the Instances table or tunnex workload retire --config with this same configuration path for permanent removal.

Enrollment-key expiry, exhaustion, or key-only revocation prevents new joins; already enrolled instances have independent credentials. To replace a reusable key, create a new key, provision it for future replicas, verify a fresh enrollment, and then revoke the old key. Preserve the original key and private state while recovering an enrollment whose response was lost.

Already admitted requests may finish. Revoking one instance cannot stop someone with a valid reusable key from enrolling another. After workload re-enablement, fresh tokens are required; revoked instances remain revoked.

Disabling also permanently revokes all enrollment keys for the workload. Issue a replacement key before introducing fresh replicas after re-enabling it. The confirmation explains this effect, and key state refreshes after access changes.

Ordinary completion, crashes and supervisor restarts preserve the enrolled instance. Reuse its private state directory to authenticate without another enrollment. A replacement replica uses independent state and enrolls separately. For permanent removal, stop the application and explicitly retire its instance:

tunnex workload retire --config /run/secrets/tunnex/workload.json

Retirement blocks reuse of that state. If its response is lost after the server commits retirement, retries cannot authenticate with the retired credentials. The CLI reports unconfirmed remote retirement. An AI administrator must check the workload’s Instances tab and revoke the instance there if still active. Do not delete private state or automatically reenroll to bypass revocation.

The application host must reach the configured Tunnex HTTPS origin. The gateway’s model connection must reach its provider endpoint. Workload enrollment creates no VPN tunnel or private route: a private provider needs an existing network path from the gateway infrastructure. A connector is needed only where that path is otherwise missing. Existing managed AI agents remain a separate host and networking workflow.

The wrapper forwards supported AI routes only. It does not honor proxy environment settings and removes HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY from the child’s environment. Tunnex policy governs calls through Tunnex; programs using unrelated credentials can still call other endpoints unless host network controls prevent them.

The following limits are unresolved in this preview:

• Retirement confirmation: lost responses after retirement commits require administrative status confirmation, as described above.
• Authentication recovery: bounded retries cover transient 429, 502, 503 and 504 responses and retain an unexpired token where possible. Confirmed 401/403 refusals remain terminal. Tokens never remain valid past their expiry, and retry handling does not guarantee uninterrupted access during an outage.
• Long responses: the current upstream request timeout is 35 seconds, including streams.
• Qualification: local restart and replica replacement are verified; multiple API replicas, production platform lifecycles and failover remain incomplete.
• Pending capabilities: central MCP tool execution, trusted-issuer federation, scheduled instance-key rotation, and Windows runtime are not available.

For the canonical implementation record, use the local core repository branch story/S-AI-workload-identity: docs/workload-model-access.md describes current behavior, docs/S-AI-workload-identity-decisions.md records approved intent, and docs/S-AI-workload-enrollment-research.md contains the source research. Those local records include future behavior; they do not establish published availability.