Using AgentSecrets in a Monorepo

Monorepos containing multiple frontend applications, backend APIs, and microservices (e.g. managed via Turborepo, Nx, or pnpm workspaces) present a unique secret management challenge:

• Different applications require different subsets of secrets.
• Multiple packages run concurrently in parallel pipelines (turbo run dev).
• Build caches can accidentally invalidate or leak secrets if .env files are watched.

AgentSecrets natively supports monorepos through Directory-Scoped Projects and Concurrent In-Memory Injection.

Monorepo Architecture: Projects within a Workspace

In AgentSecrets, a single Workspace represents your team or company. Inside that workspace, you create distinct Projects for each application or service in the repository:

my-monorepo/
├── .agentsecrets/
│   └── project.json         <-- Root context: project "core-infrastructure"
├── apps/
│   ├── web/                 <-- Next.js Frontend
│   │   └── .agentsecrets/
│   │       └── project.json <-- Scoped to project "web-frontend"
│   └── api/                 <-- Python / FastAPI Backend
│       └── .agentsecrets/
│           └── project.json <-- Scoped to project "backend-api"
└── packages/
    └── db/                  <-- Shared Database Schema

Initializing Monorepo Projects

From the root of each app directory, run:

# In apps/web:
cd apps/web
agentsecrets project create web-frontend
agentsecrets init --storage-mode 1

# In apps/api:
cd apps/api
agentsecrets project create backend-api
agentsecrets init --storage-mode 1

Each subdirectory now has its own .agentsecrets/project.json pointing to its dedicated project ID. When commands are run from within apps/web, AgentSecrets automatically scopes secret resolution to web-frontend.

Running Services in a Monorepo

Option 1: Running Individual Apps Directly

Navigate into the application folder and use agentsecrets env --:

cd apps/api
agentsecrets env -- python main.py

Or for the frontend:

cd apps/web
agentsecrets env -- npm run dev

Option 2: Turborepo / Nx Concurrent Task Execution

When orchestrating tasks from the monorepo root via Turborepo (turbo run dev), you can configure each package's package.json script to wrap its dev command in agentsecrets env:

// apps/web/package.json
{
  "name": "web",
  "scripts": {
    "dev": "agentsecrets env -- next dev",
    "build": "agentsecrets env -- next build"
  }
}

// apps/api/package.json
{
  "name": "api",
  "scripts": {
    "dev": "agentsecrets env -- uvicorn main:app --reload",
    "test": "agentsecrets env -- pytest"
  }
}

Now, from the monorepo root:

npx turbo run dev

Turborepo spawns both services concurrently. Because agentsecrets env runs inside each package directory, each child process resolves only its own scoped secrets from the OS Keychain in parallel.

Overriding Project Context via Environment Variables

If your build tool executes all commands from the root directory rather than cd-ing into package folders, you can dynamically override the project context using the AGENTSECRETS_PROJECT_ID environment variable:

# Target the backend API explicitly from the monorepo root:
AGENTSECRETS_PROJECT_ID=proj_api123 agentsecrets env -- python apps/api/main.py

Server Endpoint Resolution Order in Monorepos

When resolving credentials, AgentSecrets searches in this strict priority order:

1. AGENTSECRETS_PROJECT_ID (CLI environment variable override)
2. .agentsecrets/project.json in the current working directory
3. Upward directory traversal searching for the nearest parent .agentsecrets/
4. Active global project selected via agentsecrets project use <name>

Turborepo Caching Best Practices (No .env Invalidation)

In traditional setups, Turborepo monitors .env files in turbo.json under globalEnv or env:

// Traditional setup (Vulnerable & Brittle):
{
  "pipeline": {
    "build": {
      "inputs": [".env.production", "src/**"]
    }
  }
}

With AgentSecrets:

1. Zero Disk Files: No .env files exist, so there are no plaintext files to accidentally commit or track.
2. Deterministic Builds: Build steps run with agentsecrets env -- next build. You only need to declare the public environment variable names in turbo.json, not the values.