Write a SpecConfig
Overview
A job specification defines how Bacalhau should execute your workload. This guide provides a complete reference of all supported options, configurations, and their valid values.
Basic Structure
A job specification is a JSON document with the following structure:
Field Reference
Job Level Fields
Name
string
Yes
-
Alphanumeric with - and _
Type
string
Yes
batch
batch, service, daemon, ops
Count
integer
No
1
1 or greater
Priority
integer
No
0
0-100
Namespace
string
No
default
Valid DNS label
Labels
object
No
{}
Key-value string pairs
Tasks
array
Yes
-
Array of task objects
Types
These are the types of jobs:
batch: Run once and completeservice: Run continuously with specified replica countdaemon: Run continuously on all matching nodesops: Run once on all matching nodes
Task Configuration
Tasks define the actual work to be performed. Each task requires:
Engine configuration (how to run)
Resource requirements (what it needs)
Data handling (inputs/outputs)
Inside tasks, there are a number of fields.
Task Level Fields
Name
string
Yes
-
Alphanumeric with - and _
Engine
object
Yes
-
Engine configuration
Resources
object
Yes
-
Resource requirements
InputSources
array
No
[]
Array of input sources
ResultPaths
array
No
[]
Array of result paths
Network
object
No
{"Type": "none"}
Network configuration
Timeouts
object
No
-
Timeout settings
Env
object
No
{}
Key-value string pairs
Meta
object
No
{}
Key-value string pairs
Additionally, there are sub-fields to fill in.
Engine Types
docker: Docker container executionwasm: WebAssembly module execution
Engine Configuration
Docker Engine Parameters
Image
string
Yes
Docker image name
Entrypoint
array
No
Container entrypoint
Parameters
array
No
Command parameters
WorkingDirectory
string
No
Working directory
EnvironmentVariables
object
No
Environment variables
Ports
array
No
Port mappings
Example:
Common Edge Cases:
Images without default entrypoints require explicit entrypoint
Environment variables with spaces or special characters need proper escaping
Working directory must exist in container
Large images may exceed node storage limits
WASM Engine Parameters
EntryModule
string
Yes
WASM module path
EntryPoint
string
Yes
Exported function name
Parameters
array
No
Function arguments
EnvironmentVariables
object
No
Environment variables
Example:
Storage Types
ipfs: IPFS content (you must provide your own IPFS endpoint)s3: Amazon S3 storagelocal: Local filesystemurlDownload: HTTP/HTTPS URLss3PreSigned: Pre-signed S3 URLs
Network Types
none: No network access (default)http: Limited HTTP/HTTPS accessfull: Unrestricted network access
Publisher Types
ipfs: Publish to IPFSs3: Upload to S3local: Store locallynoop: Discard results
Resource Requirements
Resource Fields
CPU
string
Yes
Decimal
0.1 to node max
Memory
string
Yes
Size + Unit
1MB to node max
Disk
string
Yes
Size + Unit
10MB to node max
GPU
string
No
Integer
0 to node max
Example:
Data Handling
Input Source Fields
Source.Type
string
Yes
One of: ipfs, s3, local, urlDownload, s3PreSigned, inline
Source.Params
object
Yes
Source-specific parameters
Target
string
Yes
Absolute mount path
Alias
string
No
Friendly identifier
Source Type Parameters
IPFS:
S3:
URL:
Inline:
Example:
This can accept multiple sources - for example:
Network Configuration
Timeout Configuration
Validation and Testing
Pre-Submission Validation
You can test your job schema by running the validatecommand. E.g.
Test Runs
Bacalhau also supports --dry-runfor testing, though this is only done locally. It does not test against the network.
Troubleshooting Guide
Common Error Messages
Resource Errors
Solution: Check node capabilities and adjust requests
Network Errors
Solution: Verify network policy and domain lists
Timeout Errors
Solution: Adjust timeouts or optimize job
Was this helpful?