Skip to content

Configuration ​

Arkyc is configured via environment variables. The API reads apps/api/.env; the dashboard and playground read their own .env files (Vite). Copy each .env.example and adjust.

API (apps/api/.env) ​

Core ​

VariableExamplePurpose
APP_NAMEArkstackApplication name.
APP_URLhttp://localhost:3100Public base URL of the API.
APP_PORT3100Port the API listens on.
APP_HOSTlocalhostBind host.
FRONTEND_URLhttp://localhost:3000Dashboard origin. Also hosts the cross-device handoff page, so the widget's QR points at ${FRONTEND_URL}/verify.
WEBSITE_URLhttp://localhost:3000Public website, linked from emails.
TRUST_PROXYunsetProxy hops (e.g. 1) or subnets to trust for the client IP. Set it behind a load balancer, or device and velocity signals only see the proxy.
NGROK_AUTHTOKENunsetOptional, for exposing a local API through ngrok.

Database ​

VariableExamplePurpose
DATABASE_URLpostgres://arkyc:arkyc@localhost:5432/arkycPostgreSQL connection.

Match this to your Postgres. The bundled docker-compose.yml provisions arkyc:arkyc@localhost:5432/arkyc.

Auth & crypto ​

VariableExamplePurpose
APP_KEYark key:generateStrong, stable secret. Encrypts secrets at rest and keys document fingerprints; rotating it makes existing ciphertext unreadable and restarts duplicate detection.
JWT_SECRETa-long-random-secretSigns dashboard session JWTs.
JWT_EXPIRES_IN1hDashboard token lifetime.
TWO_FACTOR_ENCRYPTION_KEY(32-byte key)Encrypts 2FA secrets.
CLIENT_TOKEN_TTL_SECONDS900Client-token lifetime (15 min).

Providers ​

VariableDefaultNotes
OCR_DRIVERmockmock, tesseract, ai, or external.
LIVENESS_DRIVER / FACE_MATCH_DRIVERmockmock, external, or local.
BIOMETRICS_MODEL_DIRstorage/modelsModel files for the local drivers (ark biometrics:setup).
SCREENING_DRIVERmockmock, opensanctions, or external.
SCREENING_API_KEY / SCREENING_ENDPOINTnone / hosted APIOpenSanctions key, or a yente / external endpoint.
SCREENING_DATASETdefaultOpenSanctions dataset or collection to match against.
SCREENING_MONITOR_INTERVAL_HOURS24How often monitored identities are re-screened.
NETWORK_DRIVERmockmock or maxmind.
MAXMIND_COUNTRY_DB / MAXMIND_ASN_DBnoneGeoLite2 (or GeoIP2) database paths for maxmind; see GeoIP.
MAXMIND_ANONYMOUS_IP_DB / TOR_EXIT_LISTnoneOptional VPN/proxy database and Tor exit list.
TRUST_PROXYunsetProxy hops or subnets to trust for the client IP.
OCR_FALLBACK_DRIVERmockUsed when OCR_DRIVER=ai but a project isn't granted the ai capability.
OCR_LANGUAGEengTesseract language data for the tesseract driver.
OCR_API_KEYnoneAnthropic API key for OCR_DRIVER=ai.
OCR_AI_MODELclaude-haiku-4-5-20251001Vision model for the ai driver.
OCR_AI_MAX_EDGE1568Longest uploaded image edge (px) for the ai driver.
OCR_AI_TIMEOUT_MS30000Per-attempt timeout (ms) for the ai driver; raise it for large vision models.
OCR_AI_MAX_RETRIES2Retries for the ai driver on a timeout, network error, 429 or 529.
OCR_AI_PROVIDERanthropicanthropic or workers-ai (implied when WORKERS_AI_MODEL is set).
WORKERS_AI_MODEL@cf/google/gemma-4-26b-a4b-itWorkers AI vision model; setting it selects the Workers AI backend.
CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKENnoneWorkers AI credentials (token falls back to OCR_API_KEY).
OCR_ENDPOINT / LIVENESS_ENDPOINT / FACE_MATCH_ENDPOINTnoneexternal HTTP endpoint (or API base override for ai).
LIVENESS_API_KEY / FACE_MATCH_API_KEYnoneOptional bearer for the endpoint.
ADDRESS_DRIVERmockmock or live (address stage; opt-in workflows).
ADDRESS_ORS_API_KEYnoneopenrouteservice key for the live driver's geocode_lookup.
ADDRESS_ORS_URL / ADDRESS_NOMINATIM_URLpublic endpointsGeocoder base overrides (forward / reverse).
ADDRESS_USER_AGENTArkyc/1.0 (…)User-Agent sent to Nominatim (per its usage policy).

See Provider drivers, Fraud signals & screening and Workflows.

Storage ​

VariableDefaultNotes
FILESYSTEM_DISKlocallocal, s3, gcs, or ftp.
S3 (s3 disk)noneAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION, AWS_BUCKET, AWS_ENDPOINT, AWS_URL.
GCS (gcs disk)noneGOOGLE_CLOUD_PROJECT, GOOGLE_APPLICATION_CREDENTIALS, GOOGLE_CLOUD_STORAGE_BUCKET.

Any S3-compatible service works via the s3 disk — point AWS_ENDPOINT at it.

Queue ​

VariableDefaultNotes
QUEUE_CONNECTIONsyncsync (inline), database (durable), or redis.
QUEUE_TABLEjobsTable for the database connection.
QUEUE_RETRY_AFTER90Seconds before a reserved job is reclaimed.
REDIS_HOST / REDIS_PORT / REDIS_PASSWORD / REDIS_QUEUE_DBnoneFor the redis connection.
QUEUE_NAMEdefaultThe connection's default queue (what a worker without --queue drains).
QUEUE_NAME_OCRocrQueue for OcrJob (config queue.queues.ocr).
QUEUE_NAME_BIOMETRICbiometricQueue for BiometricJob (face match + decision).
QUEUE_NAME_WEBHOOKwebhookQueue for WebhookJob (webhook delivery).
QUEUE_NAME_MAINTENANCEmaintenanceQueue for SessionSweepJob.
QUEUE_NAME_NOTIFICATIONSnotificationsQueue for UserNotificationJob.

With database or redis, every queue that receives jobs needs a worker. One worker can work them all with --queue='webhook,*'. See Self-hosting.

Maintenance & cache ​

VariableDefaultNotes
SESSION_SWEEP_DRIVERscheduleHow expired sessions, retention and screening monitoring run: schedule (the framework scheduler via ark schedule:run from cron, or ark schedule:work), queue (a self-rescheduling job on the queue worker, started once with ark session:sweep --loop; needs an async queue), or off (expire lazily on access only).
SESSION_SWEEP_INTERVAL300Sweep cadence in seconds (minimum 30).
CACHE_STOREmemorymemory, file, redis, or database.

Realtime & push ​

VariableDefaultNotes
REALTIME_TRANSPORTpollingpusher, firebase, firebase-database, polling (no infrastructure; clients refetch), or memory (tests).
REALTIME_POLL_INTERVAL5000Client refetch interval in ms for polling.
REALTIME_PUSHfalsefirebase to push user notifications to registered devices over FCM.
PUSHER_APP_ID / PUSHER_KEY / PUSHER_SECRET / PUSHER_CLUSTERdemo valuesPusher Channels credentials and cluster (e.g. eu, us2).
PUSHER_HOST / PUSHER_PORT / PUSHER_USE_TLSunsetPoint at a self-hosted soketi instead, e.g. 127.0.0.1, 6001, false for the bundled docker-compose.
PUSHER_PUBLIC_HOST / PUSHER_PUBLIC_PORT / PUSHER_PUBLIC_USE_TLSunsetWhere browsers reach that server when it differs from PUSHER_HOST (inside Docker the API uses soketi, browsers localhost).
FIREBASE_ADMINSDKunsetPath to the service-account JSON, instead of the three variables below.
FIREBASE_PROJECT_ID / FIREBASE_CLIENT_EMAIL / FIREBASE_PRIVATE_KEYunsetService-account credentials.
FIREBASE_DATABASE_URLunsetRealtime Database URL for firebase-database.
FIREBASE_API_KEY / FIREBASE_AUTH_DOMAIN / FIREBASE_APP_ID / FIREBASE_MESSAGING_SENDER_IDunsetPublic web config the dashboard and widget connect with.
FIREBASE_VAPID_KEYunsetWeb push key for browser notifications.

Mail ​

MAIL_HOST, MAIL_PORT, MAIL_SECURE, MAIL_USERNAME, MAIL_PASSWORD, MAIL_FROM_ADDRESS: for invitation and verification emails. In dev, a Mailpit container on 1025 works well. MAIL_TEST_ADDRESS is the Arkstack mailer's test recipient.

Dashboard (apps/dashboard/.env) ​

VariableExamplePurpose
VITE_API_ENVdevelopmentSelects which API URL below is used.
VITE_DEV_API_URLhttp://localhost:3100API base in development.
VITE_STAGING_API_URL / VITE_PROD_API_URL / VITE_API_URLnoneAPI base for other environments.
VITE_WEBSITE_URLhttps://arkyc.toneflix.netPublic website; the dashboard's Documentation link opens its /docs.

Playground (apps/playground/.env) ​

VariableExamplePurpose
ARKYC_SECRET_KEYsk_…Project secret key (server-side only).
ARKYC_API_URLhttp://localhost:3100API base the playground proxies to.
ARKYC_WEBHOOK_SECRET(signing secret)Verifies received webhooks (optional).
PORT5174Playground dev-server port.

Released under the MIT License.