Core environmental variables

This page lists the environmental variables that actually change in deployment and daily operations: service monitoring, database, API key, limit, external service matching, Compose layout layer and sandbox sidecar. Control of internal system behavior (parallel, re-test, batch size, reading cycle rhythm, etc.) is not available on this page, see Advanced environmental variables。

Most deployments do not require individual settings.

Official use Deployment of Docker Compose When the vast majority of the variables have been filled in by the compose file, you usually only need to .env There are three necessary provisions: POSTGRES_PASSWORD、REDIS_PASSWORD、JWT_SECRET The remaining variables on this page can be viewed as required.

Duration formatting

All length variables (such as ACCESS_TTL、REFRESH_TTL Use the Go duration format: number plus unit embodiment, support s The second, m The minute, h can be combined (such as 1h30m (No of no d Unit: 30 days to write. 720h。

Basic of Service

varied	The default value	Explained
AIVORY_LISTEN	:8787	Service Listening Address: 8787 ports for all network cards by default; can only be written when you want to bind the native device 127.0.0.1:8787。
AIVORY_ENV	development	Operating environmental labels. set up for production A non-dev value will trigger a deployment-level security scan (see below) JWT_SECRET Rules of Initiation).
STATIC_DIR	and empty	When pointing to a built-in SPA front-end directory, the API process serves the front-end page on the same port with the same source.

** How to choose a common hole ** Production deployment must be AIVORY_ENV Established as production Otherwise, part of the security checks that are valid only in the deployment environment will not be enabled. STATIC_DIR Only when you build the front end yourself and want the API process directly to host the static file; do not move it when using the official mirror image. /api) is a recommended form, which can save cross-domain configuration.

Databases and Caching

varied	The default value	Explained
DATABASE_URL	./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)	The database connection string is the default SQLite file path (with the WAL and busy_timeout parameters); to postgres:// Start with PostgreSQL.
REDIS_URL	and empty	Redis connection strings. Use process cache and cohort when left vacant; enable Redis cache, task cohort and stream recovery after setup.
QDRANT_URL	and empty	Qdrant vector library addresses. Disable vector retrieval when left empty, RAG goes the full injection back.
QDRANT_API_KEY	and empty	Access the API key for Qdrant to be consistent with the Qdrant server-side configuration.

DATABASE_URL Examples of two forms:

# SQLite(单机小规模,详见 SQLite 模式文档)
DATABASE_URL="./data/aivory.db?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)"

# PostgreSQL(compose 部署默认形态)
DATABASE_URL="postgres://aivory:你的密码@postgres:5432/aivory"

DATABASE_URL Decides more than a database

DATABASE_URL Is it for postgres:// The prefix is also one of the inputs for determining whether or not it is a deployment environment: Once PostgreSQL is connected, it will be compulsory when it starts. JWT_SECRET Additionally, there is no automatic data migration between SQLite and PostgreSQL, please switch through it before switching. Backup and Migration Exporting the data.

** How to choose a common hole ** Single or small team can go. The SQLite model Zero external dependence; a multi-user production environment recommends a full suite of PostgreSQL + Redis + Qdrant (compose is the default). REDIS_URL The ability to degrade dependent cohorts, such as space-time stream recovery, is implemented within the process, and Redis must be configured when deploying multiple copies. QDRANT_URL Leaving empty does not affect the knowledge base functionality available, only the quality of retrieval degradation to the full text injection, the document volume effect and token consumption will get worse.

Security and Session

varied	The default value	Explained
JWT_SECRET	and empty	API key for issuing access/renewing tokens.Rules for initiating verification see the warnings below.
ACCESS_TTL	30m	Access tokens are valid in the Go duration format.
REFRESH_TTL	720h	The renewal token is valid for 720 hours, which is 30 days.
ALLOWED_ORIGINS	http://localhost:5173,http://127.0.0.1:5173	Allow cross-domain access to the origin white list of the API, logic separation. Only front-end and back-end separation deployment is required; single container co-source deployment is not required.

JWT_SECRET Rules for Startup Screening

Not set in the development environment JWT_SECRET The service automatically generates a random temporary API key. ** Each reset will result in all login sessions being invalidated. ** When the system “seems to be a deployment environment”AIVORY_ENV A non-dev value, or DATABASE_URL When it is PostgreSQL, an API key of at least 32 characters must be explicitly set, otherwise the service will refuse to start.

openssl rand -base64 48

Do not replace the API key at the time of production: All users' login status will immediately disappear after replacement.

** How to choose a common hole **: ACCESS_TTL Shortening the window reduces token leakage, but increases the frequency of refreshment. REFRESH_TTL Decide how long the user has not been in need of re-logging. ALLOWED_ORIGINS It is a hole that newcomers often step: the same source deployment (recommended) is completely unmatched; only when the front end is deployed separately to another domain name, it is necessary to add the front end origin and write the full text. scheme://host[:port] Do not take the path and the end slope.

Storage and limits

varied	The default value	Explained
UPLOAD_DIR	./data/uploads	User uploaded file storage directory.
ARTIFACT_DIR	./data/artifacts	Storage directory of generated products (code running output documents, etc.).
BACKUP_DIR	./data/backups	Storage directory of backup documents.
MAX_UPLOAD_BYTES	52428800	A single file upload hard limit is 50MB by default.Administrator background can also tighten by image/file separately within this limit.
MAX_BACKUP_BYTES	21474836480	The upper limit of imported backup size is 20GiB by default.
DAILY_MESSAGE_LIMIT	200	Maximum number of messages per user per day.
IMAGE_DAILY_LIMIT	30	The maximum number of images generated per user per day.

** How to choose a common hole ** Three catalogues are included. ./data Following, Compose deployment corresponds to the host. DATA_DIR Hang the volume, make sure that the volume has enough disk space and includes backup policies. MAX_UPLOAD_BYTES It is the server hard upper limit, the image / file limit of the admin console can only be smaller than it, can not be enlarged; if enlarged here, also synchronize the reverse proxy request upper limit (such as Nginx's). client_max_body_size Otherwise, the request will be stopped by the agent first. The reverse proxy。DAILY_MESSAGE_LIMIT 与 IMAGE_DAILY_LIMIT is global default, adjusting the quota for individual users Users and quota in the operation.

External Services

varied	The default value	Explained
SEARCH_PROVIDER	and empty	Internet searches, such as serper It can also be configured in the admin console.
SEARCH_API_KEY	and empty	Search for the API key.
SEARCH_BASE_URL	and empty	Custom address for the search backend (used when built or proxy gateway).
EMBEDDING_BASE_URL	and empty	The API address for the embedding service, the OpenAI compatible interface.
EMBEDDING_API_KEY	and empty	The API key in the service.
EMBEDDING_MODEL	text-embedding-3-small	Name of embedding model.
EMBEDDING_DIM	1536	Embedded in vector dimensions.
MINERU_API_URL	and empty	MinerU service address for OCR resolution for scanned PDFs.compose https://mineru.net。
MINERU_API_KEY	and empty	The API key.
SANDBOX_BASE_URL	and empty	Code sandbox sidecar address.compose by default http://sandbox:8000。
SANDBOX_API_KEY	and empty	Share API key for communication with sandbox sidecar.compose uses shared values by default aivory-bundled-sandbox。
ENABLE_MOCK_PROVIDER	false	Input from compose to enable the built-in demo model (without a real model API to experience the interface).

EMBEDDING_DIM must be consistent with the actual dimension of the model

The vector repository is set up according to a fixed dimension, EMBEDDING_DIM 与 EMBEDDING_MODEL When the actual output dimensions are not consistent, vector writing and retrieval will go wrong. Changing the embedding model must synchronize the value, and the old vector in the library is not compatible with the new dimension, requiring the knowledge base index to be rebuilt. text-embedding-3-small It corresponds to 1536 V.

** How to choose a common hole ** Search and embedded services are not necessary, and corresponding functions (network search, vector retrieval) are automatically degraded or unavailable when not configured. SEARCH_* Support in the admin console configuration, environmental variables and the background can be selected, the backdrop configuration advantage is that the change does not need to restart the container, see Overview of admin console The sandbox two variables left empty code execution function is not available; when with the official compose, sidecar has been launched with the suite, no manual setting is required, but** if the sandbox is exposed to a non-intranet environment, make sure to SANDBOX_API_KEY Change from a shared default to a randomly strong API key ** (sidecar side synchronization modified, see Section 8), see for more details. Deployment of Sandbox。ENABLE_MOCK_PROVIDER Only for demonstration and verification deployment, production environment maintenance false。

OAuth Multi-Domain Names

varied	The default value	Explained
OAUTH_CALLBACK_BASE_URL	and empty	When deploying multiple domains, fix the only one used for OAuth recall. scheme://host。
OAUTH_RETURN_ORIGINS	and empty	After cross-domain logging is completed, permission to jump back to the origin white list, with a distinction.

** How to choose a common hole ** A single domain name deployment requires no setup either. When the same set of services is accessed through multiple domains and an OAuth provider (such as GitHub/Google) only permits registering a fixed referral address, you can use the OAUTH_CALLBACK_BASE_URL Set to the domain name you registered with the provider; the user will be able to jump back to the original domain name after logging in from other domains, adding those domains. OAUTH_RETURN_ORIGINS Origin outside the white list will not be skipped, which is a security design that prevents redirecting from opening up, and leaks will represent “successful login but not returning to the original page.”

Compose of layer variables (.env)

The following variables are written in the compose root directory. .env In the document, by docker-compose.yml Launch the injection of containers, not the configuration directly read by the Aivory process:

varied	The default value	Explained
IMAGE_OWNER	hjxwz123	The owner of the mirror. ghcr.io/<IMAGE_OWNER>/aivory-app Change the name of the mirror when using the self-built mirror image warehouse.
IMAGE_TAG	latest	The production environment recommends locking specific version numbers (such as 2.2.0 rather than latest。
POSTGRES_USER	aivory	PostgreSQL user name.
POSTGRES_PASSWORD	It is obligatory	PostgreSQL password, no default value, must be filled in for the first deployment.
POSTGRES_DB	aivory	Name of PostgreSQL database.
REDIS_PASSWORD	It is obligatory	Redis password, no default value, must be filled in for the first deployment.
QDRANT_API_KEY	aivory-internal-qdrant	Qdrant’s API key, the app container shares the same value as the qdrant container.
JWT_SECRET	It is obligatory	Directly transmitted to the app container, see Section 3.
DATA_DIR	./data	Host data directory, which holds persistent data to each container.

** How to choose a common hole **: POSTGRES_PASSWORD、REDIS_PASSWORD、JWT_SECRET There are no default values. .env Lack of filling any one will lead to boot failure, which is a deliberate anti-stain design. POSTGRES_* After modification, compose will use them to spell out the app container. DATABASE_URL No need to manually write the link. QDRANT_API_KEY Though there is a default value, it is safe as long as the Qdrant port is not exposed outside the compose network; if you expose Qdrant separately, change to a strong random value. DATA_DIR The directed directory is the entire permanent state (database, upload, vector, backup), the entire directory can be copied when migrating the host. Deployment of Docker Compose。

Sandbox Sidecar operating variables

The following variables affect aivory-sandbox-sidecar Containers (code sandbox controls), with section 5 on the app side SANDBOX_BASE_URL/SANDBOX_API_KEY is a two-end configuration.sidecar pulls the isolated container to execute code through Docker for each session, the overall architecture is seen Deployment of Sandbox User side functions. The Python Sandbox。

Mirrors and Container Resources

varied	The default value	Explained
SANDBOX_IMAGE	aivory-sandbox:latest	Runtime mirrors used by the session container.
SANDBOX_NETWORK	none	The network mode of the session container is completely disconnected by default; set to bridge It only enables runtime networking (such as a pip installation package).
SANDBOX_MEMORY	2g	Memory upper limit for individual session containers. Document rendering class tasks are less than memory and are not recommended below the default value.
SANDBOX_CPUS	1	CPU quota for a single session container.
SANDBOX_PIDS_LIMIT	256	Maximum number of processes for a single session container, fork bombs.
SANDBOX_NOFILE_ULIMIT	1024:1024	The file descriptor for the session container is ulimit (soft: hard).
SANDBOX_PULL_ON_START	Empty and closed.	empty and not 0/false When the sidecar starts. docker pull Runtime mirroring once, avoiding the first session of the new server failure due to lack of mirroring.Drawing is the best effort, failure only logs do not block the start.

Certified

varied	The default value	Explained
SANDBOX_API_KEY	and empty	sidecar requires all requests to carry a matching Bearer API key, which is rejected if the verification fails. ** When the API key is empty and not explicitly exempted, the sidecar directly refuses to start. ** (fail-closed)。
SANDBOX_ALLOW_NO_AUTH	Empty and closed.	Explicit exemption without API key launch, only for trusted localhost developers. 1/true/yes/on Four values take effect, and other writing (including False/no/off All are considered non-immunity.

Do not turn off sandbox authentication in any network environment.

sidecar directly drives the host's Docker, equivalent to the host's root permission. SANDBOX_ALLOW_NO_AUTH It should only appear in a completely non-external native development environment; the production environment must be set to be strongly random. SANDBOX_API_KEY and consistent with the app side (Section 5).

Execution of overtime and session recovery

varied	The default value	Explained
SANDBOX_EXEC_TIMEOUT_CAP_MS	600000	Execute a single overtime hard drive upper limit (10 minutes). each call overtime set by admin console will be limited to that value; lowering will tighten the ceiling.
SANDBOX_DEFAULT_EXEC_TIMEOUT_MS	120000	The caller does not specify the default single-execution overtime (120 seconds) for overtime and will not silently inherit the 10 minute hard upper limit.
SANDBOX_IDLE_TTL_SECONDS	1800	How long after the session is free is recovered, 30 minutes by default.
SANDBOX_IDLE_TTL_CAP_SECONDS	86400	Free operating hard drive upper limit for recovering TTL (24 hours). admin console can shorten the recovery window, but never exceed that upper limit.
SANDBOX_MAX_SESSIONS	16	The maximum number of session containers that survive at the same time.
SANDBOX_MAX_CONCURRENT_EXECS	4	The maximum number of code executed at the same time.
SANDBOX_MAX_CONCURRENT_CREATES	2	The maximum number of sessions held simultaneously is created.
SANDBOX_QUEUE_TIMEOUT_SECONDS	150	The request for the longest waiting time in a parallel cohort returns the overtime error.

File System and Disk Protection

varied	The default value	Explained
SANDBOX_READ_ONLY_ROOTFS	1	The session container root file system only reads (the anti-disk is full of attacks). /workspace、/tmp、$HOME tmpfs with a upper limit of size. 0 或 false Closed and not recommended.
SANDBOX_TMPFS_SIZE	256m	/tmp The upper limit of the size of tmpfs.
SANDBOX_WORKSPACE_SIZE	512m	Work area can be written. /workspace Maximum size of tmpfs. old name SANDBOX_WORKSPACE_TMPFS_SIZE It remains in force as a compatible name.
SANDBOX_DISK_SIZE	Empty and closed.	Session container can write layers of disk quota (such as 1g Docker overlay2 is required to drive storage and enable pquota/prjquota when it is not satisfied docker run Errors are and are therefore applied as optional and as hard as possible (the parameter is automatically removed if it fails to try again).
SANDBOX_SECCOMP_PROFILE	Empty and closed.	Specify a fixed seccomp profile file path for the session container (the path must be read within the sidecar container). docker run。

Export and product limits

varied	The default value	Explained
SANDBOX_MAX_OUTPUT_BYTES	32768	Execute the cut up limit for stdout/stderr (32KB) at a time.
SANDBOX_MAX_ARTIFACT_BYTES	20971520	The upper limit for the size of a single product file (20 MiB).
SANDBOX_MAX_TOTAL_ARTIFACT_BYTES	52428800	The upper limit of total size for all products is executed at a time (50 MiB).
SANDBOX_MAX_FILES_PER_EXEC	20	A maximum number of documents that can be uploaded at a time.
SANDBOX_MAX_UPLOAD_BYTES	20971520	The upper limit for the size of a single file to the sandbox (20 MiB).
SANDBOX_MAX_ARCHIVE_BYTES	209715200	The upper limit for the size of the work area archive tar package (200MiB). /workspace If the value is exceeded by skipping the archive (log), the session itself is still recovered normally.

Persistence of work areas

varied	The default value	Explained
SANDBOX_LOCAL_STORAGE_DIR	Empty and closed.	Local disk archive backend directory, zero dependence alternative outside of S3/OSS. After setting up, the workplace tar package is written into the directory, which needs to be hanged as volumes to restart the reservation across the sidecar. local The back end is not valid, and the session is recovered, which means that the work area is lost. The path can only be specified by the operations via the environment variable and does not accept remote callers.

** How to choose a common hole ** Official compose has filled in the available default value for sidecar, most scenarios just need to care. SANDBOX_API_KEY (in accordance with the app side) and whether it is disabled SANDBOX_NETWORK Disconnecting the network (bridge This means that untrustworthy code can be outsourced to the package, please evaluate the risk after opening again. SANDBOX_MEMORY/SANDBOX_MAX_SESSIONS/SANDBOX_MAX_CONCURRENT_EXECS Estimated by "host memory ≥ session number × single session memory", the theoretical peak of the default 16 session × 2g exceeds the capacity of the small machine, and the small memory machine should be lowered first SANDBOX_MAX_SESSIONS.sidecar internal reading cycle rhythm, S3/OSS overtime repeat, request body size, etc. SANDBOX_S3_*、SANDBOX_MAX_BODY_BYTES and entering Advanced environmental variables。

Changes in front-end construction period

varied	The default value	Explained
VITE_API_BASE	/api	The front end calls the base path of the API, in ** During construction ** Injection: Changes to the full address of the API service only when the front-and-back deployment is separated (the front-end is statically hosted elsewhere).

** How to choose a common hole ** This is a building-period variable, not a run-time variable: changing it has to rebuild the front-end product, it has no effect on the official mirror setting that has been built. /api Yes; only when front-end deployment to independent domain name/CDN https://api.example.com/api This type of complete address, while remembering to add the front end origin on the server side ALLOWED_ORIGINS (Paragraph of the third paragraph).

The next step.

• The first deployment from to start quickly.与Operation for the first time Repeat the standard process.
• Domain Name and HTTPS Access The reverse proxy与 Cloudflare。
• Internal preference index. Advanced environmental variables。