Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt

Use this file to discover all available pages before exploring further.

A service profile is a catalog resource that defines a non-human identity for agents. Instead of running under a developer’s personal credentials, an agent spawned with a service profile commits as a bot author and authenticates with dedicated secrets. Each service profile references secrets by name for API keys, signing keys, and tokens. Access is controlled by grants attached to the profile — only principals listed in a grant can assume the profile at spawn time.

​
Fields

NameTypeRequiredDescription
namestringyesUnique identifier within the tenant. DNS label format: [a-z][a-z0-9-]{0,62}.
descriptionstringnoHuman-readable description shown in the dashboard. Max 1024 bytes.
git_namestringnoGit author name for agents using this profile (e.g. acme-deploy-bot). Empty uses the default bot name.
git_emailstringnoGit author email for agents using this profile. Empty uses the default bot email.
anthropic_api_key_secretstringnoSecret name for the Anthropic API key. Empty falls back to the tenant-wide ANTHROPIC_API_KEY secret.
signing_key_secretstringnoSecret name for the Ed25519 commit signing key. Empty falls back to the tenant-wide SERVICE_SIGNING_KEY secret.
github_token_secretstringnoSecret name for a GitHub token. Empty uses a token minted from the installed app.
claude_oauth_token_secretstringnoSecret name for a Claude subscription OAuth token.
claude_oauth_refresh_token_secretstringnoSecret name for a Claude OAuth refresh token.
openai_api_key_secretstringnoSecret name for an OpenAI/Codex API key.
ssh_public_keysstring[]noSSH public keys for murmur ssh access, in authorized_keys format.
grantsGrant[]noAccess grants controlling who may assume this service profile.

​
Grant fields

Each entry in grants specifies who can assume the service profile and what permissions they hold. See authorization for full details.
NameTypeRequiredDescription
groupsstring[]conditionalGroup names in the same tenant. At least one of groups or users is required.
usersstring[]conditionalGitHub logins. At least one of groups or users is required.
inlineobjectconditionalInline permission list. Exactly one of inline or role is required.
inline.permissionsstring[]yesPermission strings in {kind}.{verb} format (e.g. service-profile.assume).
rolestringconditionalNamed role reference, resolved at evaluation time. Exactly one of inline or role is required.
name_patternstringnoGlob pattern restricting which resource names this grant applies to. Supports ${provider} and ${username} variables and trailing * wildcard.

​
Examples

​
Create a service profile

name: ci-builder
description: "CI builder bot for automated PR creation"
git_name: acme-ci-bot
git_email: ci-bot@acme.dev
anthropic_api_key_secret: ci-anthropic-key
signing_key_secret: ci-signing-key
grants:
  - groups:
      - platform-engineers
    inline:
      permissions:
        - service-profile.assume

cat <<'EOF' | murmur set service-profile ci-builder
name: ci-builder
description: "CI builder bot for automated PR creation"
git_name: acme-ci-bot
git_email: ci-bot@acme.dev
anthropic_api_key_secret: ci-anthropic-key
signing_key_secret: ci-signing-key
grants:
  - groups:
      - platform-engineers
    inline:
      permissions:
        - service-profile.assume
EOF

​
Minimal service profile with tenant-wide fallbacks

name: deploy-bot
description: "Deploy bot using tenant-wide secrets"
git_name: deploy-bot
grants:
  - users:
      - octocat
    inline:
      permissions:
        - service-profile.assume
All secret fields fall back to tenant-wide defaults when left empty. The git_email falls back to the default bot email.

​
Listing service profiles

murmur get service-profile

NAME          DESCRIPTION
ci-builder    CI builder bot for automated PR creation
deploy-bot    Deploy bot using tenant-wide secrets

​
Reading a single service profile

murmur get service-profile ci-builder

​
Errors

CodeMeaningWhat to do
INVALID_ARGUMENTname is requiredProvide a name field.
INVALID_ARGUMENTname must match [a-z][a-z0-9-]{0,62}The name contains invalid characters. Use lowercase letters, digits, and hyphens. Must start with a letter.
INVALID_ARGUMENTdescription exceeds 1024 byte limitShorten the description to 1024 bytes or fewer.
INVALID_ARGUMENTgrants[N]: grant must specify at least one group or userEach grant needs at least one entry in groups or users.
INVALID_ARGUMENTgrants[N]: grant must specify inline permissions or a role referenceEach grant needs either an inline permission list or a role reference.
INVALID_ARGUMENTgrants[N]: grant role reference must be non-emptyA grant uses role but the value is empty. Provide a role name.
FAILED_PRECONDITIONcannot delete service-profile: referenced by agentAn agent or flight references this service profile. Remove the reference before deleting.