​

kind: Workspace

​

What it is

Credentials are slots, never values. The manifest format has no value: field for credentials — a Workspace document is always safe to commit to git. Credential values are supplied at apply time via crewship apply --from-env / --secrets-file, or prompted; any slot left unfilled is created as status=PENDING and shows a “needs value” CTA in the UI.

​

YAML schema

apiVersion: crewship/v1        # required — always crewship/v1 for now
kind: Workspace                # required — the literal string "Workspace"
metadata:
  name: ACME Engineering       # required (display)
  slug: acme-engineering       # required — idempotency key
  description: ""              # optional
  author: ACME Corp            # optional — descriptive header
  version: 0.1.0               # optional
  preferred_language: en       # optional
spec:
  credentials:                 # workspace-scoped credential slots (shared by every crew)
    - env: ANTHROPIC_API_KEY   # required — env-var name == credential name
      provider: ANTHROPIC      # required
      type: API_KEY            # required
      label: Anthropic API key # optional
  skills:                      # workspace-scoped skills (referenced by crew agents)
    - slug: house-style        # required — idempotency key
      inline: |                # one of inline / path / source
        ---
        name: house-style
        description: ACME's internal code-style conventions
        ---
        # House Style
        One feature per PR; commits in imperative mood.
  crews:                       # required — at least one crew
    - slug: code-review
      name: Code Review
      icon: git-pull-request
      color: blue
      devcontainer:
        image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
      mcp_servers:
        - name: github
          display_name: GitHub
          transport: stdio
          command: npx
          args: [-y, "@modelcontextprotocol/server-github"]
          env_mapping:
            GITHUB_PERSONAL_ACCESS_TOKEN: GH_TOKEN
      agents:
        - slug: daniel
          name: Daniel
          agent_role: LEAD
          cli_adapter: CLAUDE_CODE
          llm: { provider: ANTHROPIC, model: claude-haiku-4-5 }
          tool_profile: MINIMAL
          skills: [house-style]
          env_refs: [ANTHROPIC_API_KEY, GH_TOKEN]
          prompt: |
            You are Daniel, a senior code reviewer.

​

Top-level fields

​

spec.credentials[] (slot declaration)

​

spec.skills[]

​

spec.crews[]

• agents — see Agent for the field reference (the nested form omits crew_slug since the parent crew is implicit). At most one agent per crew may be agent_role: LEAD. Only AGENT and LEAD are valid here — COORDINATOR is rejected in the nested form (see the validation rules below).
• mcp_servers — the inline form of Integration, crew-scoped. Each entry’s transport is one of stdio, streamable-http, http, or sse.
• services — sidecar containers; same shape as Crew’s spec.services, including the auto_credentials block described below.

​

spec.crews[].services[].auto_credentials[]

Host-published ports disable auto_credentials. When a service publishes a port to the host the sidecar leaves the crew’s private bridge, so the external attack surface deserves an operator-chosen secret. validate.go refuses auto_credentials in that configuration — declare the credential as a regular slot instead.

​

Examples

​

Minimal — one crew, one agent

apiVersion: crewship/v1
kind: Workspace
metadata:
  name: Solo
  slug: solo
spec:
  credentials:
    - env: ANTHROPIC_API_KEY
      provider: ANTHROPIC
      type: API_KEY
  crews:
    - slug: main
      name: Main
      devcontainer:
        image: mcr.microsoft.com/devcontainers/javascript-node:22-bookworm
      agents:
        - slug: lead
          name: Lead
          agent_role: LEAD
          cli_adapter: CLAUDE_CODE
          env_refs: [ANTHROPIC_API_KEY]
          prompt: You are the crew lead.

​

Multi-crew with shared skill + credentials

​

CLI reference

​

Apply behavior

• Upsert (default) — create missing rows, update drifted ones.
• --strict — fail if any slug already exists (fresh-bootstrap guard).
• --replace --yes — destructive recreate.

​

Validation rules

• metadata.slug is required and slug-formatted.
• Workspace credentials: each has a non-empty env, provider, and type; no duplicate env within the scope.
• Workspace skills: each has a non-empty slug and exactly one of path / source / inline.
• Crews: each crew has a slug (slug-formatted, unique within the workspace) and at least one agent.
• Agents: slug + name required; agent_role (AGENT | LEAD), cli_adapter, and tool_profile enum-checked; at most one LEAD per crew; skills and env_refs resolve against the crew-scope then workspace-scope declarations.

  COORDINATOR is not valid in nested bundles. Inside a kind: Crew or kind: Workspace document the agent-role validator (validAgentRole, internal/manifest/validate.go) admits only AGENT and LEAD. The standalone kind: Agent form accepts COORDINATOR in its own front-end validator, but the nested form rejects it outright — prefer AGENT/LEAD everywhere.

• MCP servers and services validate their own shapes (env-mapping values resolve to known credentials; service names are DNS labels; named volumes only). MCP transport must be one of stdio, streamable-http, http, or sse — stdio requires command; the three HTTP-family transports require endpoint.
• Services: auto_credentials[] entries each need a valid env-var-shaped name (unique within the service, no clash with the crew’s credentials[]); inject_as_env, when set, must be env-var-shaped; length, when positive, is at least the 16-byte floor.

​

Round-trip via export

​

See also

• Crew / Agent / Skill / Integration — the standalone equivalents of the nested blocks.
• examples/manifests/full-team.workspace.yaml — complete multi-crew bundle.
• Schema source: internal/manifest/schema.go (WorkspaceDocument, WorkspaceSpec).
• Validation: internal/manifest/validate.go (checkWorkspaceDoc).
• Export: internal/manifest/export.go (ExportWorkspace).