agent-filestore

FileStore

FileStore publishes immutable evidence files for pull requests and project work. Agents upload directly to private object storage and receive stable raw-file links suitable for screenshots, recordings, PDFs, and text artifacts.

What it does

• One immutable file and public URL per upload.
• Private React evidence room grouped by pull request, task, or Inbox.
• Named API keys for agent attribution and revocation.
• Direct-to-bucket uploads and short-lived signed downloads.
• Reversible archive and owner-only permanent purge.

CLI

After the first package release:

bunx agent-filestore@latest auth set <api-key>
bunx agent-filestore@latest upload ./evidence.png
bunx agent-filestore@latest artifacts list

The uploader detects the Git repository, branch, commit, and current GitHub pull request when git and gh are available. Override that context with --pr, --group, --group-url, or --no-pr. Add --json for agent-safe structured output.

Local development

bun install
cp .env.example .env
docker compose up -d
bun run db:migrate
bun run dev

Run the React development server separately when working on the portal:

bun run dev:web

Validation:

bun run check

Service configuration

Required production variables:

• DATABASE_URL
• FILESTORE_PUBLIC_BASE_URL
• FILESTORE_ADMIN_PASSWORD_HASH
• AWS_ENDPOINT_URL
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_S3_BUCKET_NAME
• AWS_DEFAULT_REGION

The optional limits and URL lifetimes are documented in .env.example. Generate the owner password hash with Bun rather than storing a plaintext password:

bun -e 'console.log(await Bun.password.hash(process.argv[1]))' 'your-password'

Architecture decisions

The product contract, ADRs, and terminology live under docs/. The production topology is one Bun service, one Postgres service, and one private Railway bucket in Singapore/APAC.