Veilfile

Veilfile — private, ephemeral artifact hosting for AI agents

When a coding agent in CI or a cloud session produces a screenshot, log bundle, or HAR file for review, it needs a private URL to put it at — not a public repo. Veilfile is the sanctioned place: upload via API key (or MCP), get back an unguessable, expiring URL. Uploads are scanned for secret shapes and flagged (blocked only when the caller passes on_secret=reject; file contents are never logged).

• API: POST /api/v1/artifacts (multipart, Authorization: Bearer vlf_…) → {id, url, expires_at, size_bytes, secret_flags[]}. GET /a/ serves the file (the 256-bit token *is* the auth). List (bare JSON array) and revoke endpoints included.
• MCP: hosted server at POST /mcp (JSON-RPC over HTTP; tools upload_artifact, create_upload_url, list_artifacts, revoke_artifact), authenticated with a vlf_ key or an OAuth token.
• CLIs: veilfile on PyPI (cli/) and npm (npm/): login (device flow), logout, status, push, pull.
• Dashboard: signed-in pages at /app/, Django views on the same shell as the rest of the site: Overview (usage vs plan caps), Files (secret-flag notes
• revoke), Keys (a new key is shown once), Connected apps and Billing (plan switching and the Stripe billing portal).
• Landing page: / (public). Agent docs: /llms.txt, docs/API.md, /docs/.
• Agents working on this repo: read AGENTS.md.

See SPEC.md for the product spec.

Plans

Yearly billing costs ten months' price, so two months are free. A yearly plan has the same limits as the monthly one.

The source of truth is backend/drop_core/plans.py (PLANS, and ANNUAL_PRICE_USD for the yearly prices; Stripe prices live in Stripe and the STRIPE_PRICE_* variables). backend/drop_core/tests_fix_docs.py fails when a doc or template states a different price or cap.

Quickstart (local dev)

# Backend

python3 -m venv venv && ./venv/bin/pip install -r backend/requirements.txt export DJANGO_DEBUG=True DJANGO_SECRET_KEY=dev-only-key ./venv/bin/python backend/manage.py migrate ./venv/bin/python backend/manage.py createsuperuser # dashboard login ./venv/bin/python backend/manage.py runserver # :8000

Sign up at http://localhost:8000/accounts/signup/ (or log in), open /app/, create an API key, then:

curl -H "Authorization: Bearer vlf_..." \

-F "file=@screenshot.png" \ http://localhost:8000/api/v1/artifacts/

Environment variables

No secrets are committed to this repo. Copy the names below into a local .env (gitignored) or your host's env config. Billing is live in production (sk_live_..., live price IDs, Stripe Managed Payments); use a Stripe sandbox/test key only on a local or staging copy.

Without Stripe vars, checkout/switch/portal return 503 billing_not_configured and the dashboard shows a friendly note; everything else works.

Tests

Tests need DJANGO_DEBUG=True (the test runner refuses False) and a local database; it also forces local storage and strips STRIPE_*/AWS_*.

# Backend (the count changes; run it rather than trusting a number here)

cd backend && DJANGO_DEBUG=True DJANGO_SECRET_KEY=dev-only-key \ ../venv/bin/python manage.py test ../venv/bin/python manage.py makemigrations --check --dry-run # must report no changes

CLIs

cd npm && node --test cd cli && ../venv/bin/python -m unittest discover -s tests -t .

CI (.github/workflows/ci.yml) runs all of the above plus manage.py check --deploy, a production-settings collectstatic, and the browser checks in site-tests/ (jobs site, site-cloth, site-ink, site-reading, site-phone, site-forms, site-catalog and site-dashboard; see AGENTS.md, "Site checks") on every pull request to main (the browser checks skip a pull request that changes no page), and the backend and CLI checks on every push to it. It runs on GitHub-hosted runners, one machine for each job, with the jobs side by side (AGENTS.md, "Where CI runs").

Ops

• Deploy: Render Docker web service (serves veilfile.com), auto-deploys every commit to main after its CI checks pass, with a paid Postgres. render.yaml mirrors it. The container runs as a non-root user. Boot sequence (backend/entrypoint.sh): migrate --noinput (skipped when SKIP_MIGRATE=1), createcachetable, a background daily housekeeping loop, then gunicorn.
• Health check: GET /healthz returns 200 {"status":"ok"} after a SELECT 1, or 503. Set it as the Render Health Check Path.
• Daily housekeeping: the entrypoint loop runs sweep_expired, clearsessions, cleartokens, prune_funnel_events, prune_email_ips (clears send-log IPs after 90 days) and purge_expired_cache once a day. No separate cron job is needed. Uploads also trigger a small lazy sweep.
• TTL sweeper: python backend/manage.py sweep_expired deletes expired artifacts (files + rows). Idempotent. Prints swept=N bytes=N failed=N and exits non-zero when any storage delete failed (those rows are kept for the next run); --limit N / --time-budget SECONDS bound a run.
• Orphaned files: python backend/manage.py reconcile_storage lists stored objects with no artifact row; --delete removes them. Run it by hand, dry run first: --delete refuses when the database looks wrong (empty artifact table, more than 20% orphans, or R2 storage without PostgreSQL) unless you pass --force after checking the db= / storage= it prints.
• Billing resync: python backend/manage.py sync_stripe_billing (dry run; --apply to write) rebuilds workspace plans from Stripe. The Stripe setup steps are in the private ops repository.
• Deploy checks: manage.py check --deploy reports veilfile.W001-W006 misconfigurations (also logged at ERROR by every worker at boot).
• Local container: docker run needs DATABASE_URL=sqlite:////tmp/db.sqlite3 together with DJANGO_ALLOW_SQLITE=True (production mode otherwise refuses SQLite); /app/backend is read-only to the non-root user.
• Storage: Render's disk is ephemeral. Production must use `DROP_STORAGE=s3` (Cloudflare R2).
• MCP registries: launch checklist in docs/REGISTRIES.md.

Project layout

backend/

config/ Django settings/URLs (env-driven) drop_core/ Workspace, APIKey (vlf_), Artifact, plans, storage, secret scan, agent API, key mgmt, device login, OAuth glue, sweeper drop_billing/ Stripe checkout/switch/portal/status/webhook (live,