.env.example

# ============================================================================
# Sandchest — Environment Variables
# ============================================================================
# Copy this file to .env and fill in the required values.
# In production, set these via Fly.io secrets. See apps/api/src/env.ts.
# ============================================================================


# ──────────────────────────────────────────────────────────────────────────────
# API / Control Plane (apps/api)
# ──────────────────────────────────────────────────────────────────────────────

# [Required] PlanetScale MySQL connection string.
# Also used by packages/db for migrations (drizzle-kit).
DATABASE_URL=mysql://sandchest:sandchest@127.0.0.1:3307/sandchest

# [Required] BetterAuth session/token signing key. Use a long random string.
BETTER_AUTH_SECRET=dev-secret-change-me-in-production

# [Required] Resend API key for sending OTP emails.
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

# [Optional] Autumn billing API secret key. Billing is a no-op if unset.
# AUTUMN_SECRET_KEY=

# [Optional] Redis connection URL. Falls back to in-memory if unset.
# REDIS_URL=redis://127.0.0.1:6379

# [Optional] S3 bucket name for artifact and replay event storage.
# ARTIFACT_BUCKET_NAME=sandchest-artifacts-dev

# HTTP server port.
# Default: 3001
# PORT=3001

# Node.js environment mode.
# Default: development
# NODE_ENV=development

# Graceful shutdown drain timeout in milliseconds.
# Default: 30000
# DRAIN_TIMEOUT_MS=30000

# BetterAuth callback base URL. Must match the API's public URL.
# Default: http://localhost:3001
BETTER_AUTH_BASE_URL=http://localhost:3001

# Optional cookie domain for BetterAuth cross-subdomain cookies.
# Leave unset in local development. Production defaults to .sandchest.com.
# BETTER_AUTH_COOKIE_DOMAIN=

# Sender email address for OTP emails via Resend.
# Default: Sandchest Auth <noreply@send.sandchest.com>
# RESEND_FROM_EMAIL=Sandchest Auth <noreply@send.sandchest.com>


# ──────────────────────────────────────────────────────────────────────────────
# Frontend / Dashboard (apps/web — Next.js)
# ──────────────────────────────────────────────────────────────────────────────

# [Required] API URL exposed to the browser (NEXT_PUBLIC_ prefix = client-visible).
# Default: http://localhost:3001
NEXT_PUBLIC_API_URL=http://localhost:3001

# Admin server-side API target used by apps/admin server routes.
# Default: https://api.sandchest.com when unset, so set this locally.
API_URL=http://localhost:3001

# Optional dedicated smoke target for apps/admin /smoke.
# Falls back to API_URL when unset.
# SANDCHEST_SMOKE_BASE_URL=http://localhost:3001


# ──────────────────────────────────────────────────────────────────────────────
# SDK & CLI (packages/sdk-ts, packages/cli, packages/mcp)
# ──────────────────────────────────────────────────────────────────────────────

# [Required for SDK/CLI usage] Sandchest API key (sk_* prefix).
# The SDK reads this as a fallback when no apiKey is passed in options.
# The CLI reads this or from ~/.config/sandchest/config.json.
# SANDCHEST_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx


# ──────────────────────────────────────────────────────────────────────────────
# Node Daemon — Core (crates/sandchest-node)
# ──────────────────────────────────────────────────────────────────────────────
# These are written to /etc/sandchest/node.env on EC2 via user-data.
# Only needed locally if running the Rust node daemon directly.

# Rust tracing log level filter.
# Default: info (production), debug (dev)
# RUST_LOG=debug

# Root data directory for VM images, snapshots, and sandbox working dirs.
# Default: /var/sandchest
# SANDCHEST_DATA_DIR=/var/sandchest

# Unique node identifier. Auto-generated if unset.
# SANDCHEST_NODE_ID=

# gRPC server port for control plane communication.
# Default: 50051
# SANDCHEST_NODE_GRPC_PORT=50051

# API -> node daemon connection for local development.
# Point the local API at a local node daemon. When using plaintext localhost
# gRPC, set NODE_GRPC_INSECURE=1 instead of mTLS credentials.
# NODE_GRPC_ADDR=127.0.0.1:50051
# NODE_GRPC_NODE_ID=00000000000000000000000000000001
# NODE_GRPC_INSECURE=1

# Local control plane -> remote node daemon (for example, local apps/admin and
# apps/api talking to a real Fly-provisioned node). Keep API_URL /
# NEXT_PUBLIC_API_URL on localhost, but point NODE_GRPC_* at the real node and
# use client mTLS credentials copied from Fly secrets into ignored local files.
# NODE_GRPC_ADDR=<real-node-ip-or-host>:50051
# NODE_GRPC_NODE_ID=<real-node-id>
# NODE_GRPC_CA_PATH=/absolute/path/to/certs/fly-ca.pem
# NODE_GRPC_CERT_PATH=/absolute/path/to/certs/fly-client.pem
# NODE_GRPC_KEY_PATH=/absolute/path/to/certs/fly-client.key

# Optional API-side guardrails for hung node RPCs.
# NODE_CREATE_TIMEOUT_MS=30000
# NODE_FILE_TIMEOUT_MS=30000
# NODE_COLLECT_ARTIFACTS_TIMEOUT_MS=30000

# Path to the Linux kernel image used by Firecracker.
# Default: /var/sandchest/images/vmlinux-5.10
# SANDCHEST_KERNEL_PATH=/var/sandchest/images/vmlinux-5.10

# Control plane API URL for callbacks/heartbeat. Optional.
# SANDCHEST_CONTROL_PLANE_URL=


# ──────────────────────────────────────────────────────────────────────────────
# Node Daemon — S3 / Artifact Storage
# ──────────────────────────────────────────────────────────────────────────────

# [Required on node] S3 bucket name for artifact uploads.
# SANDCHEST_S3_BUCKET=sandchest-artifacts-dev

# S3/R2 region. Use 'auto' for Cloudflare R2.
# Default: auto
# SANDCHEST_S3_REGION=auto

# S3-compatible endpoint URL (e.g. for R2). Uses AWS default if unset.
# SANDCHEST_S3_ENDPOINT=

# Static S3 credentials. Uses EC2 instance profile if unset.
# SANDCHEST_S3_ACCESS_KEY=
# SANDCHEST_S3_SECRET_KEY=


# ──────────────────────────────────────────────────────────────────────────────
# Node Daemon — Network
# ──────────────────────────────────────────────────────────────────────────────

# Outbound network interface for TAP device NAT masquerade.
# Default: ens5 (EC2), eth0 (Rust default)
# SANDCHEST_OUTBOUND_IFACE=ens5

# Per-sandbox bandwidth limit in Mbps.
# Default: 100 (dev), 200 (production)
# SANDCHEST_BANDWIDTH_MBPS=100


# ──────────────────────────────────────────────────────────────────────────────
# Node Daemon — Firecracker Jailer
# ──────────────────────────────────────────────────────────────────────────────

# Enable Firecracker Jailer (chroot + seccomp sandbox).
# Default: false (dev), true (production)
# SANDCHEST_JAILER_ENABLED=false

# Path to Firecracker binary.
# Default: /usr/bin/firecracker
# SANDCHEST_FIRECRACKER_BINARY=/usr/bin/firecracker

# Path to Jailer binary.
# Default: /usr/bin/jailer
# SANDCHEST_JAILER_BINARY=/usr/bin/jailer

# Base directory for chroot jails.
# Default: {SANDCHEST_DATA_DIR}/jailer
# SANDCHEST_JAILER_CHROOT_BASE_DIR=/var/sandchest/jailer

# UID/GID to run Firecracker as inside the jail.
# Default: 10000
# SANDCHEST_JAILER_UID=10000
# SANDCHEST_JAILER_GID=10000

# Cgroup version for resource limits (1 or 2).
# Default: 2
# SANDCHEST_JAILER_CGROUP_VERSION=2

# Path to custom seccomp filter JSON. Uses Firecracker built-in filter if unset.
# SANDCHEST_JAILER_SECCOMP_FILTER=

# Create new PID namespace for jailed process.
# Default: true
# SANDCHEST_JAILER_NEW_PID_NS=true


# ──────────────────────────────────────────────────────────────────────────────
# Guest Agent (crates/sandchest-agent)
# ──────────────────────────────────────────────────────────────────────────────
# Only needed when developing the guest agent outside a microVM.

# Enable TCP dev mode instead of vsock (for local development).
# SANDCHEST_AGENT_DEV=1

# TCP port for the agent server in dev mode.
# Default: 50052
# SANDCHEST_AGENT_TCP_PORT=50052

# vsock port for agent communication (inside microVM).
# Default: 52
# SANDCHEST_AGENT_VSOCK_PORT=52

# TCP port the node daemon uses to connect to the agent in dev mode.
# Default: 8052
# SANDCHEST_AGENT_DEV_PORT=8052


# ──────────────────────────────────────────────────────────────────────────────
# CI / CD (GitHub Actions)
# ──────────────────────────────────────────────────────────────────────────────
# These are set as GitHub repository secrets, not in .env files.
# Listed here for documentation purposes only.

# Fly.io access token for flyctl in GitHub Actions deployment.
# FLY_ACCESS_TOKEN=