> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://rivet.chrisboulton.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://rivet.chrisboulton.com/_mcp/server.

# Resource conventions

> Defaults, unmanaged properties, strict types, and exported attributes.

Every resource declares one host object, or one command, under a label. Labels can differ from physical names/paths. Rivet rejects conflicting physical ownership, including conflicts between package providers or membership policies.

Approved [executable plugins](/contributing/plugins) can add resource types and service and package backends. Their declarations follow the same metadata, ownership, capability, and verification rules; each installed definition supplies its schema and static exports.

## Managed and unmanaged properties

A default such as `ensure = "present"` defines desired state. An omitted optional property often means **unmanaged**: Rivet preserves what exists. The per-resource tables distinguish these cases. Explicit null acts as omission only when that field permits null.

A file's omitted mode preserves an existing mode but uses 0644 on creation. A service's omitted activity, enablement, and mask remain unmanaged. User creation uses distribution defaults for omitted fields; omitted existing-user properties remain unmanaged.

`ensure` is a resource-specific vocabulary, not a generic command:

| Resource                        | Accepted values                                                    | Omitted value                      |
| ------------------------------- | ------------------------------------------------------------------ | ---------------------------------- |
| File                            | `file`, `directory`, `symlink`, `absent`; `present` aliases `file` | `file`                             |
| Package                         | `present`, `latest`, `absent`, `purged`; dpkg rejects `latest`     | `present`                          |
| User / group / group membership | `present`, `absent`                                                | `present`                          |
| Service                         | `running`, `stopped`; `state` aliases the field                    | Activity unmanaged                 |
| Timer / SSH key                 | `present`, `absent`                                                | `present`                          |
| Mount                           | Uses `state`: mounted, unmounted, absent                           | `mounted`                          |
| Exec                            | No ensure field                                                    | Explicit execution policy required |

Explicit null is rejected for non-service ensure policies. Source aliases normalize before evaluation; supplying both service `ensure` and `state` fails.

## Static exports

Handles and these declared properties can be used in expressions. Optional unmanaged values are unavailable, rather than read from a host. Every type additionally exposes `meta.sensitive`.

| Type             | Exported properties                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| File             | `path`, `ensure`, `content`, `mode`, `target`, `owner`, `group`                                                               |
| Package          | `name`, `ensure`, `version`, `architecture`, `held`                                                                           |
| User             | `name`, `ensure`, `uid`, `primary_group`, `groups`, `home`, `shell`, `comment`, `password_hash`, `password_locked`, `expires` |
| Group            | `name`, `ensure`, `gid`                                                                                                       |
| Group membership | `group`, `ensure`, `members`, `exclusive`                                                                                     |
| Exec             | `cwd`                                                                                                                         |
| Service          | `provider`, `name`, `ensure`/`state`, `enabled`, `masked`, `on_change`                                                        |
| Timer            | `name`, `ensure`                                                                                                              |
| SSH key          | `user`, `ensure`, explicit `authorized_keys`                                                                                  |
| Mount            | `path`, `state`                                                                                                               |

For file `content`, only inline content is available; a source does not expose downloaded bytes through an expression. Account IDs allocated by the host cannot be exported when omitted. Use names when depending on a managed account with an allocated ID.

All types accept [common metadata](/language/metadata). Required capabilities are checked when compiling and before executing a received bundle.