Set a profile

curl --request PUT \
  --url http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cwd": "<string>",
  "env": {},
  "mounts": {},
  "paths": {
    "hide": [],
    "show": [],
    "reasons": []
  },
  "vars": {
    "hide": []
  },
  "commands": {
    "allow": [
      "<string>"
    ],
    "ask": [],
    "deny": []
  },
  "policy": {},
  "command_limits": {},
  "processes": {
    "list": "session",
    "kill": "session",
    "max": 128
  },
  "network": true
}
'

import requests

url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}"

payload = {
    "cwd": "<string>",
    "env": {},
    "mounts": {},
    "paths": {
        "hide": [],
        "show": [],
        "reasons": []
    },
    "vars": { "hide": [] },
    "commands": {
        "allow": ["<string>"],
        "ask": [],
        "deny": []
    },
    "policy": {},
    "command_limits": {},
    "processes": {
        "list": "session",
        "kill": "session",
        "max": 128
    },
    "network": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cwd: '<string>',
    env: {},
    mounts: {},
    paths: {hide: [], show: [], reasons: []},
    vars: {hide: []},
    commands: {allow: ['<string>'], ask: [], deny: []},
    policy: {},
    command_limits: {},
    processes: {list: 'session', kill: 'session', max: 128},
    network: true
  })
};

fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'cwd' => '<string>',
    'env' => [
        
    ],
    'mounts' => [
        
    ],
    'paths' => [
        'hide' => [
                
        ],
        'show' => [
                
        ],
        'reasons' => [
                
        ]
    ],
    'vars' => [
        'hide' => [
                
        ]
    ],
    'commands' => [
        'allow' => [
                '<string>'
        ],
        'ask' => [
                
        ],
        'deny' => [
                
        ]
    ],
    'policy' => [
        
    ],
    'command_limits' => [
        
    ],
    'processes' => [
        'list' => 'session',
        'kill' => 'session',
        'max' => 128
    ],
    'network' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}"

	payload := strings.NewReader("{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}"

response = http.request(request)
puts response.read_body

{}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

Set a profile

curl --request PUT \
  --url http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cwd": "<string>",
  "env": {},
  "mounts": {},
  "paths": {
    "hide": [],
    "show": [],
    "reasons": []
  },
  "vars": {
    "hide": []
  },
  "commands": {
    "allow": [
      "<string>"
    ],
    "ask": [],
    "deny": []
  },
  "policy": {},
  "command_limits": {},
  "processes": {
    "list": "session",
    "kill": "session",
    "max": 128
  },
  "network": true
}
'

import requests

url = "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}"

payload = {
    "cwd": "<string>",
    "env": {},
    "mounts": {},
    "paths": {
        "hide": [],
        "show": [],
        "reasons": []
    },
    "vars": { "hide": [] },
    "commands": {
        "allow": ["<string>"],
        "ask": [],
        "deny": []
    },
    "policy": {},
    "command_limits": {},
    "processes": {
        "list": "session",
        "kill": "session",
        "max": 128
    },
    "network": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    cwd: '<string>',
    env: {},
    mounts: {},
    paths: {hide: [], show: [], reasons: []},
    vars: {hide: []},
    commands: {allow: ['<string>'], ask: [], deny: []},
    policy: {},
    command_limits: {},
    processes: {list: 'session', kill: 'session', max: 128},
    network: true
  })
};

fetch('http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => json_encode([
    'cwd' => '<string>',
    'env' => [
        
    ],
    'mounts' => [
        
    ],
    'paths' => [
        'hide' => [
                
        ],
        'show' => [
                
        ],
        'reasons' => [
                
        ]
    ],
    'vars' => [
        'hide' => [
                
        ]
    ],
    'commands' => [
        'allow' => [
                '<string>'
        ],
        'ask' => [
                
        ],
        'deny' => [
                
        ]
    ],
    'policy' => [
        
    ],
    'command_limits' => [
        
    ],
    'processes' => [
        'list' => 'session',
        'kill' => 'session',
        'max' => 128
    ],
    'network' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}"

	payload := strings.NewReader("{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/v1/workspaces/{workspace_id}/profiles/{name}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Put.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"cwd\": \"<string>\",\n  \"env\": {},\n  \"mounts\": {},\n  \"paths\": {\n    \"hide\": [],\n    \"show\": [],\n    \"reasons\": []\n  },\n  \"vars\": {\n    \"hide\": []\n  },\n  \"commands\": {\n    \"allow\": [\n      \"<string>\"\n    ],\n    \"ask\": [],\n    \"deny\": []\n  },\n  \"policy\": {},\n  \"command_limits\": {},\n  \"processes\": {\n    \"list\": \"session\",\n    \"kill\": \"session\",\n    \"max\": 128\n  },\n  \"network\": true\n}"

response = http.request(request)
puts response.read_body

{}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

{
  "detail": "<unknown>",
  "errno": "<string>",
  "refusal": {}
}

Authorizations

Authorization

string

header

required

The server's token (MIRAGE_AUTH_TOKEN) or a JWT. A daemon in the default local mode with no token accepts requests without one.

Path Parameters

workspace_id

string

required

The workspace's id.

name

string

required

Body

application/json

One profile: the whole permission document a session runs under.

A session is created from exactly one of these, and it is the only place permissions are written. There is no workspace-wide block and no mount-owned block above it, so reading this object is reading everything the profile may do; what a profile does not say, it does not restrict. Configuration, not enforcement: the resolver compiles it onto the session's narrowing fields and the entry points keep enforcing. Deliberately not named a View, which per the view convention is a handle an agent holds on one entry point, while a profile is what the embedder uses to define one. Frozen so two agents with the same profile share one object and neither can bend the other's view.

Two rules decide a line against it, and they are the whole law. A rule naming no path is read by verb (deny before ask before allow), wherever it is written. A rule carrying paths, and every hide, is read by anchor depth: the deeper entry wins, ties break by verb.

A profile may also state a policy: for each pre_ method it answers at (pre_execute, pre_command, pre_vfs, pre_session), a list of programs, each with the runtime it runs on (ProfilePolicy, the shape a clis entry has). A program's function for the method takes its context and returns its answer: None for no opinion, a deny, an ask, or at pre_execute a route. They are asked in order and the first deny wins, so a policy expresses the conditions a declarative rule cannot; like every policy, it can only restrict, never grant past a deny. The document is optional beside it: a profile stating only a policy hides nothing, and the policy is its whole admission policy.

Args: cwd (str | None): the session's working directory at creation. env (dict[str, str | EnvVar] | None): the env entries seeded into the session at creation, in the workspace env grammar: a bare string is an exported literal, and a from: entry a managed pointer, so a credential is named here and fetched, never written as its value. mounts (dict[str, ProfileMount] | None): per-mount settings, keyed by prefix: a mode, ask and deny rules for lines working inside the mount, and hides under it. A mount the mapping omits keeps its own mode and gains no rules. paths (PathsBlock | None): the profile's hides, absolute. vars (VarsBlock | None): the profile's hidden variables. commands (CommandsBlock | None): the profile's allow list and its ask / deny rules, absolute paths. policy (dict[ScriptMethod, list[ProfilePolicy]] | None): the profile's policy: each pre_ method's programs, asked in order. network (bool | dict[str, list[str]] | None): where the session's lines may connect, the workspace's network grammar, held besides the workspace's own; None leaves the workspace's alone.

cwd

string | null

env

Env · object | null

Show child attributes

mounts

Mounts · object | null

Show child attributes

paths

PathsBlock · object | null

paths: of a profile, or of one of its mount sections.

hide entries use the document's one grammar: an entry with *, ? or [ is a pattern, anything else an exact path and its subtree (utils/hidden.classify_paths); every entry holds a token and is absolute or a name pattern, wherever the block is written. A hide entry may also be a group {patterns: [...], reason: ...}: the patterns join the flat list like any other entry and the reason lands in reasons, the operator-only side table (:class:HideReason).

show is the other half of the path axis: a mapping of path to mode ({"/repo/docs": r}), or a plain list whose entries inherit the mount's mode. Every entry is absolute, a subtree or an anchored pattern, because a show anchors to a place and a name pattern names none. An entry re-opens its subtree inside a hidden region when its anchor is deeper than the hide's, and states the mode in force below its anchor when it carries one; both on the one anchor-depth rule.

Args: hide (tuple[str, ...]): what the profile makes nonexistent. show (tuple[ShowEntry, ...]): the profile's show entries, in document order. reasons (tuple[HideReason, ...]): why grouped hide entries exist, for the operator's entry points only.

Show child attributes

vars

VarsBlock · object | null

vars: of a profile.

Args: hide (tuple[str, ...]): variable names or globs over names the session reads as unset.

Show child attributes

commands

CommandsBlock · object | null

commands: at the top level of a profile.

allow lists the command patterns the profile allows; a line no pattern covers is refused, <cmd>: Permission denied at 126, like any other rule's Deny. Shell builtins are subjects like everything else: a list stating only cat refuses echo and cd. The agent's own functions are the one exemption, safe because every line of a body passes the gate itself. ask rules are admitted only with a host approval; deny rules refuse with a reason. A bare string in either is one command pattern with the default reason.

Args: allow (tuple[str, ...] | None): the profile's allow patterns; None (unstated) allows everything. ask (tuple[CommandRule, ...]): what needs sign-off, in order. deny (tuple[CommandRule, ...]): the profile's refusals, in order.

Show child attributes

policy

Policy · object | null

Show child attributes

command_limits

Command Limits · object | null

Show child attributes

processes

ProcessPermissions · object | null

How far past its own session a profile reaches into processes.

A session always sees and stops its own processes. list widens what ps and a handler's process view see; kill widens what they may stop, and never past list. max caps the live processes the session holds, its running line included, as ulimit -u counts the shell. A bare scope sets both. The workspace states one for every session and a profile's overrides it field by field (layered).

Args: list (ProcessScope): whose processes the session sees. kill (ProcessScope): whose processes the session may stop. max (int | None): most live processes, MAX_PROCESSES unless stated, None for no cap.

Show child attributes

network

Response

{key}

string