service-profile

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. Grants attached to the profile control access. Only principals listed in a grant can assume the profile at spawn time.

Fields

Name	Type	Required	Description
`name`	string	yes	Unique identifier within the tenant. DNS label format: `[a-z][a-z0-9-]{0,62}`.
`description`	string	no	Human-readable description shown in the dashboard. Max 1024 bytes.
`git_name`	string	no	Git author name for agents using this profile (e.g. `acme-deploy-bot`). Empty uses the default bot name.
`git_email`	string	no	Git author email for agents using this profile. Empty uses the default bot email.
`anthropic_api_key_secret`	string	no	Secret name for the Anthropic API key. A Claude OAuth credential on this profile wins over it. Empty, with no Claude OAuth credential set, runs this profile’s agents on a Murmur-provided model credential and bills the tenant for LLM Inference.
`signing_key_secret`	string	no	Secret name for the Ed25519 commit signing key. Empty means agents using this profile do not sign their commits.
`github_token_secret`	string	no	Secret name for a GitHub token. Empty uses a token minted from the installed app.
`claude_oauth_token_secret`	string	no	Secret name for a Claude subscription OAuth token.
`claude_oauth_refresh_token_secret`	string	no	Secret name for a Claude OAuth refresh token.
`openai_api_key_secret`	string	no	Secret name for an OpenAI/Codex API key. A fallback used only when no OpenAI OAuth credential is set.
`claude_oauth_credentials`	object[]	no	Additional labeled Claude OAuth credentials. Each entry has `token_secret`, `refresh_token_secret`, and `label`. Spawns round-robin across the legacy pair (entry 0, label `default`) plus these entries.
`openai_oauth_token_secret`	string	no	Secret name for an OpenAI (ChatGPT) subscription OAuth access token. Preferred over `openai_api_key_secret`.
`openai_oauth_refresh_token_secret`	string	no	Secret name for the OpenAI OAuth refresh token.
`openai_oauth_id_token_secret`	string	no	Secret name for the OpenAI OAuth id_token. Codex needs it to establish the ChatGPT account.
`openai_oauth_credentials`	object[]	no	Additional labeled OpenAI OAuth credentials. Each entry has `token_secret`, `refresh_token_secret`, `id_token_secret`, and `label`. Spawns round-robin across the legacy pair (entry 0, label `default`) plus these entries.
`ssh_public_keys`	string[]	no	SSH public keys for `murmur ssh` access, in `authorized_keys` format.
`steering_policy`	string	no	Name of a steering policy that additionally gates events driving this profile’s agents. The narrower of this and the event repo’s policy wins, so a permissive repo policy never loosens a locked-down profile. Empty applies the repo policy only.
`grants`	Grant[]	no	Access grants controlling who may assume this service profile.
`user_system_prompt`	object	no	Instructions appended to every turn of agents spawned with this profile, whether owned or borrowed. Set `user_system_prompt.text` to Markdown, maximum 16 KiB. Empty disables it.
`deny_platform_inference_fallback`	bool	no	When `true`, agents using this profile are refused Macroscope-supplied inference for any provider the profile has no credential for. Default `false`: those agents run on a Macroscope-supplied key billed to the tenant.
`inference_connections`	object[]	no	Inference connections agents using this profile can run opencode against, in the order added. Each entry has `id` (unique), `display_name`, `base_url`, `api_key_secret` (a tenant secret name), `protocol`, `provider`, and `models`.
`github_role`	string	no	GitHub role (catalog kind `github-role`) controlling what agents may do with this profile’s GitHub credential. Empty selects the platform coding-agent role.
`allow_borrowers_to_access_all_repositories`	bool	no	Default `false`: agents borrowing this profile get per-repository GitHub tokens capped at the borrower’s own repository role, and operations that name no repository are refused. `true` gives borrowing agents the full GitHub App installation token. Profile-owned agents (flights) always use the full installation token.

Grant fields

Each entry in grants specifies who can access or assume this service profile. These grants apply to this resource, not to what the service profile may do elsewhere. Grant that authority through tenant-bindings or grants on the target workspace. See authorization for details.

Name	Type	Required	Description
`groups`	string[]	conditional	Group names in the same tenant. At least one of `groups` or `users` is required.
`users`	string[]	conditional	GitHub logins. At least one of `groups` or `users` is required.
`inline`	object	conditional	Inline permission list. Exactly one of `inline` or `role` is required.
`inline.permissions`	string[]	yes	Permission strings in `{kind}.{verb}` format (e.g. `service-profile.assume`).
`role`	string	conditional	Named role reference, resolved at evaluation time. Exactly one of `inline` or `role` is required.
`name_pattern`	string	no	Glob pattern restricting which resource names this grant applies to. Supports `${provider}` and `${username}` variables and trailing `*` wildcard.
`extend_to_runtime_agents`	bool	no	Ignored on this resource. Runtime extension applies to tenant-bindings and grants on the running agent’s own workspace.

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

name: deploy-bot
description: "Deploy bot for release automation"
git_name: deploy-bot
grants:
  - users:
      - octocat
    inline:
      permissions:
        - service-profile.assume

A profile only carries the secrets it names. Each empty field has its own behavior. This profile’s agents commit as deploy-bot at the default bot email, authenticate to GitHub with a token minted from the installed app, leave their commits unsigned, and run on a Murmur-provided model credential that is billed to the tenant. See Fields for what each empty field does.

Listing service profiles

murmur get service-profile

ci-builder
deploy-bot

The list prints one name per line.

Reading a single service profile

murmur get service-profile ci-builder

Errors

Code	Meaning	What to do
`INVALID_ARGUMENT`	`name is required`	Provide a `name` field.
`INVALID_ARGUMENT`	`name 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_ARGUMENT`	`description exceeds 1024 byte limit (N bytes)`	Shorten the `description` to 1024 bytes or fewer.
`INVALID_ARGUMENT`	`grants[N]: grant must specify at least one group or user`	Each grant needs at least one entry in `groups` or `users`.
`INVALID_ARGUMENT`	`grants[N]: grant must specify inline permissions or a role reference`	Each grant needs either an `inline` permission list or a `role` reference.
`INVALID_ARGUMENT`	`grants[N]: grant role reference must be non-empty`	A grant uses `role` but the value is empty. Provide a role name.
`INVALID_ARGUMENT`	`steering_policy: steering policy "<name>" does not exist`	Reference an existing steering policy, or leave `steering_policy` empty to apply the repo policy only.
`INVALID_ARGUMENT`	`anthropic_api_key_secret: secret "<name>" does not exist`	Each `*_secret` field must name an existing tenant secret. Create it with `murmur secret set` first.
`FAILED_PRECONDITION`	`cannot delete service-profile "<name>": referenced by flight: <names>`	A flight or API key references this service profile. Remove the reference before deleting.

Profiles and secrets: concept overview
Service profiles guide: step-by-step setup from the dashboard
Authorization: grants, roles, and permissions
steering-policy: additionally gates events driving this profile’s agents
Agents: the resource that references a service profile at spawn time
Flights: multi-agent workflows that reference a service profile
murmur set: CLI command for creating and updating catalog resources
murmur get: CLI command for reading catalog resources

Getting Started

Core Concepts

Guides

service-profile

Fields

Grant fields

Examples

Create a service profile

Minimal service profile

Listing service profiles

Reading a single service profile

Errors

​Fields

​Grant fields

​Examples

​Create a service profile

​Minimal service profile

​Listing service profiles

​Reading a single service profile

​Errors

​Related

Fields

Grant fields

Examples

Create a service profile

Minimal service profile

Listing service profiles

Reading a single service profile

Errors

Related