Skip to main content

Run Visor on a Linux host

Run Visor directly on the host as a regular process. Postgres can still come from Docker or any managed provider — only Visor itself runs as a native binary here.

Prerequisites​

Pick a deployment root and lay the files out as follows. The absolute paths below are what you put into config.yaml.

/opt/tss-wrapper/
├── tss-wrapper-svc            # Visor binary (built in the next step)
├── config.yaml                # Visor config
└── binary/
    ├── tss                    # TSS binary          -> tss.binary_path
    └── configs/
        ├── tss.yaml           # TSS binary config   -> tss.config_path
        └── certs/             # certificates dir    -> tss.certificates_path

Requirements:

  • tss.binary_path must be an absolute path to an executable file. Visor launches it with tss.binary_params for default mode and, during tasks, re-launches it with --config <tss.config_path>.
  • tss.config_path is the TSS binary's own YAML. Visor mutates parties.list here during a reshare, and the timechanger task rewrites timing fields in it. Start from the config you produced in Configuration file.
  • tss.certificates_path must be a directory writable by Visor and readable by the TSS binary. Party certificates are written as <domain>.crt. The initial certificates come from TLS certificates.

Matching config.yaml snippet:

config.yaml
tss:
  binary_path: "path/to/binary/tss"
  binary_params: ""
  api_params: ""
  config_path: "path/to/binary/tss/tss.yaml"
  certificates_path: "path/to/binary/tss/certs"
  core_address: "bridge1..."

See Configuration file for the full field reference.

1. Build Visor​

From a clone of the tss-wrapper-svc repo:

go build -o tss-wrapper-svc .
install -m 0755 tss-wrapper-svc /opt/tss-wrapper/tss-wrapper-svc

2. Start Postgres (if you don't already have one)​

Any Postgres instance works; the upstream repo bundles one for convenience:

docker compose -f build/docker-compose.yaml up -d db

This exposes Postgres on localhost:5435 with:

  • user: tss-wrapper
  • password: tss-wrapper
  • db: db

Make sure db.url in your config.yaml matches, for example:

config.yaml
db:
  url: postgres://tss-wrapper:tss-wrapper@localhost:5435/db?sslmode=disable

For alternative Postgres setups, see Set up database.

3. Passing the config file​

Every tss-wrapper-svc subcommand accepts -c / --config and defaults to ./config.yaml:

tss-wrapper-svc service run --config /opt/tss-wrapper/config.yaml
tss-wrapper-svc service run -c /opt/tss-wrapper/config.yaml
tss-wrapper-svc service migrate up   -c /opt/tss-wrapper/config.yaml
tss-wrapper-svc service migrate down -c /opt/tss-wrapper/config.yaml

4. Apply DB migrations​

Run once against each fresh database:

cd /opt/tss-wrapper
./tss-wrapper-svc service migrate up -c ./config.yaml

This creates Visor's epochs, latest_block and tasks tables.

5. Run Visor​

cd /opt/tss-wrapper
./tss-wrapper-svc service run -c ./config.yaml

You should see the orchestrator log started default mode once Visor has launched the TSS binary.

6. Verify​

  • HTTP gateway:
curl http://localhost:8080/
  • gRPC:
grpcurl -plaintext localhost:9090 list
  • Logs should include the orchestrator line started default mode and observer lines for events consumed from Bridgeless-core.

7. Run Visor as a systemd unit​

/etc/systemd/system/tss-wrapper.service
[Unit]
Description=TSS Visor service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/opt/tss-wrapper
ExecStart=/opt/tss-wrapper/tss-wrapper-svc service run -c /opt/tss-wrapper/config.yaml
Restart=on-failure
RestartSec=5s

[Install]
WantedBy=multi-user.target

Enable and inspect:

systemctl daemon-reload
systemctl enable --now tss-wrapper
journalctl -u tss-wrapper -f
info

Visor will drive the TSS binary end-to-end from this point on. Epoch transitions trigger auto_resharing automatically — the manual flow documented in Key resharing is only needed for one-off operations or disaster recovery.