# Run: Profiles

**Page:** api/run/profiles

[Download Raw Markdown](./api/run/profiles.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



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



Array of profile configurations.

```json
[
  {
    "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



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


```bash
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



Updated list of all profiles.

```json
[
  {
    "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"]
    }
  }
]
```


```json
{
  "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 |


```json
{
  "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 |


```json
{
  "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



```js
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"]
  }
});
```


```bash
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



```json
{
  "selected_profile": "work"
}
```


```json
{
  "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 |


```json
{
  "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



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


```bash
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



```json
{
  "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
  }
}
```


```json
{
  "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 |


```json
{
  "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



```js
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 }
  ]
});
```


```bash
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.


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



Profile deleted successfully. No content is returned.


```json
{
  "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 |


```json
{
  "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



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


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