Configuration

The hyperstack.toml file is the central configuration for your Hyperstack project. It defines your project metadata, SDK generation settings, build preferences, and stack definitions. The file is created automatically when you run hs init, but you can customize it for advanced use cases.

Creating the Configuration File

The easiest way to create hyperstack.toml is with the CLI:

hs init

This command:

Creates hyperstack.toml with a project name based on your directory
Auto-discovers stacks from .hyperstack/*.stack.json files
Creates a .hyperstack/ directory if it doesn’t exist

You can then customize the generated file for your needs.

File Location

By default, the CLI looks for hyperstack.toml in the current directory. You can specify a different path with the --config flag:

hs --config ./config/hyperstack.toml up

Minimal Configuration

For most projects, you only need a project name:

[project]
name = "my-stack"

The CLI auto-discovers stacks from .hyperstack/*.stack.json files created during cargo build.

Full Configuration Reference

[project]
name = "my-project"
description = "A brief description of your project"
version = "1.0.0"

# SDK generation settings
[sdk]
output_dir = "./generated"                              # Default output for both languages
typescript_output_dir = "./frontend/src/generated"     # Override for TypeScript only
rust_output_dir = "./crates/generated"                 # Override for Rust only
typescript_package = "@myorg/my-sdk"                   # Package name for TypeScript
rust_module_mode = false                               # Generate Rust SDKs as modules by default

# Build preferences
[build]
watch_by_default = true

# Stack definitions (auto-discovered by default, but can be explicit)
[[stacks]]
name = "my-game"
stack = "SettlementGame"                               # Stack name or path to .stack.json
description = "Settlement game tracking"
typescript_output_file = "./src/generated/game.ts"    # Per-stack TypeScript output path
rust_output_crate = "./crates/game-stack"             # Per-stack Rust output path
rust_module = true                                     # Per-stack: generate as module instead of crate

Sections

`[project]` — Project Metadata

Option	Type	Required	Description
`name`	string	Yes	Project name (used for SDK package naming)
`description`	string	No	Project description
`version`	string	No	Project version

`[sdk]` — SDK Generation Settings

Option	Type	Default	Description
`output_dir`	string	`"./generated"`	Default output directory for all SDKs
`typescript_output_dir`	string	`output_dir`	TypeScript SDK output directory
`rust_output_dir`	string	`output_dir`	Rust SDK output directory
`typescript_package`	string	`"hyperstack-stacks/{stack_name}"`	NPM package name for TypeScript SDKs
`rust_module_mode`	boolean	`false`	Generate Rust SDKs as modules (`mod.rs`) instead of standalone crates

Note: When rust_module_mode = true, generated Rust SDKs are created as modules that can be embedded directly in your existing crate. When false, each SDK is generated as a standalone crate with its own Cargo.toml.

`[build]` — Build Preferences

Option	Type	Default	Description
`watch_by_default`	boolean	`true`	Enable file watching for automatic rebuilds during development

`[[stacks]]` — Stack Definitions

Define stacks explicitly for custom naming or per-stack overrides. If not defined, stacks are auto-discovered from .hyperstack/*.stack.json files.

Option	Type	Required	Description
`name`	string	Yes	Stack name (used for SDK generation and CLI commands)
`stack`	string	Yes	Stack name from your Rust code or path to `.stack.json` file
`description`	string	No	Stack description
`typescript_output_file`	string	No	Per-stack TypeScript output file path
`rust_output_crate`	string	No	Per-stack Rust output crate/module directory
`rust_module`	boolean	No	Per-stack override for module vs crate generation

Common Use Cases

Multiple Stacks in One Project

Each stack is a separate #[hyperstack] module that can contain multiple entities. Use multiple [[stacks]] entries when you have separate programs or data sources:

[project]
name = "my-defi-protocol"

[[stacks]]
name = "lending"
stack = "LendingMarket"
description = "Lending pool positions and interest rates"

[[stacks]]
name = "dex"
stack = "DexPool"
description = "DEX liquidity pools and swaps"

Separate SDK Output Directories

[project]
name = "my-project"

[sdk]
typescript_output_dir = "./frontend/src/generated"
rust_output_dir = "./crates/generated"

Custom TypeScript Package Name

[project]
name = "my-project"

[sdk]
typescript_package = "@myorg/hyperstack-sdk"

Rust SDK as Module (for Monorepos)

[project]
name = "my-project"

[sdk]
rust_module_mode = true  # All Rust SDKs generated as modules

Or per-stack:

[[stacks]]
name = "my-game"
stack = "SettlementGame"
rust_module = true
rust_output_crate = "./src/generated"  # Will create mod.rs here

Per-Stack TypeScript Output File

[[stacks]]
name = "game"
stack = "GameState"
typescript_output_file = "./src/game.ts"

Environment Variables

Environment variables override configuration file values:

Variable	Description	Overrides
`HYPERSTACK_API_URL`	Override the API endpoint	Default API URL
`HYPERSTACK_API_KEY`	API key for authentication	(no file override)

Credentials File

Authentication credentials are stored separately from your project configuration in:

~/.hyperstack/credentials.toml

This file contains your API key for accessing Hyperstack Cloud:

api_key = "your-api-key-here"

The credentials file is created automatically when you authenticate via the CLI. Since this file contains sensitive information, it is stored in your home directory and should never be committed to version control.

Validation

Validate your configuration:

hs config validate

This checks:

Required fields are present
File paths are valid
Stack references resolve to valid .stack.json files
No conflicting settings

Next Steps

CLI Commands — Full CLI reference
Your First Stack — Complete tutorial
SDK Reference: Rust — Rust SDK usage and module mode