Core Concepts
Security Model
Tenant keys, agent tokens, permission tiers, pod isolation, and practical safety notes.
CommonOS separates human operators from agent runtimes.
Token Types
| Token | Holder | Scope |
|---|---|---|
cos_live_... | Tenant/operator | Full fleet control: create fleets, deploy agents, assign tasks, terminate agents. |
cos_agent_... | Agent pod | Runtime actions: emit events, pull own tasks, complete own tasks, bootstrap runtime, use scoped wallet routes. |
Permission Tiers
| Tier | Intended capabilities |
|---|---|
manager | Coordinate work and assign tasks to worker agents. |
worker | Execute assigned tasks and report state. |
Enforcement is partly route-based and partly convention in the current implementation. Keep sensitive operator actions behind tenant auth and avoid granting tenant keys to agent processes.
Runtime Isolation
Ordinary fleet agents retain their existing per-agent placement model. Agent computers use a stricter owner-tenant boundary:
- one opaque Kubernetes namespace and quota per canonical human owner
- one dedicated pod, scoped runtime token, and persistent claim per computer
- Pod Security admission labels, runtime-default seccomp, dropped Linux capabilities, no privilege escalation, and no service-account token mount
- default-deny ingress and egress NetworkPolicies; public HTTP(S) egress cannot reach private, link-local, or metadata ranges
- encrypted GCS FUSE or EFS-backed persistence; computers never fall back to
emptyDir
The EKS bootstrap enables VPC CNI NetworkPolicy enforcement. A sandboxed
RuntimeClass can be required with COMPUTER_RUNTIME_CLASS on clusters that
provide gVisor or Kata Containers.
Practical Safety
- Do not commit
.env.local, service account keys, or API keys. - Avoid putting
NEXT_PUBLIC_API_KEYin deployed public frontends. - Require a sandboxed runtime class before accepting arbitrary third-party container images in a hostile multi-tenant environment.
- Treat guest Docker images as untrusted code and constrain their runtime.
- Rotate tenant API keys if exposed.