Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.meshagent.com/llms.txt

Use this file to discover all available pages before exploring further.

ApiScope objects describe exactly which parts of the Rooms API a participant may call. They are carried inside the api grant of every ParticipantToken and are defined in meshagent.api.participant_token.ApiScope.

​
Built-in presets

MeshAgent ships three convenience constructors:
  • ApiScope.agent_default() – enables Livekit, Queues, Messaging, Dataset, Memory, Sync, Storage, Containers, Developer, Agents, LLM, Services, and Secrets access. Use ApiScope.agent_default(tunnels=True) to include the tunnels grant.
  • ApiScope.user_default() – enables the same core room access as agent_default(), but omits the LLM grant and still excludes Admin and Tunnels.
  • ApiScope.full() – everything in agent_default() plus the Admin and Tunnels grants.
Use these helpers when you want broad access, then override individual fields when you need to lock things down.

​
Scope fields

Each field is optional. Most fields treat None as “no restriction” for that capability. Tunnels are opt-in: when tunnels is None, tunnel access is denied.

​
livekit

LivekitGrant contains an optional breakout_rooms list. When provided, only the named breakout rooms can be joined; leaving it empty allows every breakout room (LivekitGrant.can_join_breakout_room).

​
queues

QueuesGrant exposes three controls:
  • send: list of queue names the participant may publish to (can_send checks membership; None means all queues).
  • receive: list of queues the participant may consume from (can_receive).
  • list: boolean flag gating QueuesClient.list operations (defaults to True).

​
messaging

MessagingGrant has simple booleans for broadcast, list, and send, all defaulting to True.

​
dataset

DatasetGrant manages table-level access:
  • tables: optional list of TableGrant entries (name, and booleans for read, write, alter). When omitted the participant may access every table.
  • list_tables: boolean (defaults to True).
  • Helper methods (can_read, can_write, can_alter) enforce the per-table flags.

​
memory

MemoryGrant controls room-memory access:
  • list: boolean controlling whether the participant may list memories.
  • memories: optional list of MemoryEntryGrant objects, each scoped by name and optional namespace.
  • Each memory entry has its own permissions object with booleans for create, drop, inspect, query, upsert, ingest, recall, and optimize.

​
sync

SyncGrant accepts paths: a list of SyncPathGrant { path, read_only }. Paths may end with * to match prefixes. When no paths are supplied, read and write access is global. can_read and can_write verify the constraints.

​
storage

StorageGrant mirrors the sync semantics but checks filesystem-style prefixes (path.startswith(...)). A read_only flag prevents writes on matching paths.

​
containers

ContainersGrant controls container management features:
  • use_containers: overall switch for container operations (defaults to True).
  • pull / run: optional allowlists of image tags; each entry can end with * to allow a prefix (can_pull / can_run).
  • logs: booleans toggling log streaming support.

​
developer

DeveloperGrant currently exposes a single logs boolean, enabling developer log forwarding when True.

​
tunnels

TunnelsGrant controls port-forwarding into room containers.
  • ports: optional list of allowed container ports. If omitted or empty, all ports are allowed. If tunnels is None, port forwarding is denied.

​
agents

AgentsGrant exposes boolean switches for registering agents or toolkits (register_agent, register_public_toolkit, register_private_toolkit) and for invoking the Agents API (call, use_agents, use_tools). They default to True to match the typical agent workflow.

​
admin

AdminGrant currently exposes a single config boolean. When True, the participant may use the admin configuration surface.

​
secrets

SecretsGrant lets a participant ask MeshAgent to exchange OAuth credentials. Provide a list of OAuthEndpoint { endpoint, client_id }. Wildcard suffixes (*) are supported (can_request_oauth_token).

​
services

ServicesGrant currently exposes a list boolean for service-listing operations in the room.

​
Examples

# Restrict a service to a single queue and read-only storage
api:
  queues:
    send: ["notifications"]
    receive: ["notifications"]
  storage:
    paths:
      - path: "/data/uploads"
        read_only: true

# Allow port forwarding only to container port 9000
api:
  tunnels:
    ports: ["9000"]

from meshagent.api.participant_token import ApiScope, QueuesGrant

scope = ApiScope(
    queues=QueuesGrant(send=["events"], receive=["events"])
)
Combine these snippets with the api field when packaging a service to set the appropriate permissions for your service.