Agent Runtime Profiles

Agent Runtime Profiles are reusable configuration records for agent work. A profile defines the runtime harness, allowed tools, connector grants, non-secret environment defaults, policy, and metadata that MIOSA applies when a sandbox, computer, or Agent Run asks for an agent profile.

Base path: /api/v1/agent-runtime-profiles

Use profiles when your product supports multiple agent runtimes such as OSA, Codex, Claude Code, Pi, Hermes, or a custom harness, but wants the same product-level flow: create a device, dispatch a run, stream progress, and export artifacts.

Endpoints

Method	Path	Description
`GET`	`/api/v1/agent-runtime-profiles`	List profiles for the tenant, optionally filtered by workspace
`POST`	`/api/v1/agent-runtime-profiles`	Create a profile
`GET`	`/api/v1/agent-runtime-profiles/{id}`	Fetch one profile
`PUT`	`/api/v1/agent-runtime-profiles/{id}`	Update a profile
`DELETE`	`/api/v1/agent-runtime-profiles/{id}`	Delete a profile

Runtime catalog

Runtime	Use it for
`osa`	MIOSA-native agents and platform operations
`codex`	Repo work, codebase edits, terminal-driven engineering
`claude-code`	Agentic coding loops with tool use and MCP
`pi`	Compatible harness-based agent execution
`hermes`	Custom or vendor-provided agent runtime
`custom`	Your own command, queue, model router, or prompt format

Create a profile

POST /api/v1/agent-runtime-profiles
Authorization: Bearer msk_live_...
Content-Type: application/json

{
  "workspace_id": "ws_123",
  "name": "Default app builder",
  "runtime": "claude-code",
  "description": "Builds apps in /workspace and exports deliverables.",
  "applies_to": { "resources": ["sandbox", "computer"] },
  "tools": ["files", "exec", "previews", "artifacts", "browser"],
  "connectors": ["refero/design-research", "anthropic/workspace-claude"],
  "env": {
    "ANTHROPIC_MODEL": "claude-sonnet-4.6",
    "MIOSA_AGENT_CWD": "/workspace"
  },
  "policy": {
    "approval": "confirm-risky",
    "max_child_sandboxes": 5
  },
  "metadata": {
    "product_agent": "app-builder"
  },
  "is_default": true
}

Request fields

Field	Type	Required	Description
`name`	string	yes	Human-readable profile name. Unique within the tenant/workspace scope.
`runtime`	string	yes	Runtime harness: `osa`, `codex`, `claude-code`, `pi`, `hermes`, or `custom`.
`workspace_id`	string	no	Scope the profile to a workspace. Omit for a tenant-level profile.
`description`	string	no	Operator-facing summary.
`applies_to`	object	no	Resource selectors such as `{ "resources": ["sandbox", "computer"] }`.
`tools`	string[]	no	Tool bundles the orchestrator may allow: files, exec, browser, previews, artifacts, deploy.
`connectors`	string[]	no	Managed or tenant-provided connector ids to grant through the broker.
`env`	object	no	Non-secret environment defaults. Run-level env overrides profile env.
`policy`	object	no	Approval, quota, child-device, and risk policy hints.
`metadata`	object	no	Product ids, labels, or rollout data.
`is_default`	boolean	no	Make this the default profile for the tenant or workspace scope.

Response

{
  "data": {
    "id": "arp_123",
    "workspace_id": "ws_123",
    "name": "Default app builder",
    "runtime": "claude-code",
    "description": "Builds apps in /workspace and exports deliverables.",
    "applies_to": { "resources": ["sandbox", "computer"] },
    "tools": ["files", "exec", "previews", "artifacts", "browser"],
    "connectors": ["refero/design-research", "anthropic/workspace-claude"],
    "env": {
      "ANTHROPIC_MODEL": "claude-sonnet-4.6",
      "MIOSA_AGENT_CWD": "/workspace"
    },
    "policy": {
      "approval": "confirm-risky",
      "max_child_sandboxes": 5
    },
    "metadata": {
      "product_agent": "app-builder"
    },
    "is_default": true,
    "created_at": "2026-06-15T14:00:00Z",
    "updated_at": "2026-06-15T14:00:00Z"
  }
}

Apply a profile

Profiles can be applied explicitly or resolved through tenant/workspace defaults.

{
  "agent_runtime_profile_id": "arp_123"
}

Resolution order:

Source	When it applies
`skip_agent_runtime_profile: true`	Do not apply any profile to this resource or run
`agent_runtime_profile_id` / `agent_profile_id`	Force a specific profile
Workspace default profile	Used when the resource belongs to a workspace with a default
Tenant default profile	Used when no workspace default applies

Run-level env overrides non-secret profile env. Connector credentials remain brokered through MIOSA and are not copied into profile metadata.