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

Default behavior: When you run jac add requests without a version, the package is installed unconstrained and then the actual installed version is queried. A compatible-release spec (~=X.Y) is recorded -- e.g., if pip installs 2.32.5, jac.toml gets requests = "~=2.32". The jac update command also uses this format when writing updated versions back.

[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/venv/ - Project virtual environment
.jac/client/ - Client-side builds
.jac/data/ - Runtime data

[test]#

Defaults for jac test:

[test]
directory = ""          # Test directory (empty = current 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)

[check]#

Defaults for jac check:

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

[check.lint]#

Configure which auto-lint rules are active during jac lint and jac lint --fix. Rules use a select/ignore model with two group keywords:

"default" - code-transforming rules only (safe, auto-fixable)
"all" - every rule, including unfixable rules like no-print

[check.lint]
select = ["default"]          # Code-transforming rules only (default)
ignore = ["combine-has"]      # Disable specific rules
exclude = []                  # File patterns to skip (glob syntax)

To enable all rules including warning-only rules:

[check.lint]
select = ["all"]              # Everything, including no-print

To add specific rules on top of defaults:

[check.lint]
select = ["default", "no-print"]  # Defaults + no-print warnings

To enable only specific rules:

[check.lint]
select = ["combine-has", "remove-empty-parens"]

Available lint rules:

Rule Name	Description	Group
`combine-has`	Combine consecutive `has` statements with same modifiers	default
`combine-glob`	Combine consecutive `glob` statements with same modifiers	default
`staticmethod-to-static`	Convert `@staticmethod` decorator to `static` keyword	default
`init-to-can`	Convert `def __init__` / `def __post_init__` to `can init` / `can postinit`	default
`remove-empty-parens`	Remove empty parentheses from declarations (`def foo()` → `def foo`)	default
`remove-kwesc`	Remove unnecessary backtick escaping from non-keyword names	default
`hasattr-to-null-ok`	Convert `hasattr(obj, "attr")` to null-safe access (`obj?.attr`)	default
`simplify-ternary`	Simplify `x if x else default` to `x or default`	default
`remove-future-annotations`	Remove `import from __future__ { annotations }` (not needed in Jac)	default
`fix-impl-signature`	Fix signature mismatches between declarations and implementations	default
`remove-import-semi`	Remove trailing semicolons from `import from X { ... }`	default
`no-print`	Error on bare `print()` calls (use console abstraction instead)	all

Excluding files from lint:

Use exclude to skip files matching glob patterns:

[check.lint]
select = ["all"]
exclude = [
    "docs/*",
    "*/examples/*",
    "*/tests/*",
    "legacy_module.jac",
]

Patterns are matched against file paths relative to the project root. Use * for single-directory wildcards and ** for recursive matching.

[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
dir = ".jac_cache"  # Cache directory

[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

Prometheus Metrics (jac-scale):

[plugins.scale.metrics]
enabled = true
endpoint = "/metrics"
namespace = "myapp"
walker_metrics = true

See Prometheus Metrics for details.

Kubernetes Secrets (jac-scale):

[plugins.scale.secrets]
OPENAI_API_KEY = "${OPENAI_API_KEY}"
DATABASE_PASSWORD = "${DB_PASS}"

See Kubernetes Secrets for details.

See also jac-scale Webhooks and Kubernetes Deployment for more options.

[scripts]#

Custom command shortcuts:

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

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 --no-cache --session my_session main.jac

# 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"

[check.lint]
select = ["all"]
ignore = []
exclude = []

[plugins]
discovery = "auto"

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

[scripts]
dev = "jac run main.jac"
test = "jac test"
lint = "jac lint . --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

Configuration Reference#

Creating a Project#

Configuration Sections#

[project]#

[dependencies]#

[run]#

[serve]#

[build]#

[test]#

[format]#

[check]#

[check.lint]#

[dot]#

[cache]#

[storage]#

[plugins]#

[scripts]#

[environments]#

Environment Variables#

CLI Override#

Complete Example#

.jacignore#

Format#

Environment Variables#

General#

Storage#

jac-scale: Database#

jac-scale: Authentication#

jac-scale: Webhooks#

jac-scale: Kubernetes#

See Also#