crudo

Crudo serves configuration-defined JSON HTTP APIs backed by SQLite or PostgreSQL. TOML declares routes, parameterized SQL, setup, authentication, limits, CORS, ALTCHA, and optional deterministic public-address derivation. It is not an ORM, migration framework, payment processor, or x402 settlement service.

Documentation · Configuration reference · Repository

Requirements and install

Use a current Rust toolchain. Install the published crate:

cargo install crudo
crudo --help

From a checkout, build and invoke the resulting binary explicitly:

cargo build --release
./target/release/crudo --help

SQLite needs no separate server. PostgreSQL needs a reachable PostgreSQL database and URL.

60-second start

Copy the minimal example, start it, then verify it in another terminal:

cp config/minimal.toml Crudo.toml
# Installed binary:
crudo
# From a checkout instead: cargo run --
curl -i http://127.0.0.1:3000/v1/health
curl -i -H 'content-type: application/json' -d '{"name":"first"}' http://127.0.0.1:3000/v1/items

The minimal configuration creates crudo.db, listens on 127.0.0.1:3000, and mounts its API below /v1.

Configuration map

By default Crudo reads ./Crudo.toml; select a reviewed file or HTTPS URL with crudo --config PATH. Configuration is strict: unknown static fields fail startup. ${NAME} is expanded before TOML parsing; missing, empty-name, or unclosed variables fail startup, and there is no fallback or escaping syntax.

Test and verify

cargo test
E2E_BACKEND=sqlite cargo test --test e2e -- --ignored
E2E_BACKEND=postgres DATABASE_URL='postgres://…' cargo test --test e2e -- --ignored
docker compose run --build --rm e2e-sqlite
docker compose run --build --rm e2e-postgres   # Docker PostgreSQL test (starts its dependency)

See Docker operations for the repository's exact container commands and database setup.

Store demo

config/store.toml requires DATABASE_URL, WALLET_MNEMONIC, ALTCHA_SECRET, ALTCHA_KEY_SECRET, ADMIN_PASSWORD_HASH, PUBLIC_API_URL, and PAYMENT_PAY_TO. Generate an Argon2 password hash with the project's password-hashing flow, generate independent random ALTCHA secrets of at least 32 bytes, keep the mnemonic/passphrase in a secret manager, set PUBLIC_API_URL to the public API base, and use a Base-compatible address for PAYMENT_PAY_TO.

It seeds a fresh development demo database; it does not upgrade an older schema. Recreate an existing demo database after schema changes. Top-ups create demo credit; x402 responses only construct payment requirements. Neither verifies nor settles payments. The configured x402 destination is Base-only and is generated from the payment-method table; transaction external_id is unique per user, and monetary amounts are integer cents subject to the configured cap and each payment method's units_per_cent conversion.

The separately hosted frontend is at demo-crudo.github.io and its source is demo-crudo/demo-crudo.github.io. Its config.js supplies the default API URL; the visible control is a runtime override. Crudo does not serve or hardcode the frontend. Configure exact CORS origins in Crudo.

Production checklist

• Use an explicit reviewed config, least-privilege database credentials, backups, and managed schema changes.
• Terminate TLS, bind privately where possible, and configure only trusted proxy CIDRs and exact CORS origins.
• Set realistic limits; use proxy/network rate limiting for public and multi-replica deployments.
• Keep mnemonics, passphrases, ALTCHA values, database URLs, and password hashes in a secret manager.
• Do not deploy the store demo unchanged; remove demo top-ups and add independent payment verification/settlement.

Read the getting-started guide, security guide, configuration reference, and complete template.

License

MIT