Arcium.toml - Arcium Docs

Arcium.toml is auto-generated by arcium init and configures the Arcium CLI tooling. It lives at the root of your project alongside Anchor.toml. Most projects only need to edit this file when changing localnet behavior or adding a cluster offset for devnet or mainnet testing.

Localnet configuration

The [localnet] section controls your local development cluster. All required fields are auto-generated by arcium init with sensible defaults.

Field	Type	Required	Default	Description
`nodes`	integer	Yes	`2`	Number of MPC nodes. Minimum: 2
`nodes_ips`	array of `[u8; 4]`	No	Sequential from `172.20.0.100`	IPv4 addresses for each node
`localnet_timeout_secs`	integer	Yes	`60`	Seconds to wait for localnet startup
`backends`	array of string	No	Ignored	Written by the init template but ignored by the CLI

Use the default values unless you need to test against a larger local cluster or a custom Docker network setup.

Choose a local validator

The CLI uses the legacy validator by default. To preview Surfpool after completing the optional installation, select it for each local command:

arcium test --validator surfpool
arcium localnet --validator surfpool

The validator choice is not stored in Arcium.toml. --validator takes precedence over ARCIUM_LOCAL_VALIDATOR; both accept legacy or surfpool. The CLI rejects --validator with a non-local --cluster.

Cluster configuration

The [clusters.<name>] sections map network names to cluster offsets. These entries are used by arcium test --cluster <name> to resolve the cluster offset for testing.

Field	Type	Required	Description
`offset`	integer	Yes	Cluster offset for PDA derivation. See Deployment - Cluster offsets for current values.

The CLI reads these entries when you run commands such as:

arcium test --cluster devnet

For local tests without a --cluster argument, the CLI uses the [localnet] configuration.

Full example

[localnet]
nodes = 2
nodes_ips = [
  [172, 20, 0, 100],
  [172, 20, 0, 101]
]
localnet_timeout_secs = 60
backends = ["Cerberus"] # Ignored by the CLI

[clusters.devnet]
offset = 456

[clusters.mainnet]
offset = 2026

Common mistakes

Issue	Fix
`arcium test --cluster <name>` cannot find a cluster	Add `[clusters.<name>]` with an `offset` field
Tests derive the wrong cluster account	Check that the offset matches the target network
Localnet startup times out	Increase `localnet_timeout_secs` or reduce local resource contention
Custom node IPs do not work	Keep `nodes` and `nodes_ips` lengths aligned

​Localnet configuration

​Choose a local validator

​Cluster configuration

​Full example

​Common mistakes

Localnet configuration

Choose a local validator

Cluster configuration

Full example

Common mistakes