Workspaces
How a Workspace scopes tenancy, identity, registry resources, and the client endpoint in Orca Agent Engine.
A Workspace is the isolation unit for Orca Agent Engine. It scopes the agents you deploy, the registry resources they use, the identity boundaries that govern them, and the registry endpoint clients connect to. Different teams or projects each get their own Workspace.
What a Workspace contains
A Workspace holds two pillars:
- Runtime - harnesses and sandboxes for sessions, plus StreamNative Cloud functions over Pulsar or Kafka and connectors.
- Registry - agents, sessions, environments, files, vaults, skills, memory stores, and triggers, plus StreamNative Cloud providers, connections, packages, functions, and connectors.
On StreamNative Cloud, the Workspace resource also defines:
- The Pulsar and Kafka clusters the Workspace is bound to (
clusterRefs). - Legacy runner-image configuration (
runnerImages) retained for historical Agent Function deployments. - Its selected API surfaces (
cloud.streamnative.io/workspace-surfaces). - Its managed-agents PoolMember binding (
agentPoolMemberRef).
Where a Workspace is defined
On StreamNative Cloud, a Workspace is a Kubernetes custom resource (compute.streamnative.io/v1alpha1). You manage Workspaces with snctl, kubectl, or the Cloud Console. See the Workspace spec reference for Agent Engine field guidance. For non-agent Workspace topics (cluster binding, instance selection, billing scope), see the StreamNative Cloud Workspaces documentation.
On a self-hosted deployment, a Workspace is a registry record. An organization admin creates Workspaces and mints their API keys through the registry's admin listener. See Connect to the registry.
How the registry endpoint is exposed
On StreamNative Cloud, the Workspace controller copies the Functions Worker client endpoints into status.serviceEndpoints[]. Cloud CLI Workspace commands use a selected host to reach the Workspace API. Each entry has:
type:internal(cluster-local) orexternal(publicly reachable).dnsName: the DNS name clients can resolve to reach the registry.
Clients read this status and use the appropriate dnsName as the base URL for every Agent Engine API call. On a self-hosted deployment, clients use the URL where you expose the registry's public listener.
When to use multiple Workspaces
Use separate Workspaces when:
- Different business units or teams need isolated configuration, identity, and data scope.
- Production, staging, and development environments must be kept apart.
- Compliance boundaries require workload isolation.
A single Workspace is enough when all your agents share the same cluster bindings, identity policy, and data access rules.
Control registry access
Registry requests are associated with an authenticated Workspace. API keys resolve directly to a registry Workspace; configured OIDC tokens must resolve to one as well. The registry then limits resource queries to that Workspace, so the Workspace is the boundary to plan access control around.
Apply these practices to every registry credential:
- Treat every Workspace API key as full access. Assume that anyone who holds a key can read, change, and delete every registry resource in its Workspace. Handle OIDC tokens that the registry accepts for the Workspace with the same care.
- Isolate with separate Workspaces. Put teams and environments that need separate registry resource sets, such as production, staging, and development, in separate Workspaces. See When to use multiple Workspaces.
- Give each client its own key. Issue a separate credential to each automated client instead of sharing one key between clients. On a self-hosted deployment, an organization admin mints Workspace API keys on the registry's admin listener - see Connect to the registry.
- Rotate keys independently. Replace or revoke one client's key without touching the others.
- Test what a credential can do. Before a client depends on a credential, run the operations that client needs against the intended Workspace.