> For the complete Linea documentation index, see [llms.txt](/llms.txt). > Agents can fetch this page as Markdown at [https://docs.linea.build/stack/how-to/run-local-lineth-stack.md](https://docs.linea.build/stack/how-to/run-local-lineth-stack.md). # Run a local Lineth Stack This quickstart guide walks you through starting a local [Lineth](/protocol/reference/zero-knowledge-glossary#lineth)**Lineth** (Formerly the Linea Stack) The open-source ZK-rollup stack, codebase, and technical protocol that's the foundation of Linea Mainnet. Operators can deploy this stack to launch their own Ethereum-compatible L2 or L3 networks. chain, deploying the required contracts, and verifying L1 finality. You will choose how the stack settles to L1 and how it proves blocks. This quickstart is intended for operators, architects, and engineers evaluating how the stack behaves before designing a production deployment. caution This quickstart is not a production deployment model. It uses local-dev identity and mTLS material, generated quickstart wallets, dev-proof mode by default, and quickstart-only verifier configuration. Do not reuse generated or committed quickstart material in production. ## What this quickstart runs The quickstart runs a local Lineth Stack [L2](/protocol/reference/zero-knowledge-glossary#layer-2-l2)**Layer 2 (L2)** A separate blockchain that increases transaction speed and throughput, while deriving its security from Ethereum. L2s rely on Ethereum for data availability by posting their transaction data onto Ethereum. with these services. For component details, see [Deployment components](/stack/deployment/core-components). - Linea Besu [sequencer](/protocol/reference/zero-knowledge-glossary#sequencer)**Sequencer** The component of Linea's execution client responsible for ordering, building, and executing blocks in a way that allows the subsequent ZK proof to be made. It's implemented as a set of plugins extending Linea Besu, including the tracer and conflator. There's typically one sequencer per network. and an L2 Besu [RPC follower](/protocol/reference/zero-knowledge-glossary#rpc-node)**RPC node** A full node configured to expose JSON-RPC APIs to applications and users, optionally behind load balancers and RBAC. RPC nodes can be optimized for low-latency access to near-head state, or configured as archive nodes for historical queries. - [Maru](/protocol/reference/zero-knowledge-glossary#maru)**Maru** Linea's consensus layer client. Maru runs on validator nodes to coordinate block production with the execution layer, manage validator sets and consensus participation, and provide peer-to-peer networking for block propagation, using the Quorum Byzantine Fault Tolerance (QBFT) consensus algorithm. consensus layer client - [Shomei](/protocol/reference/zero-knowledge-glossary#shomei)**Shomei** A state manager that communicates with Linea Besu, via a corresponding plugin, to maintain and update network state using sparse Merkle trees. Shomei is the component behind Lineth's state manager. state manager - [Coordinator](/protocol/reference/zero-knowledge-glossary#coordinator)**Coordinator** Linea's coordination module for batching, proof generation, and finality submission. The coordinator monitors block production, manages conflation deadlines, batches blocks, combines batches into blobs, orchestrates execution, compression, and aggregation proofs, and submits proofs and data to the finalization layer. for batching, proof orchestration, L2 message data anchoring, and submissions - [Postman](/protocol/reference/zero-knowledge-glossary#postman)**Postman** The service that relays messages between the canonical message service contracts on Linea and Ethereum. Postman listens for calls made to the contract on one network and passes the submitted information to the contract on the other network. It's currently centralized, but is intended to be decentralized. for L1-to-L2 and L2-to-L1 message relay - [Web3Signer](/protocol/reference/zero-knowledge-glossary#web3signer)**Web3Signer** An open-source, remote signing service that externalizes private key management from nodes. Web3Signer integrates with enterprise-grade key stores and exposes HTTP-based signing APIs so consensus and execution clients can obtain signatures on blocks, attestations, and transactions without directly holding the private keys. for generated runtime signer keys used by the coordinator and Postman - [Prover](/protocol/reference/zero-knowledge-glossary#prover)**Prover** The Lineth component that generates ZK proofs of state transitions, handling proof-generation requests from the coordinator and Linea Besu. The prover produces three types of proofs (execution, compression, and aggregation) and combines them into a zk-SNARK that the finalization layer verifies. Provers may be scaled horizontally to meet throughput requirements. for proof generation - Local L2 Blockscout block explorer, including API backend and frontend The L2 is always local. What differs between modes is where the stack settles its L1 finality: public Sepolia, which is the primary path, or a local development L1 that the stack runs for you for easier testing. ## Prerequisites The following is required for both Sepolia and local L1 mode: | Requirement | Minimum | | --- | --- | | Docker | v24+ | | Docker Compose | v2.19+ | | Shell | POSIX-compatible shell such as `sh`, `bash`, or `zsh` | | RAM, dev-proof mode | 8 GB Docker Desktop minimum | | RAM, partial-proof mode | 32 GB minimum assigned to Docker; 128 GB recommended | | Disk | About 30 GB free | The following is required only for Sepolia mode: | Requirement | Minimum | | --- | --- | | Sepolia RPC | Reliable HTTPS endpoint: a paid RPC plan, or your own Sepolia node | | Sepolia ETH | Enough for deployment and runtime account top-ups | note These requirements may change as the Lineth Stack evolves. See the latest values in the [monorepo](https://github.com/LFDT-Lineth/lineth-monorepo/tree/main/docs/getting-started/lineth-stack). For the normal quickstart flow, you do not need host Node.js, pnpm, Foundry, or Gradle; the required tooling runs in Docker. The Lineth prover image is `linux/amd64` only. On Apple Silicon, choose the Dev proofs prover mode, which is the default. Partial proving is much slower on M-series machines. ## Steps ### Section 1. Configure and start the stack Clone the [Lineth monorepo](https://github.com/LFDT-Lineth/lineth-monorepo), then run the wizard: ```bash git clone https://github.com/LFDT-Lineth/lineth-monorepo.git cd lineth-monorepo/docs/getting-started/lineth-stack ./scripts/start.sh --wizard ``` The wizard asks a series of questions, writes your `.env` file, and can start the stack for you. If a `.env` file already exists, the wizard backs it up before making changes. The wizard asks for: 1. **L1 mode**: `Local L1` or `Sepolia`. See [Choose your L1 mode](#choose-your-l1-mode) below. 2. **Prover mode**: `Dev proofs` (default, fast dummy proofs for laptops and demos) or `Partial prover` (real partial proving, resource-heavy). 3. **Sepolia L1 RPC URL**: asked only when you choose Sepolia mode. 4. **Next step**: what to do after writing `.env`: - Save `.env` only, and do not start now. - Save `.env` and start the stack, reusing any existing quickstart containers and volumes. - Save `.env`, clear existing quickstart state, then start the stack. This runs `./scripts/reset.sh` first. - Cancel and leave `.env` unchanged. When you choose to start, the wizard runs the same guided boot flow as `./scripts/start.sh --tail`: it checks ports, checks the L1 network, generates runtime wallets, Web3Signer key config, L2 genesis, and service configuration, pulls Docker images, starts services, deploys contracts, prints links, waits for first finality, and prints the result. #### Choose your L1 mode Both modes exercise L1 finality. Sepolia is the primary path, since it settles against public Sepolia and exercises real public L1 finality. Local L1 is offered for ease of testing when you want a faster, self-contained run. - **Sepolia** settles against public Sepolia. It needs a reliable Sepolia RPC endpoint, which can be either a paid RPC plan or your own local Sepolia node, plus a funded deployer account. Check current Sepolia gas conditions in your RPC provider or explorer before you start, and make sure the deployer has enough ETH to cover deployment and runtime top-ups at current gas. The quickstart currently requires at least 2 ETH on the generated deployer; 3 ETH gives more room during Sepolia congestion. - **Local L1** is offered for ease of testing. The stack runs a quickstart-scoped Besu and Teku L1 inside the same Compose stack, so there is no external RPC, no real ETH, and no public gas spend, which makes it handy for repeatable development, CI, and demos. The wizard clears `L1_RPC_URL` for this mode. Local L1 mode has no Etherscan and no public settlement; bridge and finality flows still run against contracts deployed on the local L1. #### Fund the deployer in Sepolia mode On a clean Sepolia checkout, the first start generates an encrypted deployer keystore under `artifacts/accounts/deployer-keystore/`, prints the generated deployer address and funding requirement, then exits before the Docker pull and startup. Fund that generated Sepolia address, then start again: ```bash ./scripts/start.sh --tail ``` Keep the terminal open until it reports that first L1 finalization was observed. ### Section 2. Verify first finality After first finality, check status and links: ```bash ./scripts/status.sh ./scripts/links.sh ``` Treat the run as successful when `status.sh` confirms: - Deployed addresses are present - Coordinator is reachable - Prover request and response counts are above zero - A blob transaction appears as Data Availability only - A separate finalization transaction advances `rollup currentL2BlockNumber` caution Do not treat `Submit Blobs` as finalization. Blob submission publishes data for data availability. Only a successful `finalizeBlocks` transaction advances the Sepolia rollup `finalized` state. In Sepolia mode, finalization may appear on Sepolia Etherscan as method selector `0x755bc62f` instead of a decoded name. For the current quickstart rollup contract, that selector corresponds to `finalizeBlocks(bytes,uint256,FinalizationDataV4)`. Etherscan may display the struct argument as `tuple` because Solidity structs are ABI-encoded as tuples. ### Section 3. (Optional) Run traffic and bridge smokes Local L2 traffic and bridge smoke scripts are optional verification steps after first finality. If your shell reports `permission denied` for a script, make it executable from the Lineth Stack directory, for example `chmod +x scripts/*.sh scripts/traffic-generation/*.sh scripts/smoke-test/*.sh`, then retry. Run local L2 traffic when you want visible Blockscout activity: ```bash ./scripts/traffic-generation/send-l2-test-tx.sh ./scripts/traffic-generation/send-l2-erc20-transfer.sh ./scripts/traffic-generation/generate-l2-erc20-traffic.sh start ./scripts/traffic-generation/generate-l2-erc20-traffic.sh logs ./scripts/traffic-generation/generate-l2-erc20-traffic.sh stop ``` The demo `ERC20Example` token is not part of base boot. Traffic and ERC20 bridge smoke scripts deploy or reuse it on demand. Run bridge smoke tests when you want to verify message relay and TokenBridge flows: ```bash ./scripts/smoke-test/smoke-bridge-message.sh ./scripts/smoke-test/smoke-bridge-erc20-l1-to-l2.sh ./scripts/smoke-test/smoke-bridge-erc20-l2-to-l1.sh ./scripts/smoke-test/smoke-bridge-message-l2-to-l1.sh ``` These scripts cover generic message relay in both directions and ERC20 TokenBridge deposit and withdrawal. They do not test ETH withdrawals. In Sepolia mode, bridge smokes spend real Sepolia gas. ### Section 4. Generated files The quickstart writes generated runtime files under `artifacts/`. These include generated wallets, Web3Signer key config, L2 genesis files, rendered service configuration, deployment addresses, and timing data. Do not edit these files manually during a normal run. Use `./scripts/reset.sh` to regenerate them. Keep `.env` as the single runtime config file, and do not commit `.env` or files under `artifacts/`. ### Section 5. Export evidence Export a local support bundle when you need files to share or archive: ```bash ./scripts/export-output.sh ``` The command writes `lineth-output/`, including addresses, useful links, finality status, smoke-test status if smoke tests were run, deploy logs, and timing evidence. The output directory is ignored by git. ### Section 6. Stop or reset Stop the stack while keeping state: ```bash docker compose --env-file versions.env --env-file .env --profile stack-partial-prover stop ``` The raw Compose commands use `--profile stack-partial-prover` because it is the quickstart's main Compose profile. The default `PROVER_DEV_OVERRIDE=true` still runs dev-proof behavior inside that profile. Add `--profile local-l1` when stopping a stack started in local L1 mode. Wipe generated artifacts, Docker volumes, chain data, and deploy caches: ```bash ./scripts/reset.sh ``` `./scripts/reset.sh` preserves the generated Sepolia deployer keystore by default, so funded test ETH is not stranded by routine local resets. Use `./scripts/reset.sh --forget-deployer` only when you intentionally want a new generated Sepolia deployer. ## Advanced ### Configure `.env` manually The wizard is the recommended path, but you can configure the quickstart by hand if you prefer to edit `.env` directly or script the setup. Copy the example file, set the values for your mode, then start with `--tail`: ```bash cp .env.example .env $EDITOR .env ``` For Sepolia mode, set: ```bash L1_MODE=sepolia L1_RPC_URL=https://sepolia.infura.io/v3/ ``` For local L1 mode, set: ```bash L1_MODE=local PROVER_DEV_OVERRIDE=true ``` In local L1 mode, `L1_RPC_URL` can stay empty and Sepolia deployer settings are ignored. Then start the stack: ```bash ./scripts/start.sh --tail ``` ### Advanced debugging Use raw Compose logs only when debugging. The official start flow is the wizard or `./scripts/start.sh --tail`. The `stack-partial-prover` profile name is the quickstart Compose profile name; it does not mean `PROVER_DEV_OVERRIDE=false` is enabled. ```bash docker compose --env-file versions.env --env-file .env --profile stack-partial-prover logs -f --tail=120 ``` Add `--profile local-l1` when reading raw Compose logs for a stack started in local L1 mode, especially if you need local L1 service logs. For a narrower service log view: ```bash docker compose --env-file versions.env --env-file .env --profile stack-partial-prover logs -f --tail=120 \ deploy-contracts coordinator prover postman sequencer shomei l2-node-besu ``` Reattach to the guided progress view with: ```bash ./scripts/watch.sh ``` ## Known limitations - This quickstart is monorepo-bound. Deploy tooling uses contracts and scripts from the repository checkout. - Sepolia is the supported public L1 finality path. Using another external L1 requires configuration and timing review. - Local L1 mode provides local L1 finality for development and testing; it does not prove public Sepolia finality. - L1 contracts are owned by the generated deployer account. Timelock and Security Council flows are out of scope. - Dev-proof mode is the recommended evaluation path. Partial proving is opt-in and resource-heavy. - Full proving is out of scope. - This quickstart supports Rollup mode only. - The verifier setup is quickstart-only and does not represent production verifier configuration. - ERC20 bridge deposit and withdrawal smokes are included; ETH withdrawal smoke is not included. ## Next steps - Review the [Trust model](/stack/evaluate/trust-model). - Compare [deployment models](/stack/evaluate/deployment-models). - Understand [Data Availability and finalization](/stack/deployment/data-availability-finalization). - Review the [protocol components](/stack/deployment/core-components).