Skip to content
Arete
For the complete documentation index optimized for AI agents, see llms.txt or llms-full.txt. A markdown version of this page is available by appending .md to the URL or sending Accept: text/markdown.

Configuration

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /building-stacks/configuration.md.

arete.toml is the strict, reviewable project manifest. It declares authored artifacts, dependency intent, SDK targets, and output locations. arete.lock records the exact immutable registry and artifact identities selected by a4 install.

Create a Manifest

Section titled “Create a Manifest”
Terminal window
a4 init

Initialization writes manifest_version = 1 and may discover exact StackManifest and ProgramSpec artifacts. It never infers dependency edges: add a workspace dependency explicitly when an authored artifact should also produce an SDK.

Minimal Manifest

Section titled “Minimal Manifest”
manifest_version = 1


[project]
name = "my-project"
private = true

Dependency Example

Section titled “Dependency Example”
manifest_version = 1


[project]
name = "my-analytics-app"
private = true


[install]
allow_outside_project = false


[sdk]
targets = ["typescript", "rust"]


[sdk.typescript]
output_dir = "./src/generated"
package = "@my-org/arete-generated"


[sdk.rust]
output_dir = "./crates/generated"
module_mode = true
crate_prefix = "my_app"


[sdk.python]
output_dir = "./python/generated"
module_mode = false
package_prefix = "my_app"


[dependencies.stacks.ore]
source = { registry = "ore" }
version = "^1.4.0"


[dependencies.programs.spl-token]
source = { registry = "spl-token" }
version = "^4.0.0"
targets = ["typescript"]


[dependencies.programs.spl-token.outputs]
typescript = "./src/generated/spl-token"


[authoring.stacks.local-indexer]
manifest = "./.arete/LocalIndexer.stack-manifest.json"
artifact_roots = ["./.arete"]
deployment_name = "local-indexer"


[dependencies.stacks.indexer]
source = { workspace = "local-indexer" }

Registry dependencies require a SemVer requirement. A source has exactly one of registry, path, or workspace; path dependencies select an exact ProgramSpec or StackManifest. Workspace sources refer to a same-kind key under [authoring].

Default outputs are namespaced by dependency kind:

  • TypeScript: <output_dir>/stacks/<alias> and <output_dir>/programs/<alias>
  • Rust: <output_dir>/stacks/<prefix>-<alias>-stack and <output_dir>/programs/<prefix>-<alias>-program
  • Python: <output_dir>/stacks/<prefix>-<alias>-stack and <output_dir>/programs/<prefix>-<alias>-program

This permits a stack and standalone program to share an alias. Aliases remain unique within each kind. A dependency-level outputs value is an exact path override and does not receive the automatic kind directory.

Install and Update

Section titled “Install and Update”
Terminal window
a4 install
a4 install --locked
a4 install --dry-run
a4 install stack ore@^1.4.0
a4 install program spl-token@=4.0.2 --ts
a4 update
a4 update stack ore

A saved package add updates arete.toml, resolves the complete graph, stages all outputs, and commits outputs plus arete.lock together. Use --no-save for deliberate one-off generation through the same exact registry resolver.

Authoring and Deployment

Section titled “Authoring and Deployment”

Rust DSL compilation produces ProgramSpec, LiveSpec, and StackManifest artifacts. Authoring declarations give those exact artifacts stable project names:

Terminal window
a4 up local-indexer
a4 up ./.arete/LocalIndexer.stack-manifest.json
a4 sdk create --manifest ./.arete/LocalIndexer.stack-manifest.json --ts

Artifact roots are explicit read capabilities for files referenced by a local StackManifest. Paths are resolved relative to the manifest, and output paths stay within the project unless both the manifest and CLI opt in.

Validation

Section titled “Validation”
Terminal window
a4 config validate

Validation is offline. It checks strict keys, source and workspace types, local artifact closure, output collisions, path policy, and lock freshness.

Environment Variables

Section titled “Environment Variables”

Environment variables override configuration file values:

VariableDescriptionOverrides
ARETE_API_URLOverride the API endpointDefault API URL
ARETE_API_KEYAPI key for authentication(no file override)

Credentials File

Section titled “Credentials File”

Authentication credentials are stored separately from your project configuration in:

~/.arete/credentials.toml

This file contains your API key for accessing Arete 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

Section titled “Validation”

Validate your configuration:

Terminal window
a4 config validate

This checks:

  • Required fields are present
  • File paths are valid
  • Legacy stack references resolve to supported composite input files
  • No conflicting settings

Validation does not deploy, bind endpoints, publish generated packages, or configure DNS. Package publication and provider-neutral DNS/CDN handoff remain operator responsibilities.

Next Steps

Section titled “Next Steps”