[RFC] Role-Based Access Control for the Agent Canvas

Problem / Motivation

Agent Canvas currently uses a shared session API key that effectively grants administrator-level access. In a typical local stack, that credential is reused across the browser, Agent Server, automation backend, and automation run environments.

That is workable for one trusted developer, but it prevents a developer from safely sharing an always-on Canvas instance with a team. Anyone who can observe conversations or automations also receives the authority to run agents, change settings, access credentials, use host file and shell surfaces, and administer the instance. Actions are also difficult to attribute reliably to a person, automation, or internal service.

We would like feedback on an open-source, instance-local authorization model that creates a safe middle ground between a personal Canvas and a fully governed enterprise deployment.

The intended boundary is:

• Open source provides API-key identity, fixed roles, scoped service actors, resource attribution, and backend-enforced capabilities for a single Canvas instance.

This is a cross-repository proposal. The Agent Server and SDK must own authorization enforcement; Canvas should consume capabilities and adapt the UI, never act as the security boundary.

Desired Behavior

A self-hosted operator can grant separate credentials with one of three fixed roles:

Experience	Read	Run	Admin
Observe conversations and automations	Yes	Yes	Yes
Start and guide agent work	No	Yes	Yes
Trigger permitted automations	No	Yes	Yes
Manage profiles, customizations, and secrets	No	No	Yes
Manage access and trusted infrastructure	No	No	Yes
Use unrestricted host terminal/file APIs	No	No	Yes

The roles would be fixed capability bundles:

• Read can observe permitted conversations, events, automation metadata, and workspace artifacts, but cannot mutate state or initiate execution.
• Run adds controlled conversation and automation execution, but cannot administer settings, credentials, access policy, trusted roots, or raw host shell/file APIs.
• Admin adds instance administration, credential management, access management, trusted-root configuration, and privileged host operations.

Internal actors such as the automation service, an individual automation run, secret resolution, callbacks, and workspace-file access should receive narrowly scoped capabilities and audiences instead of impersonating a human role or inheriting a permanent Admin key.

Authorization must be enforced by the relevant backend on every owned HTTP operation and WebSocket message type. Canvas should use an authenticated identity endpoint such as GET /api/auth/whoami as its capability source, guard direct routes, and hide or disable actions that the current principal cannot perform. UI controls are an affordance, not enforcement.

Proposed rollout

1. Security hardening before roles

   • Make authentication mode explicit (disabled, static, or managed) and fail closed when an enabled mode has no keys.
   • Use constant-time credential verification.
   • Restrict workspaces to administrator-configured, symlink-aware trusted roots.
   • Separate automation encryption/signing material from the session credential.

2. Static Read and Admin credentials

   • Introduce framework-neutral principal and capability decisions in the SDK, with Agent Server HTTP/WebSocket adapters.
   • Add fail-closed policy inventories and CI coverage for all backend operations and WebSocket messages.
   • Expose the current role and capabilities through whoami.
   • Add Canvas capability state, guarded routes, and role-aware controls.
   • Preserve compatibility by treating existing session keys as Admin during migration.

3. Named credentials and service delegation

   • Store named credential metadata, keyed hashes, expiry/revocation state, parent/delegation relationships, and audit records in the Agent Server.
   • Give automation its own scoped service identity and use short-lived, resource-scoped credentials for runs and callbacks.
   • Make revocation and expiry effective for HTTP, cached service decisions, workspace access, and already-open WebSocket connections within a documented bound.
   • Migrate existing automation ownership without hiding or orphaning resources.

4. Run role

   • Ship Run only when stored credentials are resolved server-side or carried in destination-bound sealed configuration.
   • Prevent a Run caller from retrieving stored credential values directly or transplanting encrypted credential material to a caller-controlled destination.
   • Keep raw host shell and arbitrary-path file APIs Admin-only.
   • Replace the long-lived raw-key workspace cookie with short-lived, conversation-bound workspace authorization.

Security boundaries and explicit non-goals

This proposal does not claim that Read is a confidentiality boundary for existing agent output. Conversation transcripts and tool observations may already contain source code, terminal output, credentials, or other sensitive material.

It also does not prevent a Run user from asking an allowed agent to print a credential that the selected server-side profile makes available inside the agent sandbox. Run is intended to prevent direct credential retrieval and redirection through APIs; sandbox isolation and agent-level secret handling remain separate security problems.

Other non-goals for the open-source design are user accounts/passwords, SSO/OIDC/SAML, per-conversation or per-automation human ACLs, multi-node tenancy, and a tamper-proof external compliance ledger.

---

This issue is initially an RFC rather than a single implementation task. It is ready to split into repository-specific work when:

• The community and maintainers agree on the Read, Run, and Admin boundaries and their atomic capability bundles.
• The OSS/Enterprise boundary is documented: OSS owns instance-local roles and actors; enterprise systems may supply organization-scale identity, policy, and governance.
• Every Agent Server, automation, and WebSocket operation has an owning repository and a fail-closed policy-classification strategy.
• The trusted-workspace model, destination-bound credential model, and Admin-only raw shell/file boundary are agreed upon.
• The durable-key, short-lived internal-token, service-delegation, and live-revocation approaches have documented security properties and limits.
• Automation ownership migration and the handling of existing keys, cookies, open sockets, and in-flight runs are specified.
• Adversarial tests cover Read mutation attempts, Run credential retrieval/transplant attempts, workspace escapes, WebSocket authorization, service delegation, revocation/expiry, audit failure, and unclassified operations.
• Follow-up implementation issues are created in the repositories that own each change, with independently testable acceptance criteria.

Alternatives Considered

Keep one shared administrator key

This preserves today's simplicity, but it cannot support viewers or operators with bounded authority and leaves automation runs holding permanent administrator-equivalent credentials.

Add identity without authorization

Named profiles would improve attribution, but every participant would still have the same effective access. Identity alone does not make a shared instance safe.

Additional Context

Feedback requested

We are especially interested in feedback on:

1. Are Read, Run, and Admin the right fixed roles for self-hosted team use? Which capability boundaries are surprising or missing?
2. How strong is the demand for team RBAC with user attribution?

Repository ownership

Repository	Responsibility
OpenHands/software-agent-sdk	Principal/capability model, Agent Server enforcement, HTTP/WebSocket policy inventory, keys, tokens, audit, trusted workspaces
OpenHands/automation	Automation route enforcement, service identity, dispatch/run delegation, ownership migration
OpenHands/typescript-client	Typed access to the resulting Agent Server contract
OpenHands/OpenHands	Canvas capability provider, guarded routes and actions, role-aware UX, launcher compatibility and cross-repository integration tests

The implementation should be staged across those repositories. This issue is intended to align the public contract and security boundaries before individual development issues are marked ready for contribution.