Skip to content

Configuration Reference#

The jac.toml file is the central configuration for Jac projects. It defines project metadata, dependencies, command defaults, and plugin settings.

Creating a Project#

jac create myapp
cd myapp

This creates a jac.toml with default settings.

Configuration Sections#

[project]#

Project metadata:

[project]
name = "myapp"
version = "1.0.0"
description = "My Jac application"
authors = ["Your Name <you@example.com>"]
license = "MIT"
entry-point = "main.jac"
jac-version = ">=0.9.0"

[project.urls]
homepage = "https://example.com"
repository = "https://github.com/user/repo"
Field Description
name Project name (required)
version Semantic version
description Brief description
authors List of authors
license License identifier
entry-point Main file (default: main.jac)
jac-version Required Jac version

[dependencies]#

Python/PyPI packages and Jac plugins:

[dependencies]
requests = ">=2.28.0"
numpy = "1.24.0"
byllm = ">=0.4.8"

[dev-dependencies]
pytest = ">=8.0.0"

[dependencies.git]
my-lib = { git = "https://github.com/user/repo.git", branch = "main" }

Version specifiers:

Format Example Meaning
Exact "1.0.0" Exactly 1.0.0
Minimum ">=1.0.0" 1.0.0 or higher
Range ">=1.0,<2.0" 1.x only
Compatible "~=1.4.2" 1.4.x

[run]#

Defaults for jac run:

[run]
session = ""        # Session name for persistence
main = true         # Run as main module
cache = true        # Use bytecode cache

[serve]#

Defaults for jac start:

[serve]
port = 8000              # Server port
session = ""             # Session name
main = true              # Run as main module
cl_route_prefix = "cl"   # URL prefix for client apps
base_route_app = ""      # Client app to serve at /

[build]#

Build configuration:

[build]
typecheck = false   # Enable type checking
dir = ".jac"        # Build artifacts directory

The dir setting controls where all build artifacts are stored:

  • .jac/cache/ - Bytecode cache
  • .jac/packages/ - Installed packages
  • .jac/client/ - Client-side builds
  • .jac/data/ - Runtime data

[test]#

Defaults for jac test:

[test]
directory = "tests"     # Test directory
filter = ""             # Filter pattern
verbose = false         # Verbose output
fail_fast = false       # Stop on first failure
max_failures = 0        # Max failures (0 = unlimited)

[format]#

Defaults for jac format:

[format]
outfile = ""        # Output file (empty = in-place)
fix = false         # Auto-fix issues

[check]#

Defaults for jac check:

[check]
print_errs = true   # Print errors to console
warnonly = false    # Treat errors as warnings

[dot]#

Defaults for jac dot (graph visualization):

[dot]
depth = -1          # Traversal depth (-1 = unlimited)
traverse = false    # Traverse connections
bfs = false         # Use BFS (default: DFS)
edge_limit = 512    # Maximum edges
node_limit = 512    # Maximum nodes
format = "dot"      # Output format

[cache]#

Bytecode cache settings:

[cache]
enabled = true      # Enable caching

[storage]#

File storage configuration:

[storage]
storage_type = "local"       # Storage backend (local)
base_path = "./storage"      # Base directory for files
create_dirs = true           # Auto-create directories
Field Description Default
storage_type Storage backend type "local"
base_path Base directory for file storage "./storage"
create_dirs Automatically create directories true

Environment Variable Overrides:

Variable Description
JAC_STORAGE_TYPE Storage type (overrides config)
JAC_STORAGE_PATH Base directory (overrides config)
JAC_STORAGE_CREATE_DIRS Auto-create directories ("true"/"false")

Configuration priority: jac.toml > environment variables > defaults.

See Storage Reference for the full storage API.

[plugins]#

Plugin configuration:

[plugins]
discovery = "auto"      # "auto", "manual", or "disabled"
enabled = ["byllm"] # Explicitly enabled
disabled = []           # Explicitly disabled

# Plugin-specific settings
[plugins.byllm]
model = "gpt-4"
temperature = 0.7
api_key = "${OPENAI_API_KEY}"

# Webhook settings (jac-scale)
[plugins.scale.webhook]
secret = "your-webhook-secret-key"
signature_header = "X-Webhook-Signature"
verify_signature = true
api_key_expiry_days = 365

# Kubernetes version pinning (jac-scale)
[plugins.scale.kubernetes.plugin_versions]
jaclang = "latest"
jac_scale = "latest"
jac_client = "latest"
jac_byllm = "none"           # Use "none" to skip installation

See jac-scale Webhooks and Kubernetes Deployment for details.

[scripts]#

Custom command shortcuts:

[scripts]
dev = "jac run main.jac"
test = "jac test -v"
build = "jac build main.jac -t"
lint = "jac check ."
format = "jac format . --fix"

Run with:

jac script dev
jac script test

[environments]#

Environment-specific overrides:

[environment]
default_profile = "development"

[environments.development]
[environments.development.run]
cache = false
[environments.development.plugins.byllm]
model = "gpt-3.5-turbo"

[environments.production]
inherits = "development"
[environments.production.run]
cache = true
[environments.production.plugins.byllm]
model = "gpt-4"

Activate a profile:

JAC_PROFILE=production jac run main.jac

Environment Variables#

Use environment variable interpolation:

[plugins.byllm]
api_key = "${OPENAI_API_KEY}"              # Required
model = "${MODEL:-gpt-3.5-turbo}"          # With default
secret = "${SECRET:?Secret is required}"   # Required with error
Syntax Description
${VAR} Use variable (error if not set)
${VAR:-default} Use default if not set
${VAR:?error} Custom error if not set

CLI Override#

Most settings can be overridden via CLI flags:

# Override run settings
jac run main.jac --no-cache --session my_session

# Override test settings
jac test --verbose --fail-fast

# Override serve settings
jac start --port 3000

Complete Example#

[project]
name = "my-ai-app"
version = "1.0.0"
description = "An AI-powered application"
entry-point = "main.jac"

[dependencies]
byllm = ">=0.4.8"
requests = ">=2.28.0"

[dev-dependencies]
pytest = ">=8.0.0"

[run]
main = true
cache = true

[serve]
port = 8000
cl_route_prefix = "cl"

[test]
directory = "tests"
verbose = true

[build]
typecheck = true
dir = ".jac"

[plugins]
discovery = "auto"

[plugins.byllm]
model = "${LLM_MODEL:-gpt-4}"
api_key = "${OPENAI_API_KEY}"

[scripts]
dev = "jac run main.jac"
test = "jac test"
format = "jac format . --fix"

.jacignore#

The .jacignore file controls which Jac files are excluded from compilation and analysis. Place it in the project root.

Format#

One pattern per line, similar to .gitignore:

# Comments start with #
vite_client_bundle.impl.jac
test_fixtures/
*.generated.jac

Each line is a filename or pattern that should be skipped during Jac compilation passes (type checking, formatting, etc.).

Environment Variables#

General#

Variable Description
NO_COLOR Disable colored terminal output
NO_EMOJI Disable emoji in terminal output
JAC_PROFILE Activate a configuration profile (e.g., production)
JAC_BASE_PATH Override base directory for data/storage

Storage#

Variable Description
JAC_STORAGE_TYPE Storage backend type
JAC_STORAGE_PATH Base directory for file storage
JAC_STORAGE_CREATE_DIRS Auto-create directories

jac-scale: Database#

Variable Description
MONGODB_URI MongoDB connection URI
REDIS_URL Redis connection URL

jac-scale: Authentication#

Variable Description Default
JWT_SECRET Secret key for JWT signing supersecretkey
JWT_ALGORITHM JWT algorithm HS256
JWT_EXP_DELTA_DAYS Token expiration in days 7
SSO_HOST SSO callback host URL http://localhost:8000/sso
SSO_GOOGLE_CLIENT_ID Google OAuth client ID None
SSO_GOOGLE_CLIENT_SECRET Google OAuth client secret None

jac-scale: Webhooks#

Variable Description
WEBHOOK_SECRET Secret for webhook HMAC signatures
WEBHOOK_SIGNATURE_HEADER Header name for signature
WEBHOOK_VERIFY_SIGNATURE Enable signature verification
WEBHOOK_API_KEY_EXPIRY_DAYS API key expiry in days

jac-scale: Kubernetes#

Variable Description Default
APP_NAME Application name for K8s resources jaseci
K8s_NAMESPACE Kubernetes namespace default
K8s_NODE_PORT External NodePort 30001
K8s_CPU_REQUEST CPU resource request None
K8s_CPU_LIMIT CPU resource limit None
K8s_MEMORY_REQUEST Memory resource request None
K8s_MEMORY_LIMIT Memory resource limit None
DOCKER_USERNAME DockerHub username None
DOCKER_PASSWORD DockerHub password/token None

See Also#