Profiles bundle default preferences and source overrides that the Run service applies to subsequent requests. Use these endpoints to list, create, update, select, and delete profiles. The active profile’s defaults are applied whenever a request does not explicitly set a field.

A profile configuration contains:

• name — Unique identifier for the profile
• description — Optional human-readable description
• defaults — Default selector values (OS, kind, source filter, pick mode, terminal session, display, limit)
• sources_mode — How the profile interacts with global sources: inherit (start from global sources and apply overrides) or allowlist (disable all sources first, then enable only those listed in sources)
• sources — Per-source overrides that enable, disable, or reprioritize sources
• policy — Security and integrity requirements

GET /api/v1/run/profiles

List all configured user profiles with their default preferences and source overrides.

This endpoint takes no parameters.

Response

200

Array of profile configurations.

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "defaults": {
      "os": "any",
      "kind": "any",
      "source": [],
      "pick": "ask"
    },
    "sources_mode": "inherit",
    "sources": [],
    "policy": {
      "require_verified": false,
      "require_integrity": false,
      "deny_providers": [],
      "deny_source_ids": []
    }
  },
  {
    "name": "work",
    "description": "Work profile: GUI only, verified packages",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "pick": "first",
      "limit": 10
    },
    "sources_mode": "allowlist",
    "sources": [
      {
        "source_id": "nixpkgs",
        "enabled": true,
        "priority": 100
      }
    ],
    "policy": {
      "require_verified": true,
      "require_integrity": true,
      "deny_providers": ["appimage"],
      "deny_source_ids": ["untrusted-pkgx"]
    }
  }
]

SDK Usage

SDK

const profiles = await client.run.profiles.listProfiles();

cURL

curl https://myproject-mycontainer-run-1.us-east-1.containers.hoody.icu/api/v1/run/profiles

POST /api/v1/run/profiles

Create a new user profile with default preferences and optional source overrides.

This endpoint takes no parameters.

Request Body

The request body follows the run_ProfileConfig schema.

Field	Type	Required	Description
name	string	Yes	Unique profile name
description	string	No	Human-readable profile description
defaults	object	No	Default selector values (OS, kind, source filter, pick mode, terminal session, display, limit)
sources_mode	string	No	inherit (start from global sources and apply overrides) or allowlist (disable all sources first, then enable only those listed in sources)
sources	array	No	Per-source overrides (default: []). Each entry has source_id (required), enabled, and priority.
policy	object	No	Security and integrity policy with require_verified, require_integrity, deny_providers, and deny_source_ids

Response

200

Updated list of all profiles.

[
  {
    "name": "default",
    "description": "Default profile (inherits global sources)",
    "sources_mode": "inherit",
    "sources": [],
    "policy": {}
  },
  {
    "name": "work",
    "description": "Work profile: GUI only, verified packages",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "pick": "first",
      "limit": 10
    },
    "sources_mode": "allowlist",
    "sources": [
      {
        "source_id": "nixpkgs",
        "enabled": true,
        "priority": 100
      }
    ],
    "policy": {
      "require_verified": true,
      "require_integrity": true,
      "deny_providers": ["appimage"],
      "deny_source_ids": ["untrusted-pkgx"]
    }
  }
]

400

{
  "error": "profile name is required",
  "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

409

{
  "error": "profile 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

503

{
  "error": "failed to save 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

SDK Usage

SDK

await client.run.profiles.createProfile({
  name: "work",
  description: "Work profile: GUI only, verified packages",
  defaults: {
    os: "linux",
    kind: "gui",
    source: ["nix"],
    pick: "first",
    limit: 10
  },
  sources_mode: "allowlist",
  sources: [
    {
      source_id: "nixpkgs",
      enabled: true,
      priority: 100
    }
  ],
  policy: {
    require_verified: true,
    require_integrity: true,
    deny_providers: ["appimage"],
    deny_source_ids: ["untrusted-pkgx"]
  }
});

cURL

curl -X POST https://myproject-mycontainer-run-1.us-east-1.containers.hoody.icu/api/v1/run/profiles \
  -H "Content-Type: application/json" \
  -d '{
    "name": "work",
    "description": "Work profile: GUI only, verified packages",
    "defaults": {
      "os": "linux",
      "kind": "gui",
      "source": ["nix"],
      "pick": "first",
      "limit": 10
    },
    "sources_mode": "allowlist",
    "sources": [
      { "source_id": "nixpkgs", "enabled": true, "priority": 100 }
    ],
    "policy": {
      "require_verified": true,
      "require_integrity": true,
      "deny_providers": ["appimage"],
      "deny_source_ids": ["untrusted-pkgx"]
    }
  }'

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

Set the given profile as the currently active profile. Its defaults are 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

Response

200

{
  "selected_profile": "work"
}

404

{
  "error": "profile not found",
  "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

503

{
  "error": "failed to save 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

SDK Usage

SDK

await client.run.profiles.selectProfile("work");

cURL

curl -X POST https://myproject-mycontainer-run-1.us-east-1.containers.hoody.icu/api/v1/run/profiles/work/select

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

The body is a partial profile configuration. Only the fields included in the request are merged into the existing profile; omitted fields are left unchanged. See the request body of Create Profile for the full field list.

Response

200

{
  "name": "work",
  "description": "Work profile: GUI only, verified packages (updated)",
  "defaults": {
    "os": "linux",
    "kind": "gui",
    "source": ["nix", "pkgx"],
    "pick": "first",
    "limit": 20
  },
  "sources_mode": "allowlist",
  "sources": [
    {
      "source_id": "nixpkgs",
      "enabled": true,
      "priority": 200
    }
  ],
  "policy": {
    "require_verified": true
  }
}

404

{
  "error": "profile not found",
  "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

503

{
  "error": "failed to save 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

SDK Usage

SDK

await client.run.profiles.updateProfile("work", {
  description: "Work profile: GUI only, verified packages (updated)",
  defaults: {
    source: ["nix", "pkgx"],
    limit: 20
  },
  sources: [
    { source_id: "nixpkgs", enabled: true, priority: 200 }
  ]
});

cURL

curl -X PATCH https://myproject-mycontainer-run-1.us-east-1.containers.hoody.icu/api/v1/run/profiles/work \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Work profile: GUI only, verified packages (updated)",
    "defaults": { "source": ["nix", "pkgx"], "limit": 20 },
    "sources": [{ "source_id": "nixpkgs", "enabled": true, "priority": 200 }]
  }'

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

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

Note

Deleting the currently active profile clears the selection. Subsequent requests will not have any profile defaults applied until a new profile is selected.

Parameters

Name	In	Type	Required	Description
profile	path	string	Yes	Profile name

Response

204

Profile deleted successfully. No content is returned.

404

{
  "error": "profile not found",
  "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

503

{
  "error": "failed to save 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

SDK Usage

SDK

await client.run.profiles.deleteProfile("work");

cURL

curl -X DELETE https://myproject-mycontainer-run-1.us-east-1.containers.hoody.icu/api/v1/run/profiles/work