Agent Drive

Encrypted storage your agents keep across sandboxes. Use it through an MCP server, a CLI, and a skill.

• User stories
• Build plan
• HTTP API
• Client encryption format
• CLI and MCP reference
• Quickstart
• Deployment, deletion maintenance, and release gates

Client quickstart

After applying the database migration and provisioning a local management key as described below, build the workspace CLI:

pnpm --filter @dennisonbertram/agent-drive build

Set the local API endpoint and paste the one-time management credential at the hidden prompt:

export AGENT_DRIVE_API_URL=http://127.0.0.1:3000
read -rs -p "Management API key: " AGENT_DRIVE_API_KEY
printf '\n'
export AGENT_DRIVE_API_KEY
pnpm agent-drive login --api "$AGENT_DRIVE_API_URL"

Create an agent and a drive. Back up the printed drive key immediately. The server cannot recover it:

pnpm agent-drive agent create --name local-agent
pnpm agent-drive drive create --name my-drive

Use the returned agent and drive IDs to create a scoped file-operation key. Save the one-time API token securely, then use it with the locally retained drive key:

pnpm agent-drive key create --agent AGENT_ID --drive DRIVE_ID --label local-cli --scope read --scope write --scope delete
read -rs -p "Scoped API key: " AGENT_DRIVE_API_KEY
printf '\n'
export AGENT_DRIVE_API_KEY
printf 'hello from an agent\n' > ./sample.txt
pnpm agent-drive put ./sample.txt /sample.txt --drive DRIVE_ID
pnpm agent-drive get /sample.txt --drive DRIVE_ID --output ./sample.downloaded.txt

The CLI encrypts bytes before uploading. Drive keys never go to the API or object storage.

MCP server

Install the CLI, then add it to your MCP host. Agent Drive reads API credentials and drive keys from its private config file or environment variables; it never accepts a drive key as a command-line argument. Changes to the saved configuration require restarting the MCP process.

npm install -g @dennisonbertram/agent-drive
claude mcp add agent-drive -- agent-drive mcp

To run from source instead (for contributors), build the workspace package and point the host at the compiled CLI with node /ABSOLUTE/PATH/agent-drive/packages/agent-drive/dist/cli.js mcp.

Codex (~/.codex/config.toml), forwarding credential variables from the local environment rather than placing their values in the TOML file:

[mcp_servers.agent-drive]
command = "agent-drive"
args = ["mcp"]
env_vars = ["AGENT_DRIVE_API_URL", "AGENT_DRIVE_API_KEY", "AGENT_DRIVE_CONFIG", "AGENT_DRIVE_KEY"]

Set AGENT_DRIVE_API_URL and AGENT_DRIVE_API_KEY securely in the environment or use the saved config created by pnpm agent-drive login. Per-drive key environment variables use AGENT_DRIVE_KEY_<DRIVE_ID> and take precedence over AGENT_DRIVE_KEY, then saved drive keys. Drive keys and API credentials are secrets; never paste them into prompts, handoffs, or source control. The API key needs the scopes required by the tools you intend to use.

Install the included skill into your working project's skill directory (or read skills/agent-drive/SKILL.md directly). From this checkout, choose your host:

# Claude Code project skill
mkdir -p .claude/skills
cp -R skills/agent-drive .claude/skills/
# Codex project skill
mkdir -p .agents/skills
cp -R skills/agent-drive .agents/skills/

The skills/agent-drive-trace-archive skill archives an agent's old trace files weekly, deleting local copies only after the downloaded copy's SHA-256 matches. Install it the same way as above.

The share tool creates expiring encrypted links through the implemented sharing backend. The stdio regression tests use a real local API and storage, not a live Claude Code session; no Claude binary or external service is installed or invoked by those tests.

Local development environment

The repository includes the authenticated storage API, encrypted client/CLI, MCP tools and skill, human console, encrypted sharing, billing controls, and deletion/audit interfaces. Hosted authentication, payments, storage configuration, and deployment require dedicated configuration and live acceptance; local regression tests are not evidence of a production launch.

Requirements

• Node.js 24.22.2 (the supported Node 24 LTS line; see .nvmrc)
• Corepack and the pinned pnpm version ([email protected])
• Docker Engine and Docker Compose

Enable Corepack once if needed, then install dependencies:

corepack enable pnpm
pnpm install
cp .env.example .env

Start the local PostgreSQL and MinIO services and wait for their health checks and deterministic bucket initialization:

pnpm services:up

PostgreSQL uses the Docker Official Image published in Amazon ECR Public because Docker Hub pulls were rate-limited in the development environment. MinIO's documented Quay image returned an authorization error there, so Compose builds MinIO server and client from pinned upstream releases using Docker Official Go and Debian base images. No third-party MinIO mirror is used.

The Compose defaults and .env.example credentials are public local-development-only values; never reuse them outside local development. The S3 access key and secret are also used as MinIO's local root credentials. MinIO's API is at http://localhost:9000, its console is at http://localhost:9001, and the database is at localhost:5432. Compose creates the agent-drive-local bucket. Keep these services running for local development; use docker compose down when intentionally stopping them. To use alternate host ports, set POSTGRES_HOST_PORT, MINIO_API_HOST_PORT, and MINIO_CONSOLE_HOST_PORT.

Apply all checked-in schema migrations after the services are healthy:

DATABASE_URL=postgresql://agent_drive:[email protected]:5432/agent_drive \
  pnpm --dir apps/web db:migrate

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗