> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set profile

> Create or replace a named permissions profile in the running workspace. Existing sessions keep their current permissions until explicitly updated. This does not change the saved workspace configuration.

> [accordion] Errors
>
> | Status | Meaning |
> | - | - |
> | `401` | The token is missing or wrong |
> | `404` | The workspace, session, job or file does not exist |
> | `422` | Validation Error |
> | `429` | Past a rate limit, or a new session past max\_sessions |
>
> See [error examples and recovery steps](https://docs.mirage.strukto.ai/api/errors.md). The [complete OpenAPI contract](https://github.com/strukto-ai/mirage/blob/main/docs/openapi.yaml) includes every response schema.


## OpenAPI

````yaml /openapi.yaml put /v1/workspaces/{workspace_id}/profiles/{name}
openapi: 3.2.0
info:
  title: Mirage API
  version: '0.1'
servers:
  - url: http://127.0.0.1:8765
    description: A local server on its default port
security:
  - bearerAuth: []
tags:
  - name: Workspace operations
    x-group: Workspaces
  - name: Workspaces
    x-group: Lifecycle
    parent: Workspace operations
  - name: Sessions
  - name: Shell
    parent: Workspace operations
  - name: VFS
    parent: Workspace operations
  - name: Tools
  - name: Documents
    x-group: Agent Instructions
    parent: Workspace operations
  - name: Snapshots
  - name: Templates
    parent: Configuration
  - name: Saved VFS
    x-group: VFS
    parent: Configuration
  - name: Saved CLIs
    x-group: CLI
    parent: Configuration
  - name: Saved runtimes
    x-group: Runtime
    parent: Configuration
  - name: Saved machines
    x-group: Machine
    parent: Configuration
  - name: Configuration
  - name: Policies
    parent: Configuration
  - name: Asks
    parent: Workspace operations
    x-group: Approval requests
  - name: Lines
    parent: Workspace operations
    x-group: Commands
  - name: Jobs
    parent: Workspace operations
  - name: Processes
    parent: Workspace operations
  - name: Machines
    parent: Workspace operations
  - name: Server
  - name: Service
    parent: Server
  - name: Daemon
    parent: Server
  - name: Auth
paths:
  /v1/workspaces/{workspace_id}/profiles/{name}:
    put:
      tags:
        - Workspaces
      summary: Set profile
      description: >-
        Create or replace a named permissions profile in the running workspace.
        Existing sessions keep their current permissions until explicitly
        updated. This does not change the saved workspace configuration.
      operationId: set_profile_v1_workspaces__workspace_id__profiles__name__put
      parameters:
        - $ref: '#/components/parameters/workspaceId'
        - name: name
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionProfile'
            example:
              cwd: /
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                name: analyst
              schema:
                type: object
                additionalProperties:
                  type: string
                title: >-
                  Response Set Profile V1 Workspaces  Workspace Id  Profiles 
                  Name  Put
components:
  parameters:
    workspaceId:
      name: workspace_id
      in: path
      required: true
      description: Workspace ID.
      schema:
        type: string
      example: demo
  schemas:
    SessionProfile:
      properties:
        cwd:
          anyOf:
            - type: string
            - type: 'null'
          title: Cwd
        env:
          anyOf:
            - additionalProperties:
                anyOf:
                  - type: string
                  - $ref: '#/components/schemas/EnvVar'
              type: object
            - type: 'null'
          title: Env
        mounts:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/ProfileMount'
              type: object
            - type: 'null'
          title: Mounts
        paths:
          anyOf:
            - $ref: '#/components/schemas/PathsBlock'
            - type: 'null'
        vars:
          anyOf:
            - $ref: '#/components/schemas/VarsBlock'
            - type: 'null'
        commands:
          anyOf:
            - $ref: '#/components/schemas/CommandsBlock'
            - type: 'null'
        policy:
          anyOf:
            - additionalProperties:
                items:
                  $ref: '#/components/schemas/ProfilePolicy'
                type: array
              propertyNames:
                enum:
                  - pre_execute
                  - pre_command
                  - pre_vfs
                  - pre_network
                  - post_execute
                  - post_command
                  - post_vfs
                  - post_network
              type: object
            - type: 'null'
          title: Policy
        command_limits:
          anyOf:
            - additionalProperties:
                $ref: '#/components/schemas/Limit'
              type: object
            - type: 'null'
          title: Command Limits
        processes:
          anyOf:
            - $ref: '#/components/schemas/ProcessPermissions'
            - type: 'null'
        network:
          anyOf:
            - type: boolean
            - additionalProperties:
                anyOf:
                  - items:
                      type: string
                    type: array
                  - additionalProperties:
                      type: string
                    type: object
              type: object
            - type: 'null'
          title: Network
      additionalProperties: false
      type: object
      title: SessionProfile
      description: >-
        Permissions and initial settings for a session. Unspecified settings add
        no restrictions beyond the workspace configuration.


        Use `commands`, `paths`, and `mounts` to control access, and `policy`
        for custom rules. For command rules without paths, deny takes precedence
        over approval requests and allow rules. More specific path rules take
        precedence over broader rules. See [permissions
        profiles](/home/policy/overview) for rule examples.
    EnvVar:
      properties:
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
        readonly:
          type: boolean
          title: Readonly
          default: false
        export:
          type: boolean
          title: Export
          default: true
        from:
          anyOf:
            - type: string
            - type: 'null'
          title: From
        ref:
          type: string
          title: Ref
          default: ''
        key:
          anyOf:
            - type: string
            - type: 'null'
          title: Key
        fetch:
          type: string
          enum:
            - lazy
            - eager
          title: Fetch
          default: lazy
      additionalProperties: false
      type: object
      title: EnvVar
      description: >-
        An environment variable with a literal `value` or a secret source
        identified by `from`, never both. Use `ref` and `key` to select a
        secret. `readonly` prevents commands from changing the variable. Managed
        secrets are always exported; literal values use the `export` setting.
    ProfileMount:
      properties:
        mode:
          anyOf:
            - $ref: '#/components/schemas/MountMode'
            - type: 'null'
        commands:
          anyOf:
            - $ref: '#/components/schemas/MountCommandsBlock'
            - type: 'null'
        paths:
          anyOf:
            - $ref: '#/components/schemas/PathsBlock'
            - type: 'null'
      additionalProperties: false
      type: object
      title: ProfileMount
      description: >-
        Optional permissions for a specific mount. A profile can reduce mount
        permissions but cannot increase them. Omitted mounts retain their
        configured permissions. Use path hiding to prevent access to a mount.
    PathsBlock:
      properties:
        hide:
          items:
            type: string
          type: array
          title: Hide
          default: []
        show:
          items:
            $ref: '#/components/schemas/ShowEntry'
          type: array
          title: Show
          default: []
        reasons:
          items:
            $ref: '#/components/schemas/HideReason'
          type: array
          title: Reasons
          default: []
      additionalProperties: false
      type: object
      title: PathsBlock
      description: >-
        Control which paths a session can access. `hide` makes matching paths
        appear not to exist. `show` exposes more specific paths inside hidden
        regions, optionally with reduced permissions. Exact paths include their
        descendants; patterns support `*`, `?`, and character classes.
    VarsBlock:
      properties:
        hide:
          items:
            type: string
          type: array
          title: Hide
          default: []
      additionalProperties: false
      type: object
      title: VarsBlock
      description: >-
        Environment variable names or glob patterns to hide from the session.
        Hidden variables appear unset.
    CommandsBlock:
      properties:
        allow:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Allow
        ask:
          items:
            $ref: '#/components/schemas/CommandRule'
          type: array
          title: Ask
          default: []
        deny:
          items:
            $ref: '#/components/schemas/CommandRule'
          type: array
          title: Deny
          default: []
      additionalProperties: false
      type: object
      title: CommandsBlock
      description: >-
        Command access rules. `allow` restricts available commands to matching
        patterns. `ask` requires approval, and `deny` blocks matching commands
        with a reason. If `allow` is omitted, it adds no restriction.
    ProfilePolicy:
      properties:
        script:
          anyOf:
            - $ref: '#/components/schemas/ScriptSource'
            - type: string
          title: Script
        runtime:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
          title: Runtime
          default: monty
        env:
          additionalProperties:
            anyOf:
              - type: string
              - $ref: '#/components/schemas/SecretRef'
          type: object
          title: Env
          default: {}
      additionalProperties: false
      type: object
      required:
        - script
      title: ProfilePolicy
      description: >-
        Custom policy programs, grouped by the method they handle. Provide a
        script, its runtime, and optional environment variables. If no runtime
        is specified, Monty is used and must be installed. Policy programs use
        their configured environment and can read session variables through
        `ctx["env"]`.
    Limit:
      properties:
        max_bytes:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Bytes
        max_lines:
          anyOf:
            - type: integer
              minimum: 0
            - type: 'null'
          title: Max Lines
        timeout_seconds:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Timeout Seconds
        walk_limit:
          anyOf:
            - type: integer
              minimum: -1
            - type: 'null'
          title: Walk Limit
        on_exceed:
          $ref: '#/components/schemas/OnExceed'
          default: truncate
      additionalProperties: false
      type: object
      title: Limit
      description: >-
        Limits for command output, execution time, and directory traversal. Use
        `on_exceed` to truncate results or return an error. A `walk_limit` of
        `-1` allows unlimited entries.
    ProcessPermissions:
      properties:
        list:
          type: string
          enum:
            - session
            - workspace
          title: List
          default: session
        kill:
          type: string
          enum:
            - session
            - workspace
          title: Kill
          default: session
        max:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max
          default: 128
      additionalProperties: false
      type: object
      title: ProcessPermissions
      description: >-
        Control which processes a session can list or stop, and the maximum
        number it can run. Sessions always have access to their own processes.
        The stop scope cannot exceed the list scope. Profile settings override
        workspace defaults.
    MountMode:
      type: string
      enum:
        - read
        - write
        - exec
      title: MountMode
      description: >-
        Mount access level. `read` allows listing and reading. `write` also
        allows creating, modifying, and deleting files. `exec` additionally
        allows interpreter commands such as `python3` and `js`.


        Interpreter script files must be on an `exec` mount. Inline code and
        module execution require at least one `exec` mount; imports are not
        checked by path. Shell scripts follow the permissions of each command
        they run.
    MountCommandsBlock:
      properties:
        ask:
          items:
            $ref: '#/components/schemas/CommandRule'
          type: array
          title: Ask
          default: []
        deny:
          items:
            $ref: '#/components/schemas/CommandRule'
          type: array
          title: Deny
          default: []
      additionalProperties: false
      type: object
      title: MountCommandsBlock
      description: >-
        Approval and deny rules for commands working within this mount. Use
        session-level command rules for an allow list.
    ShowEntry:
      properties:
        path:
          title: Path
          type: string
        mode:
          anyOf:
            - $ref: '#/components/schemas/MountMode'
            - type: 'null'
      additionalProperties: false
      type: object
      required:
        - path
      title: ShowEntry
      description: >-
        An absolute path or anchored path pattern to expose within a hidden
        region. Optional `mode` reduces permissions for that path. If omitted,
        mount permissions apply.
    HideReason:
      properties:
        patterns:
          items:
            type: string
          type: array
          title: Patterns
        reason:
          type: string
          title: Reason
      additionalProperties: false
      type: object
      required:
        - patterns
        - reason
      title: HideReason
      description: >-
        An optional explanation for hidden paths. The explanation is available
        to operators, not to agents accessing the workspace. Hidden paths appear
        not to exist.
    CommandRule:
      properties:
        reason:
          type: string
          title: Reason
        commands:
          items:
            type: string
          type: array
          title: Commands
          default: []
        paths:
          items:
            type: string
          type: array
          title: Paths
          default: []
        mount:
          type: string
          title: Mount
          default: ''
      additionalProperties: false
      type: object
      required:
        - reason
      title: CommandRule
      description: >-
        Require approval or deny commands matching the specified patterns. A
        pattern such as `git push` matches that command and its arguments.
        Optional paths restrict the rule to matching files or directories. Rules
        under a mount apply only within that mount.
    ScriptSource:
      properties:
        source:
          title: Source
          type: string
        language:
          type: string
          enum:
            - python
            - js
          title: Language
          default: python
        module:
          type: boolean
          title: Module
          default: false
      additionalProperties: false
      type: object
      required:
        - source
      title: ScriptSource
      description: >-
        Embedded program source with a language and optional JavaScript module
        mode. Configuration files can reference `.py`, `.js`, or `.mjs` files;
        the loader embeds their contents. `.mjs` files use module mode for
        imports and top-level `await`.
    SecretRef:
      properties:
        from:
          type: string
          title: From
        ref:
          type: string
          title: Ref
          default: ''
        key:
          type: string
          title: Key
      additionalProperties: false
      type: object
      required:
        - from
        - key
      title: SecretRef
      description: >-
        Read a configuration value from a secret source using `from`, `ref`, and
        `key`. The available sources depend on where this reference is used.
        Secret-source configuration allows only bootstrap sources such as
        environment variables or dotenv files.
    OnExceed:
      type: string
      enum:
        - error
        - truncate
      title: OnExceed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        The server's token (MIRAGE_AUTH_TOKEN) or a JWT. A daemon in the default
        local mode with no token accepts requests without one.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.