#193 enhancement: per-instance data directory isolation for multi-fleet on same device

[Anonymous]

Originally created by: kumaakh
Originally owned by: yashrajsapra

Problem

Multiple fleet instances running on the same device all share the same data directory (~/.apra-fleet/data/). This causes:

• Race conditions on registry.json, statusline.txt, known_hosts, salt — two instances writing simultaneously
• Registry cross-contamination — instance A sees instance B's members and vice versa
• Statusline collisions — last writer wins, statusline reflects whichever instance wrote most recently

Common scenario: a developer running separate fleet instances for different projects (e.g. one for apra-fleet development, one for odm work) on the same machine.

Current State

APRA_FLEET_DATA_DIR env var already exists and is fully respected:

• src/paths.ts: export const FLEET_DIR = process.env.APRA_FLEET_DATA_DIR ?? path.join(os.homedir(), '.apra-fleet', 'data')
• scripts/fleet-statusline.sh: STATUSLINE_FILE="${APRA_FLEET_DATA_DIR:-$HOME/.apra-fleet/data}/statusline.txt"
• Tests already use it: process.env.APRA_FLEET_DATA_DIR = path.join(os.tmpdir(), 'apra-fleet-test-data')

The mechanism is complete — it just isn't surfaced as a first-class configuration option at install/registration time.

Proposed Solution

1. apra-fleet install --data-dir <path> flag

Allow specifying a custom data directory at install time. The installer writes APRA_FLEET_DATA_DIR=<path> into the MCP server's env config so it is passed automatically on every server start.

Example:

apra-fleet install --data-dir ~/.apra-fleet/projects/odm
apra-fleet install --data-dir ~/.apra-fleet/projects/apra-fleet

Each installation gets its own isolated registry, statusline, known_hosts, and salt.

2. MCP registration env field

For Claude Code, the env field in the MCP config carries the variable through:

{
  "mcpServers": {
    "apra-fleet-odm": {
      "command": "apra-fleet",
      "env": { "APRA_FLEET_DATA_DIR": "/Users/akhil/.apra-fleet/projects/odm" }
    }
  }
}

This allows multiple named fleet MCP registrations on the same machine, each with isolated data.

3. Named instances (optional, builds on above)

apra-fleet install --instance odm as shorthand for --data-dir ~/.apra-fleet/instances/odm, also registering the MCP server as apra-fleet-odm rather than apra-fleet.

4. Documentation

Add multi-instance setup guide to the fleet skill and README: how to run two isolated fleet instances, how to name them, which MCP server to use in each project.

Files Affected

• src/cli/install.ts — add --data-dir / --instance flags, write env to MCP config
• src/paths.ts — no changes needed (already parameterised)
• scripts/fleet-statusline.sh — no changes needed (already uses APRA_FLEET_DATA_DIR)
• skills/fleet/SKILL.md — document multi-instance pattern
• README.md / install docs — multi-instance setup guide

Notes

• The salt file (~/.apra-fleet/data/salt) is used for credential encryption. Isolated instances get their own salt — credentials stored in one instance are not readable by another. This is correct behaviour for isolation but worth documenting explicitly.
• Default behaviour (no --data-dir) unchanged — single-instance users are unaffected.

[Anonymous]

Originally posted by: kumaakh

Addendum: apra-fleet workspace CLI

Expanding scope to include workspace management commands. A workspace is a named, isolated data directory — the user-facing name for a fleet instance.

Proposed CLI

apra-fleet workspace list
apra-fleet workspace add <name>      [--install]
apra-fleet workspace remove <name>   [--force]
apra-fleet workspace use <name>      (sets default for current shell / updates MCP registration)
apra-fleet workspace status [<name>] (shows registry count, last statusline update, etc.)

Behaviour

workspace list — shows all known workspaces with their data path, member count, and active/inactive state:

NAME         PATH                              MEMBERS  ACTIVE
default      ~/.apra-fleet/data                    8    ✅
odm          ~/.apra-fleet/workspaces/odm           4    ✅
apra-fleet   ~/.apra-fleet/workspaces/apra-fleet    2    —

workspace add <name> — creates ~/.apra-fleet/workspaces/<name>/, registers it in a workspace index (~/.apra-fleet/workspaces.json). With --install, also runs the MCP registration step so Claude/Gemini can see it as a separate named server (apra-fleet-<name>).

workspace remove <name> — removes from index, optionally deletes data dir. --force required if members are still registered.

workspace use <name> — sets APRA_FLEET_DATA_DIR for the current shell session (prints export command for eval), or updates the default MCP registration to point at this workspace.

workspace status — quick health check: data dir exists, registry member count, age of statusline.txt, salt present.

Files Affected (addendum)

• src/cli/workspace.ts — new workspace subcommand handler
• src/paths.ts — add WORKSPACES_INDEX path constant
• src/cli/install.ts — --instance <name> as shorthand for --data-dir ~/.apra-fleet/workspaces/<name> && workspace add <name>

[Anonymous]

• assigned_to: yashrajsapra

[Anonymous]

Originally posted by: kumaakh

Cross-reference: [#216] (secret CLI redesign)

[#216] introduces apra-fleet secret --set as a standalone CLI for delivering and persisting secrets. When [#193] lands, the following additions are required to make credential sandboxing work correctly across instances:

1. Auto-launched terminals must carry APRA_FLEET_DATA_DIR — when credential_store_set spawns apra-fleet secret --set <name> in a new terminal, it must prefix the command with APRA_FLEET_DATA_DIR=<this-instance-path>. Without this, the CLI defaults to the global vault and misses the instance-specific one.

2. credential-store.ts must derive path at call time — CREDENTIALS_PATH is currently computed at module load from the FLEET_DIR constant. With per-instance data dirs, the correct path depends on which instance is running. Change to derive from process.env.APRA_FLEET_DATA_DIR (or an injectable dataDir parameter) at call time, not module load.

3. apra-fleet secret docs — document that setting APRA_FLEET_DATA_DIR before running apra-fleet secret --set targets a specific instance's vault. This is how a user would pre-provision credentials for a named instance from their shell.

These are small, contained changes — no API surface changes needed. Flagging here so they are not missed when [#193] is implemented.