Run: Profiles

Use the Profiles endpoints to manage named application profiles within a Hoody Run container. A profile bundles default preferences (operating system, app kind, source filter, candidate selection mode, terminal session, and so on) with optional source overrides and a sourcing policy. One profile can be selected as the active default; its defaults are then applied to subsequent requests that do not explicitly override them.

The endpoints below let you list existing profiles, create new ones, partially update them, switch the active profile, and delete profiles by name.

List profiles

`GET /api/v1/run/profiles`

Return every configured profile along with its default preferences and source overrides.

This endpoint takes no parameters.

cURL
TypeScript SDK

curl -X GET "https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/profiles" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.profiles.listProfiles();

Response

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": {
      "os": "any",
      "kind": "any",
      "source": ["any"],
      "pick": "ask",
      "limit": 20
    },
    "sources_mode": "inherit",
    "sources": [],
    "policy": {
      "require_verified": false,
      "require_integrity": false,
      "deny_providers": [],
      "deny_source_ids": []
    }
  },
  {
    "name": "workstation",
    "description": "GUI-focused profile pinned to Linux package sources",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix", "appimage"],
      "pick": "first"
    },
    "sources_mode": "allowlist",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 10 }
    ],
    "policy": {
      "require_verified": true,
      "deny_providers": ["system"]
    }
  }
]

Create a profile

`POST /api/v1/run/profiles`

Create a new user profile with default preferences and optional source overrides. Returns the updated list of all profiles.

This endpoint takes no parameters.

Request Body

A request body is required. See the run_ProfileConfig schema in the referenced schemas section for the supported fields. The name field is required.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/profiles" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "workstation",
    "description": "GUI-focused profile pinned to Linux package sources",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix", "appimage"],
      "pick": "first"
    },
    "sources_mode": "allowlist",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 10 }
    ]
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.profiles.createProfile({
  name: 'workstation',
  description: 'GUI-focused profile pinned to Linux package sources',
  defaults: {
    os: 'linux',
    kind: 'gui',
    source: ['nix', 'appimage'],
    pick: 'first'
  },
  sources_mode: 'allowlist',
  sources: [
    { source_id: 'nixpkgs', enabled: true, priority: 10 }
  ]
});

Response

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": { "os": "any", "kind": "any", "source": ["any"], "pick": "ask", "limit": 20 },
    "sources_mode": "inherit",
    "sources": [],
    "policy": { "require_verified": false, "require_integrity": false, "deny_providers": [], "deny_source_ids": [] }
  },
  {
    "name": "workstation",
    "description": "GUI-focused profile pinned to Linux package sources",
    "defaults": { "os": "linux", "kind": "gui", "source": ["nix", "appimage"], "pick": "first" },
    "sources_mode": "allowlist",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 10 }
    ],
    "policy": { "require_verified": false, "require_integrity": false, "deny_providers": [], "deny_source_ids": [] }
  }
]

{
  "error": "Profile configuration must include a non-empty name",
  "code": 400
}

Error Code	Title	Description	Resolution
`MISSING_PROFILE_NAME`	Missing profile name	The profile configuration did not include a non-empty name	Set `name` before creating the profile

{
  "error": "A profile named 'workstation' already exists",
  "code": 409
}

Error Code	Title	Description	Resolution
`PROFILE_ALREADY_EXISTS`	Profile already exists	A profile with the same name already exists	Choose a unique profile name or update the existing profile instead

{
  "error": "Failed to persist updated profile configuration",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry

Update a profile

`PATCH /api/v1/run/profiles/{profile}`

Partially update a profile configuration. Supports merging description, defaults, sources_mode, and sources fields.

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name

Request Body

A request body is required. See the run_ProfileConfig schema in the referenced schemas section for the supported fields. Only include the fields you want to change.

cURL
TypeScript SDK

curl -X PATCH "https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/profiles/workstation" \
  -H "Authorization: Bearer $HOODY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "GUI-focused profile pinned to Linux package sources (verified only)",
    "policy": {
      "require_verified": true,
      "deny_providers": ["system"]
    }
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.profiles.updateProfile('workstation', {
  description: 'GUI-focused profile pinned to Linux package sources (verified only)',
  policy: {
    require_verified: true,
    deny_providers: ['system']
  }
});

Response

{
  "name": "workstation",
  "description": "GUI-focused profile pinned to Linux package sources (verified only)",
  "defaults": { "os": "linux", "kind": "gui", "source": ["nix", "appimage"], "pick": "first" },
  "sources_mode": "allowlist",
  "sources": [
    { "source_id": "nixpkgs", "enabled": true, "priority": 10 }
  ],
  "policy": {
    "require_verified": true,
    "require_integrity": false,
    "deny_providers": ["system"],
    "deny_source_ids": []
  }
}

{
  "error": "No profile named 'workstation' exists",
  "code": 404
}

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `listProfiles` and choose a valid profile name

{
  "error": "Failed to persist updated profile configuration",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry

Select the active profile

`POST /api/v1/run/profiles/{profile}/select`

Set the named profile as the currently active profile. Its defaults will be applied to all subsequent requests that do not explicitly override them.

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name to select

This endpoint takes no request body.

cURL
TypeScript SDK

curl -X POST "https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/profiles/workstation/select" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.profiles.selectProfile('workstation');

Response

{
  "selected_profile": "workstation"
}

{
  "error": "No profile named 'workstation' exists",
  "code": 404
}

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `listProfiles` and choose a valid profile name

{
  "error": "Failed to persist updated profile selection",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile selection could not be persisted	Check storage health and retry

Delete a profile

`DELETE /api/v1/run/profiles/{profile}`

Remove a profile by name. If the deleted profile was the selected profile, the selection is cleared.

Parameters

Name	In	Type	Required	Description
`profile`	path	string	Yes	Profile name

This endpoint takes no request body.

cURL
TypeScript SDK

curl -X DELETE "https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com/api/v1/run/profiles/workstation" \
  -H "Authorization: Bearer $HOODY_TOKEN"

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-run-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.run.profiles.deleteProfile('workstation');

Response

The profile was deleted successfully. The response has no body.

{
  "error": "No profile named 'workstation' exists",
  "code": 404
}

Error Code	Title	Description	Resolution
`PROFILE_NOT_FOUND`	Profile not found	No profile exists with the requested name	Call `listProfiles` and choose a valid profile name

{
  "error": "Failed to persist updated profile configuration",
  "code": 503
}

Error Code	Title	Description	Resolution
`CONFIG_SAVE_FAILED`	Configuration save failed	The updated profile configuration could not be persisted	Check storage health and retry

Referenced schemas

The run_ProfileConfig schema referenced by the create and update endpoints is composed of the following nested objects. Use these as a reference when constructing request bodies; only the fields marked required must be present.

`run_ProfileConfig`

Field	Type	Required	Description
`name`	string	Yes	Unique profile name
`description`	string	No	Human-readable profile description
`defaults`	`run_ProfileDefaults`	No	Default selector values applied when the profile is active
`sources_mode`	`run_ProfileSourceMode`	No	How the profile interacts with the global source list
`sources`	array of `run_ProfileSourceOverride`	No	Per-source overrides (enable/disable/reprioritize). Default: `[]`
`policy`	`run_PolicyConfig`	No	Sourcing policy applied while this profile is active

`run_ProfileDefaults`

Field	Type	Required	Description
`os`	`run_Os`	No	Target app runtime OS (not the host OS). One of `linux`, `windows`, `any`
`kind`	`run_AppKind`	No	Application kind filter. One of `gui`, `cli`, `any`
`source`	array of `run_SourceKind`	No	Default source filter. One of `nix`, `pkgx`, `appimage`, `oci`, `registry`, `system`, `any`. Default: `[]`
`pick`	`run_PickMode`	No	Candidate selection mode. One of `ask`, `first`, `index`, `id`
`terminal_id`	integer	No	Default terminal session ID. Range: `1` to `65535`
`display`	string	No	Default X11 DISPLAY number
`limit`	integer	No	Default maximum candidates to return. Range: `1` to `100`

`run_ProfileSourceOverride`

Field	Type	Required	Description
`source_id`	string	Yes	ID of the source to override
`enabled`	boolean	No	Override enabled state
`priority`	integer	No	Override priority

`run_PolicyConfig`

Field	Type	Required	Description
`require_verified`	boolean	No	Require verified sources
`require_integrity`	boolean	No	Require integrity-checked sources
`deny_providers`	array of `run_SourceKind`	No	Providers to deny. Default: `[]`
`deny_source_ids`	array of string	No	Specific source IDs to deny. Default: `[]`

`run_PickMode`

Selection mode for candidates:

ask: return candidate list without selecting (default)
first: automatically select the highest-ranked candidate
index: select by 0-based index (requires pick_index)
id: select by candidate_id (requires candidate_id)

`run_ProfileSourceMode`

How a profile interacts with the global source list:

inherit: start from global sources, apply overrides
allowlist: disable all sources first, then enable only those listed in the profile’s sources array

`run_ApiError`

Standard JSON error payload returned for validation, lookup, and persistence failures.

Field	Type	Required	Description
`error`	string	Yes	Human-readable error message
`code`	integer	Yes	HTTP status code associated with the error

`run_SelectedProfileResponse`

Field	Type	Required	Description
`selected_profile`	string	Yes	Name of the active profile