Workspaces and monorepos

A workspace holds shared key storage and a registry of vaults. A service vault holds that service’s environment values and validation rules. Services share an encryption key per environment; each vault has its own signing key.

Initialize the root and services

From the monorepo root:

ramenv init workspace --ingredient local
mkdir -p apps/api apps/web

(
  cd apps/api
  ramenv init service
  ramenv set development DATABASE_URL
)

(
  cd apps/web
  ramenv init service
  ramenv set development PUBLIC_API_URL --plaintext
)

Choose the workspace ingredient at the root. Service initialization uses the existing workspace’s provider.

init workspace creates workspace metadata and keys without a root vault. init service registers a vault under an existing workspace. Both development and production are created in each new service vault.

Understand the layout

my-monorepo/
├── .ramenv.workspace.toml
├── .ramenv.keys                 # private, shared keys
└── apps/
    ├── api/
    │   └── .ramenv.vault.toml
    └── web/
        └── .ramenv.vault.toml

Cloud workspaces use .ramenv.keyrefs.toml instead of .ramenv.keys. Commit metadata, cloud refs, and reviewed vaults; keep local keys private.

Run commands from a service

cd apps/api
ramenv list development
ramenv validate development
ramenv run development -- python app.py

ramenv finds the workspace root by walking up the directory tree. Ordinary commands read the vault in the current directory; run them from the service you want to configure.

Services share environment keys, but each vault keeps its own values and validation rules. Services neither merge nor inherit that configuration.

Add environments carefully

ramenv create-env staging

This creates a shared key and an empty environment in the current vault only. Sibling vaults stay unchanged. Repeating create-env staging in another service fails because the workspace key already exists.

Apply workspace-wide changes

These commands affect every registered vault containing the named environment:

ramenv rotate production
ramenv remove-env development

Run these commands from the workspace root or a service directory. Multi-vault changes prompt for confirmation. To confirm without a prompt:

ramenv rotate production --yes
ramenv remove-env development --yes

Rotation re-encrypts encrypted values and preserves plaintext. Removal deletes the shared key and the environment’s data in affected vaults. Review provider-specific deletion behavior and recovery requirements before executing either operation.

Keep registered vault paths, workspace metadata, and key references together when copying a workspace. Deployment may need only one service vault for runtime, but workspace maintenance must retain the registered vaults it will modify. See deployment.