​

Auto-managed credentials

​

TL;DR

apiVersion: crewship/v1
kind: Crew
metadata: { name: Backend, slug: backend }
spec:
  services:
    - { name: postgres, image: postgres:16-alpine }
  agents:
    - { slug: lead, name: Lead, agent_role: LEAD }

• One sidecar container (postgres:16-alpine) on the crew-private bridge network with POSTGRES_USER=postgres and a generated POSTGRES_PASSWORD.
• One credential row in the workspace named POSTGRES_PASSWORD, status ACTIVE, provider AUTO_MANAGED, tagged provisioned_for_service=backend/postgres.
• Every agent in the crew (here: lead) gets POSTGRES_PASSWORD added to its env_refs automatically.

​

What images are recognised

​

Redis is delivered via a command arg, not an env var

• postgres:16-alpine
• docker.io/library/postgres:17
• harbor.acme.io/library/postgres:16@sha256:...
• localhost:5000/postgres:latest

​

Customising the auto-credential

services:
  - name: cache
    image: ghcr.io/example/redis-with-auth:v1
    auto_credentials:
      - name: REDIS_PASSWORD
        inject_as_env: REDIS_AUTH       # default = name
        inject_to_agents: false          # default = true; here only the
                                         # sidecar sees the value
        length: 48                       # default = 32 bytes (64 hex chars)
        description: Auto-generated AUTH token for the cache sidecar.

​

Overriding a datastore’s command or auth env

• Command-injected datastores (Redis): your command: must include the datastore’s auth flag followed by a non-empty argument (--requirepass <secret> for Redis). A command with no flag, or the flag with an empty argument, fails the apply.
• Env-injected datastores (Postgres, MySQL, Mongo, …): the auth env key you set (e.g. POSTGRES_PASSWORD) must be non-empty. Setting it to "" fails the apply — it is neither “auth” nor “let Crewship generate one,” it is an ambiguous half-config, so we reject it.

services:
  # Deliberately run an unauthenticated datastore on the crew-private
  # bridge — an explicit, acknowledged opt-out from the always-auth rule.
  - name: redis
    image: redis:7-alpine
    command: ["redis-server"]        # no --requirepass
    allow_unauthenticated: true      # required, or apply fails closed

​

Threat model — why this is safe

1. credentials.encrypted_value — AES-256-GCM encrypted with ENCRYPTION_KEY. Surfaces the row in the UI for audit, rotate actions, and “Created by” attribution.
2. crews.services_json — plaintext, embedded in the sidecar env literal. The docker provider reads this column at sidecar start time and passes the value via docker --env.

• Sidecars from auto_credentials MUST be crew-private (no host port published). The validator refuses ports: that publish to the host on a service with auto-credentials — that combination requires a T2 manual credential and an explicit security review.
• The crew-private bridge network is the actual security boundary. An attacker who can read the workspace DB also already controls bridge isolation and the threat model is “host root,” under which a separate encrypted column doesn’t help.
• The duplicated value is bounded to the same DB file the encrypted column lives in. A backup of the workspace state carries both consistently.

​

What the UI shows

• Source column reads “system (backend/postgres)” — system is the v98 actor type, and the parenthesised slug is the provisioned_for_service tag. (A future PR pins the row to the crew’s lead agent and renders “agent: trapper” instead.)
• “Reveal value” and “Edit” actions are hidden.
• “Rotate” is available as a follow-up action (P1).
• Audit timeline shows the create event with the manifest apply as the actor user.

​

When auto_credentials is the WRONG choice

• The sidecar publishes a port to the host (docker run -p 5432:5432- style). The bridge is no longer the security boundary; declare the credential manually under credentials: and accept the operator-input friction.
• The credential needs to be readable by something outside the crew (other crews, an external monitor, a backup job). T1 rows are crew-scoped by design — workspace-wide credentials with external consumers belong to T2 / T3.
• You want to bring your own value from a secrets manager (Vault, AWS Secrets Manager, Doppler). That’s the T3 tier — declare a credential with a source: block instead.

​

Migration: existing manifests with env_refs: [POSTGRES_PASSWORD]

# Before (v97 and earlier)
credentials:
  - { env: POSTGRES_PASSWORD, provider: NONE, type: GENERIC_SECRET }

services:
  - name: postgres
    image: postgres:16
    env: { POSTGRES_DB: uo, POSTGRES_USER: postgres }
    env_refs: [POSTGRES_PASSWORD]

# After (v98+)
services:
  - { name: postgres, image: postgres:16, env: { POSTGRES_DB: uo } }

​

Related

• SPEC-4 — Auto-managed sidecar credentials (internal design doc). This guide is the canonical user-facing reference.
• internal/manifest/known_sidecars.go (catalog implementation).
• Manifests guide (the broader manifest layer).