Skip to content

Server Operator Guide

Use this page after Install. It focuses on the supported tidal-server command surface, not on host-specific scheduler or init-system setup.

What The Server Operator Owns

tidal-server is the server operator CLI. It owns:

  • Alembic migrations
  • scan execution
  • FastAPI serving
  • API key management
  • the canonical SQLite database

Supported Commands

The intended runtime surface is:

  • tidal-server db migrate
  • tidal-server scan run
  • tidal-server api serve
  • tidal-server auth ...

Repeated invocation and scheduling are external concerns.

First-Time Bootstrap

After following Install, review:

  • config/server.yaml
  • ~/.tidal/server/.env, or TIDAL_ENV_FILE for an explicit path
  • TIDAL_HOME if you want mutable files outside ~/.tidal

Then run:

tidal-server db migrate --config config/server.yaml
tidal-server auth create --label cli-client-name --config config/server.yaml
tidal-server scan run --config config/server.yaml
tidal-server api serve --config config/server.yaml

If the API should reconcile receipts in the background, set RPC_URL so the API process can start its reconciler.

Scan Execution

Default scan:

tidal-server scan run --config config/server.yaml

Scan with auto-settle enabled for that invocation:

tidal-server scan run --config config/server.yaml --auto-settle --no-confirmation

Scan with token auto-enable enabled for that invocation:

tidal-server scan run --config config/server.yaml --auto-enable-tokens --no-confirmation

When either transaction automation flag is used, the server also needs valid local wallet configuration such as:

  • TXN_KEYSTORE_PATH
  • TXN_KEYSTORE_PASSPHRASE

Operator Actions From The Server Host

Use tidal, not tidal-server, even when you are working directly on the server machine:

export TIDAL_API_BASE_URL=http://127.0.0.1:8787
tidal kick inspect
tidal kick run
tidal logs kicks

If API auth is enabled, create a client key with tidal-server auth create and export TIDAL_API_KEY before using tidal.

Config Notes

Common server settings include:

  • auction_factory_address
  • auction_kicker_address
  • monitored_fee_burners
  • kick

The API bind defaults live in code: tidal_api_host=0.0.0.0 and tidal_api_port=8787. Set them explicitly only when you need a non-default bind.

Most scanner, pricing, multicall, and reconcile tuning also now defaults in code. Only override those via environment variables when you are intentionally tuning a deployment.

Scan auto-settle and token auto-enable are not configured in server.yaml. Enable them explicitly with --auto-settle or --auto-enable-tokens when needed.

For scan-side transaction automation, keep TXN_KEYSTORE_PATH and TXN_KEYSTORE_PASSPHRASE in the service environment. Use --keystore and --password-file only for one-off overrides when running tidal.

API Key Management

Create:

tidal-server auth create --label alice --config config/server.yaml

List:

tidal-server auth list --config config/server.yaml

Revoke:

tidal-server auth revoke alice --config config/server.yaml

The API stores only SHA-256 hashes of keys. The plaintext key is shown once at creation time.

Database Notes

SQLite is the canonical datastore for this repo.

Runtime behavior:

  • journal mode: WAL
  • busy timeout: 30 seconds
  • synchronous mode: NORMAL

That configuration is set in tidal/persistence/db.py.